Documentation Guidelines

The Bao hypervisor and tool documentation is written in reStructuredText markup language and enhanced with Sphinx extensions. This documentation can be built into HTML content by the running make html in the documentation repo's top level directory. Developers can open the index.html file created in the build folder in a web browser to inspect the final output and how it is rendered.

Note

In order to maintain consistency throughout Bao's documentation, for each reST syntax element, we have defined a set of guidelines specifying where, when and how each element should be applied. The guidelines are highlighted in a Note box like this one.

reST Syntax

Headings

Document Title heading
======================

Section 1 heading
-----------------

Section 2 heading
-----------------

Section 2.1 heading
*******************

Section 2.1.1 heading
#####################

Section 2.2 heading
*******************

Section 3 heading
-----------------

Note

Headings must be used to mark sections of a document.
Headings must be used in a consistent manner by following this defined order:
- = underlining characters for the Document Title
- - underlining characters for the First section level
- * underlining characters for the Second sub-section level
- # underlining characters for the Third sub-section level

Text Formatting

reST uses some few special characters to format text. The following table resumes the inline markup samples used throughout our documentation.

format	syntax	rendering
italic	`italic`	italic
bold	`bold`	bold
inline code	``inline code``	`inline code`
link	`Bao <http://www.bao - project.org/>`_	Bao

The use of backslash (\) is a work around to eliminate inline markup delimiters. Use before the character.

Note

Bold format should be used to strongly emphasize information.
Italic format should be used to lightly emphasize information.
Inline code format must be used when small code samples are used in the text (i.e., file paths, file names, shell commands, programming language directives/keywords/identifiers, syntax characters).
Link format must be used when referencing any external link.

Tables

Throughout our documentation there are a few tables to systematically present relevant information. We use Grid tables to create tables, which have provides a lot of flexibility to merge rows and columns. There are plenty of other tools online to help generate compatible grid tables, such as TablesGenerator.

+------------+---------------------------+-----------+-----------+
|  header-c1 |         mheader-c2        | header-c3 | header-c4 |
+============+=============+=============+===========+===========+
|    r1_c1   |   r1_mc2-1  | r1_mc2-2    | r1_c3     | r1_c4     |
+------------+-------------+-------------+-----------+-----------+
|   mr2_c1   | mr2-1_mc2-1 | mr2-1_mc2-2 | mr2-1_c3  | mr2-1_c4  |
|            +-------------+-------------+-----------+-----------+
|            | mr2-2_mc2-1 | mr2-2_mc2-2 | mr2-2_c3  | mr2-2_c4  |
+------------+-------------+-------------+-----------+-----------+

Rendered, the table looks like this:

header-c1	mheader-c2		header-c3	header-c4
r1_c1	r1_mc2-1	r1_mc2-2	r1_c3	r1_c4
mr2_c1	mr2-1_mc2-1	mr2-1_mc2-2	mr2-1_c3	mr2-1_c4
mr2_c1	mr2-2_mc2-1	mr2-2_mc2-2	mr2-2_c3	mr2-2_c4

Note

Tables can be used to represent well-defined tabular information.
Tables must be wider than a two-row structure (including the header)

Lists

There are three types of possible lists: bullet lists, numbered lists, and definition lists. Bullet and numbered lists should be indented at the same level as the preceding paragraph (and not indented itself). Additional lines are indented to the first character of the text of the bullet list.

Bullet List

For bullet lists you can use the asterisk * or hyphen - characters at the start of the item. Continuation of an item can be achieve with two spaces limitation below the item.

* This is a bulleted list.
* This is a big item break between two or more lines. This is a big item break between two or
  more lines. This is a big item break between two or more lines. This is a big item break
  between two or more lines.
    * Second-level bulleted list. This is a big item break between two or more lines.

Rendered, the bullet list looks like this:

This is a bulleted list.
This is a big item break between two or more lines. This is a big item break between two or more lines. This is a big item break between two or more lines. This is a big item break between two or more lines.
- Second-level bulleted list. This is a big item break between two or more lines.

Numbered List

For numbered lists you can start the list with a 1. or a). To continue the auto-numbering, use the character # followed with . or ) as used in the first list item.

1. item 1
    1. sub-item 1.1
    #. sub-item 1.2
    #. sub-item 1.3

#. item 2
    a) sub-item 2a
    #) sub-item 2b

#. item 3
    #) sub-item 3.1
    #) sub-item 3.2

Rendered, the numbered list looks like this:

item 1
1. sub-item 1.1
2. sub-item 1.2
3. sub-item 1.3
item 2
1. sub-item 2a
2. sub-item 2b
item 3
1. sub-item 3.1
2. sub-item 3.2

Definition List

This a convenient type of list to list one or more terms and their definition.

Term1
    This statement gives a definition for the Term1.
Term2
    This statement gives a definition for the Term2.

Rendered, the definition list looks like this:

Term1: This statement gives a definition for the Term1.
Term2: This statement gives a definition for the Term2.

Note

Bullet lists should be used to display a list of itemized terms/sentences without a certain order.
Bullet lists should be used with at least two items.
Numbered lists must be used to display an ordered/sequential list of itemized conclusions or steps.
Numbered lists should be used with more than two items.
Definition lists must be used when a term definition is in place.

Code Blocks

The reST format uses the code-block directive to create a highlight block to showcase formatted code or console commands. You can choose the programming language as exemplified in the example below for the C language and shell syntaxes. Please beware of the intentional blank line following the code-block syntax. You also need to indent the code segment.

.. code-block:: c

    uint64_t smc_fid = cpu.vcpu->regs->x[0];
    uint64_t x1 = cpu.vcpu->regs->x[1];
    uint64_t x2 = cpu.vcpu->regs->x[2];
    uint64_t x3 = cpu.vcpu->regs->x[3];

.. code-block:: shell

    cd ~

Rendered, the code blocks look like this:

uint64_t smc_fid = cpu.vcpu->regs->x[0];
uint64_t x1 = cpu.vcpu->regs->x[1];
uint64_t x2 = cpu.vcpu->regs->x[2];
uint64_t x3 = cpu.vcpu->regs->x[3];

cd ~

Moreover, you can also highlight a text segment using a code block. To achieve this, you just need to selected none as the "programming language".

..code-block:: none

    Takeaway 1: This is a highlighted text with a code block background and box.

Rendered, the code block looks like this:

Takeaway 1: This is a highlighted text with a code block background and box.

Note

Code blocks must be used to display large code segments.
Code blocks must be used with the appropriate programming language attribute (use the none attribute when the language is not supported by Pygments).
Code blocks can be used to lightly highlight a large text segment.

Referencing Links

To create a implicit link to a section title, you should know that all headings automatically generate hyperlink targets. This is the syntax:

this is a link to the `Code Blocks`_ section in this page this is a link to the Lists_ section
in this page

Rendered, the implicit link looks like this:

this is a link to the Code Blocks section in this page
this is a link to the Lists section in this page

To create a explicit link within the reST files, you need first to create a target location by following this syntax:

.. _label_name:

To reference a target location, you should use this notation:

:ref:`label_name` :ref:`Text<label_name>`

If we reference a target located on the first three headings of this document, you should be able to navigate to all three spots:

:ref:`headings`
:ref:`text_formatting`
:ref:`Tables are here<tables>`

Note

Implicit referencing links should be used to reference section titles within the respective reST file that they are used.
Explicit referencing links should be used to reference an arbitrary location within or outside of a document.

Images

To include images in the reST files, the following directive must be use:

.. figure:: img/bao-logo.png
    :width: 200px
    :align: center
    :name: bao-logo-fig

    Caption for the Bao logo picture.

Rendered, the image should look like this:

Caption for the Bao logo picture.

The image :numref:`bao-logo-fig` can be later referenced by using the notation :numref:`bao-logo-fig`, specifying the image name field.

Note

Image files must be stored in the current directory img folder (e.g., development/img/).
Images must contain a description in the caption.
Images should be in a .png file format.

Tabbed Content

For certain situations, instead of creating multiple documents describing similar content, you can use the tabs feature to merge all information in one document in an organized fashion.

.. tabs::

.. tab:: Platform-A

    Platform A instructions.

.. tab:: Platform-B

    Platform B instructions.

.. tab:: Platform-C

    Platform C instructions.

Rendered, the tabbed content looks like this:

.. tabs::

    .. tab:: Platform-A

        Platform A instructions.

    .. tab:: Platform-B

        Platform B instructions.

    .. tab:: Platform-C

        Platform C instructions.

Note

Tabs should be used to organize similar information that differ in a "configuration option" (e.g., build instructions across different platforms).

Boxes

To highlight text within a colored box, you can use three different directives depending on your goal.

.. seealso:: This is a **seealso** box.

.. note:: This is a **note** box.

.. warning:: This is a **warning** box.

Rendered, the different boxes look like this:

.. seealso:: This is a **seealso** box.

Note

This is a note box.

Warning

This is a warning box.

Note

See also boxes should be used to highlight (beginning with a preliminary description) additional text information referenced externally.
Note boxes should be used for information that you want the user to pay particular attention to.
Warning boxes should be used for information the user must understand to avoid negative consequences.

TODO, FIXME and DEPRECATED Tags

While writing Bao documentation, the TODO and FIXME tags can be used as typical inline comments (.. This is a comment.) to tag content that is missing, needs refactoring or optimization, or is broken (in the sense that the output is not what is expected). See below the meaning of each tag and use it accordingly.

TODO tags can be used to mark documentation content that (i) is missing or should be added in the future or (ii) needs any refactoring or optimization.

.. TODO: This is a TODO tag.

FIXME tags can be used to mark documentation content that is broken, in the sense that the output after building is not showing what is expected. Identified misuse of the markdown syntax can be marked with this tag.

.. FIXME: This is a FIXME tag.

DEPRECATED tags can be used to mark documentation content that is deprecated and must be updated.

.. DEPRECATED: This is a DEPRECATED tag.

Spelling and Format Checkers

To keep the consistency of the documentation, the :ref:`CI pipeline <ci>` runs two checkers to find misspelled words and invalid reST format styles. The checkers can be run locally by just running the following Make rules:

To run the sphinxcontrib.spelling spell checker:

make spelling

To run the doc8 format checker:

make rst-format

Besides checking for invalid reST format styles (D000 rule), the rst-format also checks for:

Note

lines longer than 99 characters - D001
no trailing whitespace - D002
no tabulation for indentation - D003
no carriage returns (use unix newlines) - D004
no newline at end of file - D005

Spelling Dictionaries

The spell checker uses standard enchant dictionaries to validate words. However, some specific words are not recognized, and can be added into a internal dictionary to avoid the spelling error. The source/spelling_wordlist.txt plain text file contains the extended dictionary words - one word per line. Use this dictionary to add meaningful words (e.g., fallthrough, requalification) or nouns that can be used throughout other documentation files, such as tool names (e.g., Doxygen, Github), programming languages keywords (e.g., struct, typedef), or others.

Some words that don't have a particular meaning (e.g., the words mc, mr, etc used in this document to represent rows and columns on the tables section) will only make sense on this document, therefore the following directive should be used to create a list of words known to be spelled correctly within a single file.

.. spelling:word-list::

    mc mr mheader mc html

.. spelling:word-list::

    mc mr mheader mc html

Glossary of Terms

Throughout Bao's documentation we try to maintain an updated and consolidated global glossary, that references terms to their definitions. The :ref:`glossary` is located in the source top-level directory, under the file glossary.rst. Each glossary entry, must be written as a definition list, with a capitalized term, followed by a single-line indented definition (see the code block below to verify the format).

.. glossary::
    :sorted:

    Term1
        Brief description

    Term2
        Brief description

To link terms with the glossary, the keyword :term:`term1` must be used, which transforms term1 in a hyperlink to its glossary entry.

Note

While writing the documentation, a best-effort should be in-place to guarantee that each new term (i.e., abbreviations, siglums, bao's architectural components/services/entities) are added to the glossary.
If a new term is added to the glossary, you must search for each reference in all other documents and mark it with the :term: keyword to created a link to the glossary entry. However, this should be avoided if the term has a dedicated file documenting it (e.g., :ref:`CI <ci>`, :ref:`MISRA <misra>`). Use explicit referencing instead. Notwithstanding, add the term to the glossary.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc_guidelines.rst

doc_guidelines.rst

Documentation Guidelines

reST Syntax

Headings

Text Formatting

Tables

Lists

Code Blocks

Referencing Links

Images

Tabbed Content

Boxes

TODO, FIXME and DEPRECATED Tags

Spelling and Format Checkers

Glossary of Terms

Files

doc_guidelines.rst

Latest commit

History

doc_guidelines.rst

File metadata and controls

Documentation Guidelines

reST Syntax

Headings

Text Formatting

Tables

Lists

Code Blocks

Referencing Links

Images

Tabbed Content

Boxes

TODO, FIXME and DEPRECATED Tags

Spelling and Format Checkers

Glossary of Terms