Creating Manuals Using RST and Sphinx: Child Documents

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

Child documents, or sub-documents, make up the bulk of a project. Think of them as Lego blocks – pieces of various sizes that can be put together to make all sorts of end documents. Each child document answers a single question, or addresses a single topic. For example, Installing Sphinx would typically be a single child document. For more about single sourcing, have a look at The 5 Principles of Single Sourcing in Technical Documentation.

Adding child documents to an RST project

To add a document to a project, you need to know two things:

  • How to tell Sphinx to add a document to a specific place.
  • What sort of structure is permitted.

How to write an RST include directive

To include a child document in a project, you need this directive:

.. include:: <relative path>/<filename>

Let’s break this directive down:

  • .. is what we use in RST to indicate that a directive (a command) follows. Note the space after the two periods.
  • include tells Sphinx to insert the child document where the directive is located.
  • :: is the separator between the command and its data values.
  • <relative path> is the path from the document with the include directive to the directory that the child document is in. In the example below, I’ve used ../_child-documents/, which translates to, ‘go up to this directory’s parent directory, then to the child-documents directory’. If you need a bit more clarity on relative links and how to construct them, have a look at Absolute vs Relative Paths/Links.
  • <filename> is the name of the child document, including its file extension.

Example directive

.. include:: ../_child-documents/install-python.rst

Where to add child documents

You can add a child document pretty much anywhere in an reStructuredText project. That includes in the master file, base documents, and other child documents. You can have a child document that includes a child document that includes more child documents – Sphinx will just keep following the links and pulling in all required files. Just keep in mind that the longer your chains of documents, the longer Sphinx might take to build your project.

Sample project

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

See the child-documents branch of my RST-Tutorial project. Note that only base documents are stored with the master file – others are kept in a separate directory.

 

Leave a Reply

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