Creating technical documentation

This chapter covers the following topics:

How to write the documentation using reStructuredText.
How to write the documentation using Markdown.

The purpose is to provide ‘quick’ reference information (on syntax, available tools, style conventions, etc) that may be required by those writing technical documentation.

The most important information is about reStructuredText, the markup language used in the technical documentation (user manual, etc.).

There is also some (basic) information about Sphinx, the application that automatically converts the text files and generates the documentation in HTML format or PDF format.

For example, this HTML page was originally written in reStructuredText.

Press the View page source link (in the top right of the page) to see the original reStructuredText source code.

Sphinx

Sphinx is a document generator based on docutils (an open-source text processing system, for processing plain text documentation into useful formats, such as HTML, LaTeX, ODT or XML).

In Sphinx, content (the text) is separated from presentation (formatting):

Content is stored in plain text files using a simple markup language (reStructuredText or Markdown).
Presentation is defined using themes and templates for each type of output (HTML, LaTeX, PDF).

This separation allows the authors to focus on the content and not on the presentation or the output format(s).

Also, if the documentation needs to be localised to another language, the text can be translated (using translation tools, if required), and all the formatting is applied later (without requiring further changes to the localised documents).

reStructuredText and Markdown

reStructuredText and Markdown are two popular lightweight markup languages. They are both plain text formats, and can be edited with any text editor.

reStructuredText is the markup language used in this project, and is the default markup language supported by Sphinx.

Markdown is also supported by Sphinx, but only the CommonMark flavour (supported by GitHub and other platforms) is supported.:

# This is a section in Markdown   This is a section in RST
                                 ========================

## This is a subsection           This is a subsection
                                 --------------------

Nothing special needed for        Nothing special needed for
a normal paragraph.               a normal paragraph.

                                 ::

   This is a code block          This is a code block

**Bold** and *emphasized*.        **Bold** and *emphasized*.

A list:                           A list:
- this is an item                 - this is an item
- another item                    - another item

There is more: images,            There is more: images,
tables, links, ...                tables, links, ...

reStructuredText

Links