Merge branch 'develop-docs' into develop-host-model

.github/workflows/gh_pages.yml

@@ -0,0 +1,127 @@
+# Build and deploy documentation to GitHub Pages
+name: GitHub Pages
+
+on: [ push, pull_request ]
+
+env:
+  DEFAULT_BRANCH: "release"
+
+jobs:
+  build-and-deploy:
+    name: Build and deploy to gh-pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Debugging information
+        run: |
+          echo "github.ref:" ${{github.ref}}
+          echo "github.event_name:" ${{github.event_name}}
+          echo "github.head_ref:" ${{github.head_ref}}
+          echo "github.base_ref:" ${{github.base_ref}}
+          set -x
+          git rev-parse --abbrev-ref HEAD
+          git branch
+          git branch -a
+          git remote -v
+          python -V
+          pip list --not-required
+          pip list
+
+      # Clone and set up the old gh-pages branch
+      - name: Clone old gh-pages
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          set -x
+          git fetch
+          ( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
+          rm -rf _gh-pages/.git/
+          mkdir -p _gh-pages/branch/
+
+      # If a push and default branch, copy build to _gh-pages/ as the "main"
+      # deployment.
+      - name: Build and copy documentation (default branch)
+        if: |
+          contains(github.event_name, 'push') &&
+          contains(github.ref, env.DEFAULT_BRANCH)
+        run: |
+          set -x
+          mkdir -p _build/html/versions
+
+          # create two copies of the documentation
+          # 1. the frozen version, represented as vX.X in the version switcher
+          docker build -t musica -f docker/Dockerfile.docs .
+          id=$(docker create musica)
+          docker cp $id:/build/docs/sphinx tmpdocs
+          docker rm -v $id
+          version=$(sed -nr "s/^release = f'v(.+)\{suffix\}'.*$/\1/p" docs/source/conf.py)
+          mv tmpdocs _build/html/versions/${version}
+
+          # 2. stable, represented as vX.X (stable) in the version switcher
+          # edit conf.py to produce a version string that looks like vX.X (stable)
+          docker build -t musica -f docker/Dockerfile.docs --build-arg SUFFIX=" (stable)" .
+          id=$(docker create musica)
+          docker cp $id:/build/docs/sphinx tmpdocs
+          docker rm -v $id
+          mv tmpdocs _build/html/versions/stable
+          # Delete everything under _gh-pages/ that is from the
+          # primary branch deployment.  Excludes the other branches
+          # _gh-pages/branch-* paths, and not including
+          # _gh-pages itself.
+          find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' ! -path '_gh-pages/versions*' -delete
+          rsync -a _build/html/versions/stable/* _gh-pages/
+          mkdir -p _gh-pages/versions
+          rsync -a _build/html/versions/* _gh-pages/versions
+          # mv docs/switcher.json _gh-pages
+
+      # If a push and not on default branch, then copy the build to
+      # _gh-pages/branch/$brname (transforming '/' into '--')
+      - name: Build and copy documentation (branch)
+        if: |
+          contains(github.event_name, 'push') &&
+          !contains(github.ref, env.DEFAULT_BRANCH)
+        run: |
+          set -x
+          docker build -t musica -f docker/Dockerfile.docs .
+          id=$(docker create musica)
+          docker cp $id:/build/docs/sphinx tmpdocs
+          docker rm -v $id
+          brname="${{github.ref}}"
+          brname="${brname##refs/heads/}"
+          brdir=${brname//\//--}   # replace '/' with '--'
+          rm -rf   _gh-pages/branch/${brdir}
+          rsync -a tmpdocs/ _gh-pages/branch/${brdir}
+
+      # Go through each branch in _gh-pages/branch/, if it's not a
+      # ref, then delete it.
+      - name: Delete old feature branches
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          set -x
+          for brdir in `ls _gh-pages/branch/` ; do
+              brname=${brdir//--/\/}   # replace '--' with '/'
+              if ! git show-ref remotes/origin/$brname ; then
+                  echo "Removing $brdir"
+                  rm -r _gh-pages/branch/$brdir/
+              fi
+          done
+
+      # Add the .nojekyll file
+      - name: nojekyll
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          touch _gh-pages/.nojekyll
+
+      # Deploy
+      # https://github.com/peaceiris/actions-gh-pages
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _gh-pages/
+          force_orphan: true

CMakeLists.txt

@@ -28,6 +28,7 @@ option(MUSICA_ENABLE_TESTS "Builds tests that ensures each enabled MUSICA compon
 option(MUSICA_ENABLE_MPI "Enable MPI parallel support" OFF)
 option(MUSICA_ENABLE_OPENMP "Enable OpemMP support" OFF)
 option(MUSICA_ENABLE_MEMCHECK "Enable memory checking" OFF)
+option(MUSICA_BUILD_DOCS "Build the documentation" OFF)
 
 cmake_dependent_option(
   MUSICA_ENABLE_TUVX "Builds TUV-x, a photolysis calculator library" ON "MUSICA_BUILD_FORTRAN_INTERFACE" OFF)
@@ -91,6 +92,10 @@ endif()
 
 include(dependencies)
 
+if(MUSICA_BUILD_DOCS)
+  add_subdirectory(docs)
+endif()
+
 ################################################################################
 # Tests
 if(MUSICA_ENABLE_TESTS)

docker/Dockerfile.docs

@@ -0,0 +1,33 @@
+FROM fedora:37
+
+RUN dnf -y update \
+    && dnf -y install \
+        doxygen \
+        gcc-c++ \
+        gcc \
+        gdb \
+        git \
+        cmake \
+        make \
+        lcov \
+        valgrind \
+        python3 \
+        python3-pip \
+    && dnf clean all
+
+COPY . /musica/
+
+RUN pip3 install -r /musica/docs/requirements.txt
+
+ARG SUFFIX=""
+ENV SWITCHER_SUFFIX=$SUFFIX
+
+RUN echo "The suffix is '$SWITCHER_SUFFIX'"
+
+RUN mkdir /build \
+      && cd /build \
+      && cmake -D MUSICA_BUILD_DOCS=ON \
+               /musica \
+      && make docs
+
+WORKDIR /build

docs/CMakeLists.txt

@@ -0,0 +1,20 @@
+################################################################################
+# Sphinx
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/source)
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+
+add_custom_command(
+  OUTPUT ${SPHINX_INDEX_FILE} __fake_file_to_ensure_this_always_run
+  COMMAND 
+    ${SPHINX_EXECUTABLE} -b html
+  ${SPHINX_SOURCE} ${SPHINX_BUILD}
+  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+  MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
+  COMMENT "Generating documentation with Sphinx"
+  # run this command each time. This way we don't have to keep track of each individual rst file
+  BuildDocs
+)
+
+add_custom_target(docs ALL DEPENDS ${SPHINX_INDEX_FILE} Doxygen)

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,5 @@
+sphinx
+sphinx-book-theme
+sphinx-copybutton
+sphinx-design
+sphinxcontrib-bibtex

docs/source/_static/custom.css

@@ -0,0 +1,41 @@
+.sd-card-img-top {
+  width: 33% !important;
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+  margin-top: 10px;
+}
+
+.download-div {
+  display: flex;
+  flex-direction: row;
+  justify-content: space-around;
+  margin-bottom: 1rem;
+}
+
+.download-button {
+  display: inline-block;
+  padding: 10px 20px;
+  background-color: #3498db;
+  color: white;
+  border: none;
+  border-radius: 5px;
+  text-align: center;
+  text-decoration: none;
+  font-size: 16px;
+  cursor: pointer;
+  transition: background-color 0.3s;
+}
+
+.transparent-image > img {
+  background-color: unset !important;
+}
+
+.download-button:hover {
+  background-color: #2980b9;
+}
+
+blockquote {
+  padding: unset;
+  border-left: unset;
+}