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