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-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)
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