Techwriter at work blog.

Living and writing documentation at Documatt, small team of programmers that do write documentation too.


Best Sphinx conf.py tips

Over the years writing documentation in Sphinx, I found I do the same tweaks in every Sphinx project’s conf.py again and again. Here are the best ones.

Repeating text snippets

How many times do you type project name in the project documentation? What if the project has to be renamed or use new spelling (e.g., “MyProject” –> “myProject”)? As every programmer I hate repeating things. Constants like project name are ideal candidate to be available from every project document.

In Sphinx, you can append/prepend any reStructuredText markup with rst_epilog or rst_prolog conf.py options. List your common words or sentences as substitution definition in one of them. For example, project name from the project option and commonly used text snippets:

rst_epilog = f'''
.. |project| replace:: {project}
.. |dfb| replace:: Don't forget to backup before proceeding.
'''

and use it anywhere in the docs:

...

In the current release of |project| you have to update dependencies. |dfb|

...

Remove “documentation” from the page title

By default, generated HTML <title> has the value project release documentation. E.g. Tech writer at work 1.0 documentation.

If you don’t have conf.py’s release set, it is e.g., Tech writer at work  documentation (please note two spaces among “work” and “documentation”).

If you don’t like word “documentation” or two-space issue, you have to set custom title in html_title conf.py option. For example, let’s set it to the same value as a project option.

project = 'Tech writer at work blog'

...

html_title = project

Turn off or set different default syntax highlighting

Code examples are highlighted by default syntax highlight language, if not configured otherwise for a particular example. Sphinx default syntax highlighting mode is 'python3'.

Python3 highlighting:

::

    def name():
       print("Hello")

Also Python3 highlighting:

.. code-block::

   from datetime import date
   copyright = f'{date.today().year}, Documatt'

Maybe as Sphinx is mainly used in Python projects, it is reasonable value, but I personally almost always change it to ''none'' that turns off syntax highlighting

highlight_language = 'none'

… until I set it for a particular code-block:::

If you want different highlighting, you have to se it manually:

.. code-block:: javascript

   for (let i = 0; i < 3; i++) {        // shows 0, then 1, then 2
     alert(i);
   }

Comments

comments powered by Disqus