This guide will help you get started with Sphinx and write documentation in reStructuredText markup.
Work in progress, more content to be added.
This quick-guide will cover:
- General syntax and formatting
- Common elements
- How to create and structure documentation pages
- Themes and templating
- Recommended extensions
This section describes commonly used syntax and formatting.
- Italic text: Use one asterisks to create bold text, for example
*text* - Bold text: Use two asterisks to create bold text, for example
**text** - Inline code: Use backquotes to create inline code, for instance
``text``. This converts the text to monospace font, adds a background, and changes the text color. This should only be used for simple code examples. For more advanced or multiline code use code blocks.
Comments can be added in the markup, which does not display on the page itself. To create a comment prefix the comment text with ...
Example
.. This is a comment.
To create a multiline comments, add a linebreak between the .. prefix and the comment text, and indent each line with two whitespaces.
Example
..
This is a multiline comment.
This is another line in the same comment.
There are two kinds of hyperlinks, external and internal.
Standard hyperlinks needs to be wrapped in backquotes and suffixed with an underscore.
Example:
`This is a link to Google <https://google.com/>`_
The link text and target can also be separated, which is useful if the same link is used several times.
Example:
Link text:
This is a link to `Google`_
Target:
.. _Google: https://google.com/
The target needs to be place at the end of the section and be suffixed with .._.
Internal hyperlinks are great for creating references to other pages or sections in the documentation. The element being referred to needs to have a reference label.
For example:
.. _dependencies-angular:
Angular dependencies
------------------------------
The section can then be referred to by using the built-in :ref: role.
For example:
See the section :ref:`dependencies-angular` to read more about Angular dependencies.
The project comes with a pre-created glossary file.
Terms can be added to this glossary, which can then be used with the :ref: role.
For example, to make a reference to a term in the glossary called “Angular”:
The framework :ref:`Angular` is used for this project.
Sphinx pages support multiple levels of headings. Headings and sections are very important for the documentation, as they are automatically added to the navigation and table of contents, furthermore they can be referenced to from other pages in the documentation.
Usually no more than 3 levels of headings are needed; title, subsection, and subsubsection.
- Titles are underlined with
= - Sections are underlined with
- - Subsection are underlined with
~
⚠️ Note: It is important that the underlines are at least the same width as the header text, for example:
This title is underlined correctly
==================================
This title is NOT underlined correctly
===========
Headers can be referenced using the :ref: role, as described in the Hyperlinks section.
There are several body elements supported by Sphinx out-of-the-box.
Automatic generation of table of contents is one of the strongest features of Sphinx.
To create a table of contents, the .. toctree:: directive can be used. Pages can be added to the ToC by either referencing the name of the RST file itself, or use the title of the page.
Example
.. toctree::
user-interface-design
user-interface-guidelines
The .. toctree:: directive supports several options, such as numbering, max depth, and automatic inclusion of sub-pages. See the offical Sphinx documentation of table of contents to read all possible options.
Example of a ToC using max-depth and automatic numbering
.. toctree::
:maxdepth: 2
:numbered:
user-interface-design/index
user-interface-guidelines/index
Bullet point lists needs to be prefixed with *
* Bullet point 1
* Bullet point 2
Numbered lists needs to be prefixed with a number and a period
1. List item 1
2. List item 2
Numbered lists can also be autonumbered using #
#. List item 1
#. List item 2
Nested lists can be created by add a line-break after the parent list item and indenting the nested list item with two spaces:
* List item 1
* List item 2
* Nested item 1
* Nested item 2
* List item 3
Notes and warnings are great for highlighting important information for the reader.
A note can be created using the .. note:: directive. A linebreak needs to be added after the note directive with the note text added underneath. The note text needs to be indented with two whitespaces.
Example
.. note::
This is a note.
Multilines are supported.
Several types of notes are supported, such as warnings and hints. The .. note part of the directive just have to be replaced with the name of the note type to be used.
Example of a warning note
.. warning::
This is a warning note.
These are the supported note types:
- note
- warning
- attention
- caution
- danger
- error
- hint
- important
- tip
Line blocks are used to create a block of indented text.
To create a line block, the text should be prefixed with :: and be followed by a linebreak before the line block text. The line block text itself has to be indented by two whitespaces.
Example
This is a line block::
This is the text in the block
Multiline text is supported
Code blocks are the standard way to create a block of code with code highlight.
The code block can be created using the .. code-block:: directive. To specificy a specific code language for highlighting, the directive should be followed by the name of the language.
Example of a code block with a standard Python loop
.. code-block:: python
fruits = ["apple", "banana", "cherry"]
for x in fruits:
print(x)
Sphinx support tables, with several options such as automatic with, alignments, grids, and CSV tables. See the official documentation of the Sphinx Table directive to read more.
Example of a table with headers, two columns and three rows
.. table::
====== ======
Fruit Amount
====== ======
Banana 9
Apple 12
Cherry 5
====== ======
The table directive also supports grid format
Example of grid table
.. table::
+--------+--------+
| Fruit | Amount |
+========+========+
| Banana | 9 |
+--------+--------+
| Apple | 12 |
+--------+--------+
| Cherry | 5 |
+--------+--------+
Images can be inserted in the content using the .. image directive.
Example of external image:
.. image:: https://www.domain.com/image1.png
Example of internal image:
.. image:: image1.png
By default links to internal images have to be placed in the same folder as the RST page. It is good practice to use subfolders for media, to keep images and figures separate from RST pages.
To insert an image placed in a subfolder, the folder name needs to be suffixed.
For example, if the subfolder is called media:
.. image:: media/image1.png
Figures act much like images, but makes it possible to add a caption to the image and an optional legend.
Example of inserting a figure with a caption:
.. figure:: image1.png
This is the caption of the figure.
⚠️ Note: it is important that there is a line-break between the image and the caption, and that there is a space before the caption.
This section will cover how to create new documentation pages, and how to structure them to create to correct hierarchy.
Pages are created in the docs/source folder.
It is important to use the correct structure to create the correct hierarchy of pages and sub-pages. This hierarchy will automatically be used for the sidebar navigation and the table of content.
This project supports pages up to a maximum depth of 3, excluding the frontpage. For example, to create a "User Interface Design" page, with "Administration" and "External Web" sub-pages, where each of them have their own "Dependencies" sub-page, the structure would be the following:
1. User Interface Design
1.1 Administration
1.1.1 Dependencies
1.2 External Web
1.2.1 Dependencies
2. User Interface Guidelines
To create a sub-page, create a new sub-folder and a new RST in the folder. For instance, to create a the "Administration" sub-page and the "dependencies" sub-page shown above, use the following folder structure:
Administration page:
user-interface-design/administration/index.rst
Dependencies sub-page:
user-interface-design/administration/dependencies/dependencies.rst
The filename index.rst is often used for the sub-page that includes the table of contents of the sub-pages.
All RST pages needs to use the .rst filetype.
This section will cover how to change the Sphinx theme, how to edit the HTML templates, and how to change the style of the theme
Sphinx comes with several default themes. For this projet the Read the Docs theme is used, which will be installed when following the Quick-start installation guide.
The theme can be changed by editing the html_theme config value in the conf.py config file.
It is also possible to create custom themes, which is described further in the official Sphinx documentation.
The chosen theme can be further customized by editing or creating new HTML templates, placed in the _templates subfolder. The template files are based on HTML markup but also supports Jinja in order to implement variables and expressions. Templating is further described in the official Sphinx documentation, including how to implement Jinja.
Basic CSS can be used to style the HTML templates. Custom CSS stylesheets can be added to the _static/css subfolder. To include the stylesheet when build the HTML files, the path of the CSS stylesheet have to added to the html_static_path in the conf.py config file.
This project comes with an empty CSS stylesheet called custom.css.
This section gives an overview of optional extensions, which can be used to improve the experience when editing documentation pages.
The following extensions can be used to setup a live preview for editing. A live preview shows the output HTML files in real time while editing.
The VS Studio Code extension "Esbonio" can provide live-preview, syntax highlight, and auto-completion for reStructeredText.
⚠️ Be sure the right Python interpreter is selected before starting the Esbonio server. See the Build project section of the Quick-start installation guide.
The VS Studio Code extension "reStructuredText" is the a live-preview extension officialle recommended by Read the Docs. Just like the "Esbonio" extension it provides live-preview, syntax highlight, and auto-completion for reStructeredText.
This extension provides almost the same features as the Esbonio extension, but is more complex to setup. Therefore Esbonio is recommended if none of the advanced features are needed.
⚠️ Be sure the right Python interpreter is selected before enabling the preview feature. See the Build project section of the Quick-start installation guide.
Sphinx Autobuild is a Python extension, which means it does not require a specific code editor. The extension is not technically a live-preview, as it re-builds HTML pages on save. The HTML pages are served locally and can be accessed directly in the browser, giving an exact preview of how the HTML pages will look when hosted online, such as on Read the Docs.
To setup the extension for this project, run the following command in the environment:
pip install sphinx-autobuild
Then run the following to enable re-building on save:
sphinx-autobuild docs/source docs/source/_build/html
By default the HTML files can be accessed in the browser at http://127.0.0.1:8000/.
The following extensions can help improve the experience of syntax and formatting.
The "reStructuredText Syntax highlight" extension for VS Code makes it easier to differentiate text and components in the markiå.
A syntax highlight extension is highly recommended, as reStructuredText is fairly complex and hard to work with without any syntax highlighting. Visual Studio Code does not have out-of-the-box syntax highlight support for reStructuredText.
⚠️ Note that both the Esbonio and the official reStructedText extensions comes with their own syntax highlighter.
Creating and formatting tables in RST can be very complex, as correct use of whitespaces can make or break tables. Therefore the Table Formatter extension is recommended to help create correctly formatted tables.