Documenting Your project with Sphinx

Documentation matters.

And documentation that visually helps people find their way through the data, affords people the navigation they need, will help poor overworked slobs like you and I get to the info we need quicker and less stressed.

So I am reviewing a whole slew of areas

  • generating documents from source code
  • API and narrative documentation
  • Testing the docs and doctests
  • customising the look and feel - bootstrap - styleguides
  • Traditional place to start for OSS contributions

Customising Projects all the way

Custom Themes

We might want to build our own custom theme. In fact this is a lot of fun. So the best way is to steal an existing theme, lets say alabaster, and add to our docs directory in _template

Lets say we copy the directory:

~/venvs/book/lib64/python3.6/site-packages/alabaster/

to:

~/projects/mytheme

Then:

ln -s ~/projects/mybook/docs/_templates/mytheme ~/projects/mytheme

We then need to visit the sphinx project, and adjust the conf.py file as:

html_theme = 'mytheme'
html_theme_path = ['_templates/']

Note the the theme path is to the root of the theme directories. And note that we have a symlink to the theme path in our project.

We can later on, turn our theme into a python package and install via pip - just like alabaster was, and it will be available as a name in the html_theme.

Adjusting the templates.

Let’s just make a quick change to layout.html in mytheme, by say adding “Helloworld” to the footer, re run it and - yes we have a working theme.

Now we want to find the basic theme - that everything else derives from. This is in the site-packages/sphinx/themes/basic directory.

I want to add a nice “next page” link to my docs, to keep the flow of the book working. There is a hint in alabaster:

{# Disable base theme's top+bottom related navs; we have our own in sidebar #}
{%- block relbar1 %}{% endblock %}
{%- block relbar2 %}{% endblock %}

So what is relbar1 and 2? Lets see if we can find them in basic templates. Yes, in basic/layout.html, there is a relbar macro (yes Jinja2 has macros, which are just functions), and that is called in 2 locations relbar1 and 2.

{%- block relbar1 %}{{ relbar() }}{% endblock %}

So I am going to steal that macro, and use it in my template, and adjust it to look right

Progress on this - look for nextprev macro We can use access keys as well to flip through pages

Customisation

If we look at a template, we can see a lot of Jinja2 template variables, such as {{ theme_font_size }}. These are derived from the theme.conf settings, where the prefix theme_ is appended to each variable in the conf (.ini style)

These varables are then pushed into the jinja tempaltes of sphinx and globally accessible.

We can show this by just adding {{ theme_font_size }} to one of our tempaltes and we will see ‘17px’. Thats how all our conf.py changes are available.

Making changes to theme options. So all the theme options in theme.conf, are then passed into templates as theme_ prefix.

You can change the settings using

html_theme_options = {'nosidebar' : True,
                     'show_related' : True,
                     'font_size': '32px', <<<<<<<<<<<<< theme_font_size
}

Biblio

http://sphinxcontrib-napoleon.readthedocs.org/en/latest/

http://pythonhosted.org/sphinxjp.themes.basicstrap/

http://blog.jetstrap.com/2013/07/less-like-bootstrap/

The dirt simple sphinx approach for all python projects

Autogenerate a API page. Use source link on Then refer to the modules like raw:

:py:mod:`mikado.config'

which will link to the api and source.
So we have a simple, easy way to write prose docs and
still have all that autogenerated goodness.

The details are in the docstrings in the module, but the *context*
is prose in the front end.  SImple and looks good.

How to do the logo thing...

Headings

::

There is a sensible order here - the “thickest” character is hight (# is thicker than = than -) And the higher headings are double underlined, then single underlined

Heading 0 is for Book titles and so forth Do not use unless writing very high level TOCs

Heading 1 is to be the title page for a single doc / module