Category: Creating Manuals Using RST and Sphinx

Creating Manuals Using RST and Sphinx: Child Documents

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.

Creating Manuals Using RST and Sphinx: Base Documents

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

Creating Manuals Using RST and Sphinx: Master File

A master file controls almost all of the content that will be included in your user manual. It contains a list of your base documents and specifies what your table of contents will look like.

Creating Manuals Using RST and Sphinx: Using sphinx-quickstart

Once you’ve done your planning and have your directory structure figured out, the next step is to start creating your project. You’ll need to create your base directory, use sphinx-quickstart to set up your basic project structure and configuration, and then – if needed – add some extra structure.

Creating Manuals Using RST and Sphinx: Directory Structure

The source directory structure that you choose will end up embedded in a lot of documents. That includes configuration files and every single internal hyperlink created. It’s possible to go back through and change things later, but it’s also a pain in the neck.

Creating Manuals Using RST and Sphinx: Planning

We can use Sphinx and RST together to minimise ongoing maintenance time and costs. Here are a few of the things to plan before putting your documentation project together.

Creating Manuals Using RST and Sphinx: Installation

This is the first post in a series that will explore using RST and Sphinx to create technical documentation.