How to Use Sphinx for Writing Docs

How to Get the Dependencies

Using Docker

If you are using Docker, then simply pull the docker image specified below:

image: sphinxdoc/sphinx-latexpdf

Then, after running docker run -it <docker-image-name> /bin/bash, install the theme we are using with pip install sphinx_rtd_theme

Using Spack

If you are using Spack to provision dependencies, then follow the steps as such:

111    - cd ${CI_PROJECT_DIR}
112    - spack install --show-log-on-error --no-checksum --yes-to-all singularity-eos+mpi+format%gcc@${SINGULARITY_EOS_GCC_VERSION}^openmpi@${SINGULARITY_EOS_OPENMPI_VERSION}
113    - spack module tcl refresh -y
114    - spack env loads -r -x singularity-eos
115    - source ${CI_PROJECT_DIR}/spack/share/spack/setup-env.sh
116    - source ${CI_PROJECT_DIR}/spack_env/loads
117    - clang-format -version
118    - find ${CI_PROJECT_DIR} -regex '.*\.\(cpp\|hpp\)' | xargs clang-format -style=file -i && git diff --exit-code --ignore-submodules
119
120.sphinx-doc:

from .gitlab-ci.yml

Warning

If you do not have either Docker or Spack locally, you would need to install one of them first.

For Docker, refer to their Get Docker Guide.

For Spack, refer to their Getting Started Guide.

How to Build .rst into .html

After you have the dependencies in your environment, then simply build your documentation as the following:

121  stage: static_analysis
122  variables:

from .gitlab-ci.yml

Note

You can view the documentation webpage locally on your web browser by passing in the URL as file:///path/to/singularity-eos/doc/sphinx/_build/html/index.html

How to Deploy

  1. Submit a PR with your .rst changes for documentation on Github Singularity-EOS

  2. Get your PR reviewed and merged into main

  3. Make sure the pages CI job passes in the CI pipeline

As soon as the PR is merged into main, this will trigger the Pages deployment automatically if the pages CI job passes.

Documentation is available on github-pages and on re-git

More Info.