Sphinx Quick-start¶
Check Installation¶
This is a short way to check that both Sphinx and starling-theme were installed:
>>> import sphinx
>>> print(sphinx.__version__)
>>> import starling_theme
>>> print(starling_theme.__version__)
Sphinx-Quickstart¶
During sphinx
installation, a sphinx-quickstart
script should be installed in whatever bin directory your Python installation defaults to.
From the base of your project repository, create a documentation
directory:
mkdir documentation
cd documentation
Within the new documentation directory, run sphinx-quickstart
.
The script prompts the user a series of questions, then creates the configuration file (conf.py
) and respective directories based on the answers.
$ sphinx-quickstart
Welcome to the Sphinx 1.6.3 quickstart utility.
The questions and [default values] for 1.6.3
are listed below, but two deviations from the default values are recommended:
- Answer yes (
y
) when asked if you would like to separate source and build directories. This comes personal preference, but choosing to keep them separate makes for a more clear distinction between code which generates documentation, and the documentation itself. - Answer yes (
y
) to theautodoc
question. This is the setting which creates the documentation for your Python classes and functions by reading the signatures and module docstrings.
> Root path for the documentation [.]:
> Separate source and build directories (y/n) [n]:
> Name prefix for templates and static dir [_]:
> Project name:
> Author name(s):
> Project version []:
> Project release []:
> Project language [en]:
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:
After answering the questions, your documentation directory will contain two directories: build/
and source/
, as well as a Makefile
and make.bat
script.
The source/
directory will also contain a conf.py
file (configuration options for Sphinx), index.rst
(basically your home page), and two empty directories: _static
and _templates
.
Modifying conf.py
to use starling-theme
¶
Open conf.py
using your favorite text editor. Then modify the html_theme
variable to use starling_theme
(notice the underscore _ instead of the hyphen) rather than the default alabaster theme.
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
- html_theme = 'alabaster'
+ html_theme = "starling_theme"
The default Pygments syntax highlighting style can clash with the output, so changing it to something like monokai
is recommended as well.
# The name of the Pygments (syntax highlighting) style to use.
- pygments_style = 'sphinx'
+ pygments_style = "monokai"
Now you’re all set! Running make
will produce documentation using the theme:
make html