Setting up Sphinx documentation¶
This page illustrates how to set up Sphinx with automatic API documentation for your Python code and host it on GitHub Pages.
The corresponding repository is https://github.com/nichd-bspc/documentation-template. It has an example Python module along with the source for this documentation.
Initial setup¶
This section describes how to initially set up your documentation.
Dependencies¶
First, create an environment with dependencies. Here we happen to be using conda but pip, venv, apt, homebrew are other options.
For reference, here are the contents of requirements.txt from the repo:
# This is requirements.txt
make # sphinx builds a makefile that we use
sphinx # need sphinx itself
sphinx-autoapi # extension for automatically documenting code
To use this file:
conda create -p ./env --file requirements.txt
conda activate ./env
Run sphinx-quickstart¶
Since this template is intended to illustrate documentation living alongside
a Python package, we create a doc subdirectory and run
sphinx-quickstart from there to set up the directory structure.
We also assume that the Python module is living next to doc, in
a src directory. Check the repo to see how this was
set up.
mkdir doc
cd doc
sphinx-quickstart
# "y" to separate source and build directories
# Entered author and project title
# Otherwise used defaults
This will set up the directory structure. the contents of doc should look like this:
├── build # Built html will eventually go here
├── make.bat # Used for windows
├── Makefile # Main makefile to use
└── source # ReST source and config go here
├── conf.py # Default config file, ready to edit
├── index.rst # Default index file, ready to edit
├── _static # Empty for now, CSS can go here
└── _templates # used for themes and templates (advanced)
Build docs¶
In the doc directory, you should now be able to run:
make html
At the end you’ll get a message, The HTML pages are in build/html. Open
build/html/index.html in a web browser to see the docs.
From here on out it’s a matter of tweaking configuration and actually writing the documentation.
Next steps¶
Take a look around these docs. Click the “Page source” link in the footer of the page to see the ReStructured Text input used to generate this page or any other pages in these docs.