How to Use Sphinx for Writing Docs

How to have github build your documentation for you

Github can automatically build your documentation for you through the continuous integration pipeline. After you submit a pull request with your .rst changes for documentation on Github Singularity-EOS, the documentation will automatically get built. You will see a “build and deploy documentation” job at the bottom of the pull request page. If this passes, your documentation will have been generated.

On the bottom left of the documentation page on github-pages, you can select the branch/build of the documentation, one of which should be the branch you wrote your changes on.

Documentation is available on github-pages.

Building documentation locally

While you can rely on the CI to build the documentation associated with your branch, you can also very easily build sphinx documentation locally through python. These instructions also do not require admin access and are usable with shared machines or python distributions.

First, ensure that you are running a modern version of python (i.e. python 3 of some flavor)

$ python --version
Python 3.9.7

Then, use pip to install spinx and the RTD theme

pip install --user sphinx sphinx-rtd-theme

Now, navigate to the ../doc/sphinx directory where a make help shows all of the available ways to build the documentation

:language:bash

$ make help
Sphinx v4.2.0
Please use `make target' where target is one of
  html        to make standalone HTML files
  dirhtml     to make HTML files named index.html in directories
  singlehtml  to make a single large HTML file
  pickle      to make pickle files
  json        to make JSON files
  htmlhelp    to make HTML files and an HTML help project
  qthelp      to make HTML files and a qthelp project
  devhelp     to make HTML files and a Devhelp project
  epub        to make an epub
  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  latexpdf    to make LaTeX and PDF files (default pdflatex)
  latexpdfja  to make LaTeX files and run them through platex/dvipdfmx
  text        to make text files
  man         to make manual pages
  texinfo     to make Texinfo files
  info        to make Texinfo files and run them through makeinfo
  gettext     to make PO message catalogs
  changes     to make an overview of all changed/added/deprecated items
  xml         to make Docutils-native XML files
  pseudoxml   to make pseudoxml-XML files for display purposes
  linkcheck   to check all external links for integrity
  doctest     to run all doctests embedded in the documentation (if enabled)
  coverage    to run coverage check of the documentation (if enabled)
  clean       to remove everything in the build directory

Making the documentation will create a new directory, _build in the sphinx directory along with whichever type of documentation you wanted to build.

For example, building the HTML documentation with make html produces the ../doc/sphinx/_build/html directory with an index.html file that you can point a browser to in order to view the documenation.

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      - goldfiles.tar.gz
112
113.test:
114  stage: build_n_test
115  before_script:
116    - echo "Running on $(hostname)"
117    - section() { echo $'\e[0K'"section_$1:$(date +%s):$2"$'\r\e[0K'"${3+${COLOR_CYAN}$3${COLOR_PLAIN}}"; }
118    - export PYTHONNOUSERSITE=1
119    - export SPACK_DISABLE_LOCAL_CONFIG=true
120    - export SPACK_SKIP_MODULES=true

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    - export TMP_USER_PROJECT_DIR="/tmp/${USER}/${CI_PROJECT_NAME}/${CI_JOB_NAME}"
122    - export PROJECT_TMP_CI_DIR=${PROJECT_TMP_CI_DIR:-${TMP_USER_PROJECT_DIR}}

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

More Info.