How to Use Sphinx for Writing Docs

How to convert a Markdown file to rst

We are using the reStructuredText (rst) format for our documentation. If you have a markdown file you would like to convert to rst, as a first pass, you can have Pandoc convert your file. For example:

pandoc Metadata.md --from markdown --to rst -s -o metadata.rst

Pandoc can be installed easily through a Linux package manager. For example on Ubuntu,

apt install pandoc

will get you the tool.

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-pages, 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.

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

$ 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

More Info.