docs: Update readthedocs config to use Python 3.10; Add macOS version…

… of docs generation script; Add instructions to BUILDING.md describing how to build documentation locally

.readthedocs.yaml

@@ -12,7 +12,7 @@ conda:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.10"
   commands:
     - bash docs/readthedocs/build.bash
 
@@ -21,8 +21,8 @@ build:
 #   configuration: docs/readthedocs/conf.py
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
-formats:
-  - pdf
+#formats:
+#  - pdf
 
 # Optionally declare the Python requirements required to build your docs
 #python:

docs/BUILDING.md

@@ -1,5 +1,25 @@
 # Build instructions
 
+## Documentation
+Documentation are automatically created and published at 
+[readthedocs](https://bag.readthedocs.io). However, if you would like to 
+build the documentation locally, this can easily be done using scripts
+for [Linux](readthedocs/build.bash) or [macOS](readthedocs/build-macos.bash).
+Make sure to run these from the root of the repository.
+
+Once the docs are built, you can access them in the directory 
+`_readthedocs/html`.
+
+To build a PDF of the FSD, run:
+```shell
+cd _readthedocs/html/fsd
+pandoc --pdf-engine=xelatex \
+  index.html FSD-BAGStructure.html FSD-Encapsulation.html \
+  FSD-AxiomaticDefs.html FSD-BAGARB.html FSD-RevisionControl.html \
+  FSD-Extensions.html FSD-Glossary.html FSD-References.html \
+  FSD-Appendices.html RevisionHistory.html -o BAG_FSD_2.0.3.pdf 
+```
+
 ## Docker
 You can build a development Linux container using 
 [Dockerfile.dev](../Dockerfile.dev) by running the following command from the
@@ -8,6 +28,12 @@ repository root directory:
 docker buildx build -t dev/debian/baglib:latest -f Dockerfile.dev .
 ```
 
+To build for a specific architecture, such as AMD64, run:
+```shell
+docker buildx build --platform=linux/amd64 \
+  -t dev/debian/amd64/baglib:latest -f Dockerfile.dev .
+```
+
 To manually build and test inside the development container, run:
 ```shell
 docker run -ti -v ./:/tmp/bag:rw dev/debian/baglib:latest /bin/bash

docs/readthedocs/build-macos.bash

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+wget -q https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -O miniconda.sh
+bash miniconda.sh -b -p $(pwd)/miniconda
+source "$(pwd)/miniconda/etc/profile.d/conda.sh"
+hash -r
+conda env create -q --file docs/readthedocs/environment-macos.yml
+conda activate readthedocs
+cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -B doc-build -S . -DPython3_FIND_STRATEGY=LOCATION -DBAG_BUILD_PYTHON:BOOL=ON -DBAG_BUILD_DOCS:BOOL=ON
+cmake --build doc-build -v
+mkdir -p _readthedocs/html/
+ls -R doc-build/docs/sphinx
+cp -r doc-build/docs/sphinx/* _readthedocs/html/
+ls -R _readthedocs/html

docs/readthedocs/build.bash

@@ -5,9 +5,9 @@ source "$(pwd)/miniconda/etc/profile.d/conda.sh"
 hash -r
 conda env create -q --file docs/readthedocs/environment.yml
 conda activate readthedocs
-cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -B build -S . -DBAG_BUILD_PYTHON:BOOL=ON -DBAG_BUILD_DOCS:BOOL=ON
-cmake --build build -v
+cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -B doc-build -S . -DPython3_FIND_STRATEGY=LOCATION -DBAG_BUILD_PYTHON:BOOL=ON -DBAG_BUILD_DOCS:BOOL=ON
+cmake --build doc-build -v
 mkdir -p _readthedocs/html/
-ls -R build/docs/sphinx
-cp -r build/docs/sphinx/* _readthedocs/html/
+ls -R doc-build/docs/sphinx
+cp -r doc-build/docs/sphinx/* _readthedocs/html/
 ls -R _readthedocs/html

docs/readthedocs/environment-macos.yml

@@ -0,0 +1,20 @@
+name: readthedocs
+channels:
+  - conda-forge
+dependencies:
+  - python=3.9
+  - clangxx_osx-arm64
+  - cmake
+  - ninja
+  - hdf5-static
+  - libxml2
+  - swig
+  - catch2
+  - unittest-xml-reporting
+  - doxygen
+  - Sphinx=6.2.1
+  - numpydoc
+  - breathe
+  - myst-parser
+  - sphinx-automodapi
+  - graphviz

docs/readthedocs/environment.yml

@@ -11,6 +11,7 @@ dependencies:
   - swig
   - catch2
   - unittest-xml-reporting
+  - doxygen
   - Sphinx=6.2.1
   - numpydoc
   - breathe

docs/sphinx/source/fsd/FSD-Extension-VRGrid.md

@@ -135,8 +135,8 @@ file.
 low resolution surface is georeferenced on the southwest corner, and is point 
 referenced. Although not shown here, refined nodes may occupy the east/north 
 bound of the enclosing cell, but not the west/south bound. Note here that 
-*N<sub>H,N</sub>*(*i*, *j*) = 8, since refined depths are computed at the 
-intersections of the grid lines, and ∆*<sub>H,N</sub>*(*i*,*j*) > 0 is 
+delta*N<sub>H,N</sub>*(*i*, *j*) = 8, since refined depths are computed at the 
+intersections of the grid lines, and delta*<sub>H,N</sub>*(*i*,*j*) > 0 is 
 required to avoid duplication of points on the edges of the low resolution 
 cells. 
 

docs/sphinx/source/fsd/RevisionHistory.md

@@ -12,4 +12,3 @@
 | 1.6.2 CR1                       | Added clarification on the interpretation of datum transform parameters | 2017-08-29 |
 | 1.6.3                           | Restored the "extension layers" information from 1.5.1 that inexplicably were lost in the move to 1.6.0 | 2018-05-02 |
 | 2.0.1                           | Added support for georeferenced metadata; Migrate C API to C++14; Add Python API. | 2022-12-01 |
-| ![Block Marker](thin-strip.gif) | | ![Block Marker](thin-strip.gif) |