Creating Manuals Using RST and Sphinx: Base Documents

This article is part of a series documenting the process of creating manuals using reStructuredText and Sphinx. See the whole list of articles.

In a Sphinx project, ‘base documents’ are like the skeleton of a manual. In a table of contents, they’ll show up as the chapter headings.

Save base documents with master file

These base documents need to be in the same directory as your master file (by default called index.rst), and they need to have the file extension that you entered into the sphinx-quickstart script.

Create master file and base documents for each manual

If you’ll be setting up multiple manuals in RST and Sphinx, I recommend that you create a master file and base documents for every manual. This is because:

  • Variables need to be specified in each base document to reliably propagate through a manual when you build it.
  • Because of the master file format that Sphinx uses, base documents need to be located in the same directory as the master file.

Assign a directory to each manual

Sphinx makes some weird assumptions that can trip up anyone trying to create a more complicated setup for the first time:

  • The configuration file is named conf.py.
  • conf.py is in the same directory as the master file.

The problem: if you’re writing multiple manuals, you’ll need to:

  • Have multiple master files.
  • (potentially) Set different configuration values for each.

My recommendation: assign a directory for each manual. In this directory, create:

  • A configuration file (conf.py).
  • A master file.
  • Base documents.

Inside your base documents

The next post will go into formatting in depth, but here are the basics that you’ll need.

Level 1 Heading

RST uses lines of punctuation to mark a heading. For example, this is what I use for a level 1 heading:

=============
Heading text
=============

The first heading in a base document will be used:

  • As a chapter heading in the table of contents.
  • To designate that punctuation character as a ‘level one’ heading.

The character that you use for each heading level must be consistent. For example, once I use = for a level 1 heading, I must use = for all other level 1 headings. I must use a different character for level 2 headings.

Here are the key requirements:

  • Must use one of these characters: ! ” # $ % & ‘ ( ) * + , – . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
  • Each line of punctuation must have as many or more characters than the heading text.
  • Must include a line of punctuation under the heading text.
  • A line of punctuation above the heading text may be included, but isn’t mandatory.

Recommendation: Create a style guide as you go that specifies the punctuation used in each heading level. Otherwise, confusion is almost guaranteed.

See the heading characters used in Python’s Style Guide.

Links to child documents

To maximise your single-sourcing, I recommend that you put as much of your text as possible into child documents. So your base documents will consist primarily of a level-one heading and links to child documents.

Link to a child document like this:

.. include:: ../children/welcome.rst

The key parts of the statement above are:

  • .. indicates a directive – something that Sphinx needs to recognise as not just text.
  • include tells Sphinx to use the contents of a different file.
  • :: is the standard RST connection between a command and the information Sphinx needs – in this case, a file location and name.

Example base document

====================
Introduction
====================

.. include:: ../children/intro-text.rst
.. include:: ../children/whats-in-user-guide.rst
.. include:: ../children/customer-support-contact.rst

.. include:: variables.rst

Sample project

I’ve created a sample RST/Sphinx project on GitHub, with branches that align to every tutorial article.

To see how base documents look and are included in the master file, have a look at https://github.com/Nomesque/RST-Tutorial/tree/base-documents.

Note that I’ve built a basic HTML output from this project too – navigate to build/doc-kramers-rst-tutorial/html in the above GitHub branch to have a look.

 

Leave a Reply

Your email address will not be published. Required fields are marked *