From 029aaf084bbd57c70dd037c3314adfb18d570bcd Mon Sep 17 00:00:00 2001 From: selimnairb Date: Sat, 14 Dec 2024 12:50:34 -0500 Subject: [PATCH] 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 | 6 ++--- docs/BUILDING.md | 26 +++++++++++++++++++ docs/readthedocs/build-macos.bash | 13 ++++++++++ docs/readthedocs/build.bash | 8 +++--- docs/readthedocs/environment-macos.yml | 20 ++++++++++++++ docs/readthedocs/environment.yml | 1 + .../sphinx/source/fsd/FSD-Extension-VRGrid.md | 4 +-- docs/sphinx/source/fsd/RevisionHistory.md | 1 - 8 files changed, 69 insertions(+), 10 deletions(-) create mode 100755 docs/readthedocs/build-macos.bash create mode 100644 docs/readthedocs/environment-macos.yml diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 1ca423c285..96d855970a 100644 --- a/.readthedocs.yaml +++ b/.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: diff --git a/docs/BUILDING.md b/docs/BUILDING.md index 826d567ac7..40d5bdd9e8 100644 --- a/docs/BUILDING.md +++ b/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 diff --git a/docs/readthedocs/build-macos.bash b/docs/readthedocs/build-macos.bash new file mode 100755 index 0000000000..a549d624b9 --- /dev/null +++ b/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 diff --git a/docs/readthedocs/build.bash b/docs/readthedocs/build.bash index 51f2bf365b..9e28aac4fb 100644 --- a/docs/readthedocs/build.bash +++ b/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 diff --git a/docs/readthedocs/environment-macos.yml b/docs/readthedocs/environment-macos.yml new file mode 100644 index 0000000000..cb33f5b1ce --- /dev/null +++ b/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 diff --git a/docs/readthedocs/environment.yml b/docs/readthedocs/environment.yml index d269cd5f17..0b03f99b08 100644 --- a/docs/readthedocs/environment.yml +++ b/docs/readthedocs/environment.yml @@ -11,6 +11,7 @@ dependencies: - swig - catch2 - unittest-xml-reporting + - doxygen - Sphinx=6.2.1 - numpydoc - breathe diff --git a/docs/sphinx/source/fsd/FSD-Extension-VRGrid.md b/docs/sphinx/source/fsd/FSD-Extension-VRGrid.md index b56910cf1b..72fab65fa0 100644 --- a/docs/sphinx/source/fsd/FSD-Extension-VRGrid.md +++ b/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 -*NH,N*(*i*, *j*) = 8, since refined depths are computed at the -intersections of the grid lines, and ∆*H,N*(*i*,*j*) > 0 is +delta*NH,N*(*i*, *j*) = 8, since refined depths are computed at the +intersections of the grid lines, and delta*H,N*(*i*,*j*) > 0 is required to avoid duplication of points on the edges of the low resolution cells. diff --git a/docs/sphinx/source/fsd/RevisionHistory.md b/docs/sphinx/source/fsd/RevisionHistory.md index 004c8f223b..c0a1e9f2eb 100644 --- a/docs/sphinx/source/fsd/RevisionHistory.md +++ b/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) |