reStructuredText documentation style guide

Also see How to edit the documentation.

This page explains the standards we follow for writing, formatting, and organizing the documentation. Please follow these guidelines and conventions when editing the rST documentation. For the standards governing the website (as opposed to the rST documentation hosted on https://doc.qubes-os.org), please see the Website style guide. If you wish to submit a pull request regarding content hosted on the website, please refer to How to edit the website.

reStructuredText conventions

All the documentation is written in reStructuredText (rST). When making contributions, please observe the following style conventions. If you’re not familiar with reStructuredText syntax, the Sphinx primer is a great resource, as well as this quick reStructuredText. Please always be mindful that rST syntax is sensitive to indentation!

Directives

A directive is a generic block of explicit markup, provided by Docutils and extended by Sphinx. Directives are used to insert non-paragraph content, such as images, tables, and code blocks. Example directives are:

.. image::
.. code::
.. figure::

Directives start with .., followed by directive name, arguments, options, and indented content.

Images

To include images (without a caption), use the image directive. You need to specify the path to the image and an alt text.

.. image:: path/to/image.png
   :alt: Alternative text
   :width: 200px
   :align: center

Read The Docs and the HTML sphinx-rtd-theme in use have a responsive design, which allows the documentation to render appropriately across all screen sizes.

Make sure to link only to images in the attachment/doc folder of the qubes-doc repository. Do not attempt to link to images hosted on other websites.

See also TL;DR: How to add images for the further information and about using the figure directive.

Lists

Lists can be bullet lists (*, +, -), enumerated lists (1., 2., etc.), definition lists, field lists.

Nested lists must be separated from the parent list items by blank lines:

- Item 1
- Item 2

  - Subitem 2.1
  - Subitem 2.2

- Item 3

Numbered lists can be autonumbered using the # sign.

#. Item 1
#. Item 2

  #. Subitem 2.1
  #. Subitem 2.2

#. Item 3

Item 3 will start at 1.

Code blocks

When writing code blocks, use syntax highlighting within the code or code-block.

By specifying the language, you enable pygments, which show syntax color coding for that code sample (see here for a list of supported languages).

.. code:: language

   code

Use [...] for anything omitted.

For inlining small code snippets you can use the code role as in

`code:`:term:`qube``

You can add line numbers to code examples with the :linenos: parameter.

.. code:: python
  :linenos:

   def hello_world():
     print("Hello, world!")

You can have certain lines with the :emphasize-lines: parameter.

.. code:: python
  :emphasize-lines: 1,3,4

For Python use python.

.. code:: python

  string_var = 'python'

For Bash use bash.

.. code:: bash

   #!/bin/bash

For a terminal session use console.

.. code:: console

   $ echo "Hello"

For text output use output.

.. code:: output

   some output

For text use text.

.. code:: text

   some text

Tables

We adhere to the list tables directive by docutils as described here.

A simple example would be:

.. list-table::
   :widths: 15 10
   :align: center
   :header-rows: 1

   * - Header 1
     - Header 2
   * - Cell 1
     - Cell 2
   * - Cell 3
     - Cell 4

Admonitions, messages, and warnings

Admonitions, messages, and warnings are used to draw the reader’s attention to important information, such as warnings, and for stylistic purposes. They are typically styled as colored text boxes, usually accompanied by icons provided out of the box by Sphinx and rST.

Alerts should generally be used somewhat sparingly, so as not to cause alert fatigue.

Here are examples of several types of alerts:

.. hint::
   If you would like to avoid prefixing commands with [...]

.. note::
  Using Rufus to create the installation medium means that you [...]

.. warning::
  Qubes OS is not meant to be installed inside a virtual machine as [...]

.. danger::
  Qubes has no control over what happens on your computer before [...]

These render as:

Hint

If you would like to avoid prefixing commands with […]

Note

Using Rufus to create the installation medium means that you […]

Warning

Qubes OS is not meant to be installed inside a virtual machine as […]

Danger

Qubes has no control over what happens on your computer before […]

You can also provide a custom title to the admonition:

.. admonition:: Did you know?

   The Qubes OS installer is completely offline. It doesn't even load [...]

Rendering as:

Did you know?

The Qubes OS installer is completely offline. It doesn’t even load […]

Glossary

The Sphinx glossary directive is created with a simple .. glossary:: block in /user/reference/glossary.rst. Anywhere else in the documentation you can link to a term using the role: :term:`qube` which automatically generates a hyperlink to the glossary entry qube.

Roles

Sphinx uses interpreted text roles to insert semantic markup into documents and thus enhance the readability and consistency of the documentation.

Syntax is as follows:

:rolename:`content`

In Qubes OS documentation the doc and ref roles are used extensively as described in TL;DR: Cross-referencing.

Some of the roles used in the Qubes OS documentation so far are:

Please continue using the above or new ones where appropriate.

Cross referencing:

  • Use the :doc: role with a path and a custom link text:

    :doc:`contributions </introduction/contributing>`.

  • Use the :doc: role with a path:

    :doc:`/introduction/intro`

  • Use :ref: for specific sections and a custom link text

    :ref:`What is Qubes OS? <introduction/intro:what is qubes os?>`

  • Use :ref only with a unique label above the specific section:

    .. _cross_referencing:

TL;DR: Cross-referencing
------------------------

and link to the section from within the documentation using :ref:`cross_referencing`.

For further information please see TL;DR: Cross-referencing.

External cross-referencing

You can make a cross-reference to any of the projects of the external developer’s documentation (hosted on https://dev.qubes-os.org):

To do such a cross-reference, use the usual cross-reference syntax but with the following prefix: PROJECT_NAME: (replace PROJECT_NAME by the name of the project). As an example, if you want to link to the index of the core-admin documentation, use this:

reStructuredText markup

output

 
:doc:`core-admin:index`

Welcome to core-admin’s documentation!

This is equivalent to using :doc:`index` inside the core-admin documentation. This works with any role like :ref:, :option:, etc.

Even if it works without it, always prefix the external cross-references with the name of the project, to help other contributors and maintainers to figure out what is going on.

Note

Intersphinx can list all the available links to another project with the following command:

python3 -m sphinx.ext.intersphinx https://dev.qubes-os.org/projects/core-admin/en/latest/objects.inv

You can replace core-admin by any of the projects listed above.

HTML and CSS

Do not write HTML inside rST documents. In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead.

Headings

Sectioning uses underlines with different characters (=, -, ^, “, ‘, ~) to create different levels of headings. This is also the recommended order provided. It doesn’t matter which characters you use in which order to mark a title, subtitle etc, as long as they are in consistent use across the documentation.

Qubes OS uses the convention in Python Developer’s Guide for documenting which are as follows:

# with overline, for parts
* with overline, for chapters
= for sections
- for subsections
^ for subsubsections
" for paragraphs

A simple example of how this is used in the Qubes OS documentation:

==========
Main Title
==========

Subsection
----------

Sub-subsection
^^^^^^^^^^^^^^

Paragraph
"""""""""

Text decorations

Emphasis and Italics

  • Italics: Use single asterisks

*italics*

  • Bold: Use double asterisks.

**bold**

  • Monospace: Use backticks.

``monospace``

Paragraph

Paragraphs are plain texts where indentation matters. Separate paragraphs by leaving a blank line between them.

Indentation

Use spaces instead of tabs. Use hanging indentations where appropriate. rST is an indentation sensitive markup language, similar to Python, please maintain consistent indentation (3 spaces) for readability.

Line wrapping

Do not hard wrap text, except where necessary (e.g., inside code blocks).

Writing guidelines

Correct use of terminology

Familiarize yourself with the terms defined in the glossary. Use these terms consistently and accurately throughout your writing.

Sentence case in headings

Use sentence case (rather than title case) in headings for the reasons explained here. In particular, since the authorship of the Qubes documentation is decentralized and widely distributed among users from around the world, many contributors come from regions with different conventions for implementing title case, not to mention that there are often differing style guide recommendations even within a single region. It is much easier for all of us to implement sentence case consistently across our growing body of pages, which is very important for managing the ongoing maintenance burden and sustainability of the documentation.

Writing command-line examples

When providing command-line examples:

  • Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:

Open a terminal in dom0 and run:

.. code:: console

   $ cd test
   $ echo Hello
   Hello

  • Precede each command with the appropriate command prompt: At a minimum, the prompt should contain a trailing # (for the user root) or $ (for other users) on Linux systems and > on Windows systems, respectively.

  • Don’t try to add comments inside the code block. For example, don’t do this:

Open a terminal in dom0 and run:

.. code:: console

   # Navigate to the new directory
   $ cd test
   # Generate a greeting
   $ echo Hello
   Hello

The # symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments outside of the code block in normal prose.

Variable names in commands

Syntactically distinguish variables in commands. For example, this is ambiguous:

$ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm

It should instead be:

$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm

Note that we syntactically distinguish variables in three ways:

  1. Surrounding them in angled brackets (< >)

  2. Using underscores (_) instead of spaces between words

  3. Using all capital letters

We have observed that many novices make the mistake of typing the surrounding angled brackets (< >) on the command line, even after substituting the desired real value between them. Therefore, in documentation aimed at novices, we also recommend clarifying that the angled brackets should not be typed. This can be accomplished in one of several ways:

  • Explicitly say something like “without the angled brackets.”

  • Provide an example command using real values that excludes the angled brackets.

  • If you know that almost all users will want to use (or should use) a specific command containing all real values and no variables, you might consider providing exactly that command and forgoing the version with variables. Novices may not realize which parts of the command they can substitute with different values, but if you’ve correctly judged that they should use the command you’ve provided as is, then this shouldn’t matter.

Capitalization of “qube”

We introduced the term qube as a user-friendly alternative to the term vm in the context of Qubes OS. Nonetheless, “qube” is a common noun like the words “compartment” and “container.” Therefore, in English, “qube” follows the standard capitalization rules for common nouns. For example, “I have three qubes” is correct, while “I have three Qubes” is incorrect. Like other common nouns, “qube” should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of “qube” (e.g., “Qubes can be shut down…”) can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, qubes os, or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.

Many people feel a strong temptation to capitalize the word “qube” all the time, like a proper noun, perhaps because it’s a new and unfamiliar term that’s closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it’s not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, “blockchain” is a relatively recent technical term that’s a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to particular people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn’t change the way we capitalize sentences like, “John sat under a tree.” Intuitively, it makes sense that the addition and removal of objects from the world shouldn’t cause published books to become orthographically incorrect while sitting on their shelves.

Accordingly, the reason “qube” is a common noun rather than a proper noun is because it doesn’t refer to any one specific thing (in this case, any one specific virtual machine). Rather, it’s the term for any virtual machine in a Qubes OS installation. (Technically, while qubes are currently implemented as virtual machines, Qubes OS is independent of its underlying compartmentalization technology. Virtual machines could be replaced with a different technology, and qubes would still be called “qubes.”)

I have several qubes in my Qubes OS installation, and you have several in yours. Every Qubes OS user has their own set of qubes, just as each of us lives in some neighborhood on some street. Yet we aren’t tempted to treat words like “neighborhood” or “street” as proper nouns (unless, of course, they’re part of a name, like “Acorn Street”). Again, while this might seem odd because “qube” is a new word that we invented, that doesn’t change how English works. After all, every word was a new word that someone invented at some point (otherwise we wouldn’t have any words at all). We treat “telephone,” “computer,” “network,” “program,” and so on as common nouns, even though those were all new technological inventions in the not-too-distant past (on a historical scale, at least). So, we shouldn’t allow ourselves to be confused by irrelevant factors, like the fact that the inventors happened to be us or that the invention was recent or is not in widespread use among humanity.

English language conventions

For the sake of consistency and uniformity, the Qubes documentation aims to follow the conventions of American English, where applicable. (Please note that this is an arbitrary convention for the sake consistency and not a value judgment about the relative merits of British versus American English.)

Organizational guidelines

Do not duplicate documentation

Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated as some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn’t realize it’s in more than once place). When this happens, the documentation as a whole is now inconsistent, and the outdated documentation becomes a trap, especially for novice users. Such traps are often more harmful than if the documentation never existed in the first place. The solution is to link to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare.

Core vs. external documentation

See also

About external documentation

If you’ve written a piece of documentation that is not appropriate for qubes-doc, we encourage you to submit it to the Qubes Forum instead. However, linking to external documentation from qubes-doc is perfectly fine. Indeed, the maintainers of the Qubes Forum should regularly submit PRs against the About External documentation index (see TL;DR: How to edit the documentation index) to add and update external links.

Many contributors do not realize that there is a significant amount of work involved in maintaining documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to undergo a review process to ensure accuracy before being merged, which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time.

If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It’s also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.

On the positive side, we consider the existence of community documentation to be a sign of a healthy ecosystem, and this is quite common in the software world. The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes. In addition, just because the Qubes OS Project has officially written and maintains some flexible framework, such as qrexec, it does not make sense to include every tutorial that says “here’s how to do something cool with qrexec in the core docs. Such tutorials generally also belong in the community documentation.

See #4693 for more background information.

Release-specific documentation

We maintain one set of documentation for each Qubes OS release, with source files in a named branch (eg Source for r4.3 documentation is in the r4.3 branch of qubes-doc). Documentation is updated on a continual, rolling basis. Our first priority is to document the current, stable releases of Qubes. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage.

Each version is available at Read The Docs. Documentation for the current release is loaded by default, but other versions can be accessed from the flyout version menu.

In general, you do not need to mention the version in the body text of documentation for any release. Make sure that any PR you submit is relevant to the version you are targeting, and is a PR against the correct branch: if the change is relevant to more than one release, create a PR against one branch - the documentation maintainers should ensure that the PR is appropriately handled.

Git conventions

Please follow our Git commit message guidelines.

Cheatsheet: Markdown vs. reStructuredText

For the documentation contributors more familiar with Markdown, here is a small cheatsheet highlighting essential differences.

Cheatsheet: Headings

Markdown:

# Title
## Section
### Sub-Section

reStructuredText:

=====
Title
=====

Section
-------

Seub-Section
^^^^^^^^^^^^

Text Decoration

Markdown:

*Italic* or _Italic_
**Bold** or __Bold__
~~Strikethrough~~

reStructuredText:

*Italic*
**Bold**
:strike:`Strikethrough`

Cheatsheet: Lists

Markdown:

- Item 1
- Item 2
  - Subitem 1
  - Subitem 2

1. Item 1
2. Item 2
   a. Subitem 1
   b. Subitem 2

reStructuredText:

- Item 1
- Item 2
  - Subitem 1
  - Subitem 2

1. Item 1
2. Item 2
   a. Subitem 1
   b. Subitem 2

Cheatsheet: Tables

Markdown:

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

reStructuredText:

.. list-table:: rst
   :widths: 15 10
   :align: center
   :header-rows: 1

   * - Header 1
     - Header 2
   * - Cell 1
     - Cell 2
   * - Cell 3
     - Cell 4

Cheatsheet: Code Blocks

Markdown:
```python
print("Hello, world!")
```

reStructuredText:

.. code:: python

    print("Hello, world!")

Alerts and Warnings

Markdown:

Markdown does not have built-in support for alerts and warnings.

reStructuredText:

.. note::

   This is a note.

.. warning::

   This is a warning.

.. danger::

   This is a danger message.