An introduction to Sphinx¶
Credit: this notebook draws heavily on Carol Willing’s Practical Sphinx tutorial, originally MIT licensed. All modifications made here are also MIT licensed.
Sphinx?¶
The Python documentation generator.
By default, Sphinx assumes input files are created using the reStructuredText format (this quick reference can be handy). But Sphinx is an extensible system, and with a couple of custom extensions, we can:
- Use Markdown, thanks to recommonmark.
- Use Jupyter Notebooks, thanks to nbsphinx.
This is what the class website uses!
The Jupyter Docs¶
Available at jupyter.readthedocs.io:
- Complex set of docs that span multiple projects
- Include sources in reST, Markdown and Jupyter Notebooks.
- Detailed explanations with figures
- Reference documentation for the software
- Notebooks rendered as part of the documentation
Getting Started¶
If you didn’t already, in your class environment, run:
conda install sphinx
conda install -c conda-forge nbsphinx recommonmark ghp-import
Create project folder¶
mkdir my-doc-project
cd my-doc-project
Build docs from your docs root directory¶
Type make
for help on all the possible targets. Typical workflow:
make clean
make html
make linkcheck
To view the docs¶
open _build/html/index.html
Or start a webserver and view¶
python -m http.server
Configuration¶
conf.py
¶
- Use for configuration settings.
- This is a Python file.
- You can execute Python code for custom builds.
conf.py
¶
- themes
- source files
- extensions
Themes in conf.py
¶
Easiest Use the default.
Easy Use another standard theme.
Customize css
, js
and override templates
(jinja2
)
Create your own theme Only do if the above doesn’t meet your needs.
Source files¶
More than .rst
¶
- reStructuredText
.rst
and sometimes.txt
- markdown
.md
- Jupyter notebooks
.ipynb
conf.py
(cont.)¶
Markdown .md
using recommonmark
.¶
# For conversion from markdown to html
import recommonmark.Parser
# Add a source file parser for markdown
source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
}
# Add type of source files
source_suffix = ['.rst', '.md']
conf.py
(cont.)¶
Jupyter notebooks .ipynb
using nbsphinx
extension.¶
extensions = [
'sphinx.ext.mathjax',
'nbsphinx', # This lets us use notebooks
]
# I execute the notebooks manually in advance. If notebooks test the code,
# they should be run at build time.
nbsphinx_execute = 'never'
nbsphinx_allow_errors = True
# Add type of source files
source_suffix = ['.rst', '.md', '.ipynb']
index.rst
¶
Table of Contents using each source file type
.. toctree::
:maxdepth: 2
:caption: Sphinx Tips
installation
configuration.md
content.ipynb
deploy-on-rtd
Github Pages¶
- Host static websites (HTML+JS) directly from a Github Repo!
- https://pages.github.com
- All we need to have is a branch called
gh-pages
that has an HTML build (with anindex.html
file at the start). Github does the rest!
Using Github Pages to post a sphinx site easily¶
Make sure you answer yes
to the question about Github Pages in the
quickstart! If you didn’t, add to your extensions list:
'sphinx.ext.githubpages'
Add this target to the Makefile
. It automates pushing to GitHub
Pages:
.PHONY: github
github: html
ghp-import $(BUILDDIR)/html/
git push -u origin gh-pages
@echo
@echo "Published to Github"
Let’s post our site¶
- Turn our little test into a git repo (
git init, etc...
) - Go to GitHub and create a GH repo for it
- Type:
ghp-import _build/html/
git push -u origin gh-pages
- Go to Settings page and see that Github Pages is enabled.
Once we verify the above works, we can just use, thanks to our above target:
make github
Love your docs!¶
- Many documentation examples esp. Django, Jupyter, Python
- Check out Carol’s documentation examples on GitHub:
https://github.com/willingc
- A minimal documentation example repo https://github.com/willingc/doc-basics
- Anne Gentle’s https://justwriteclick.com/ and https://www.docslikecode.com/articles/
- Eric Holscher http://www.writethedocs.org/ and https://readthedocs.io