435 lines
13 KiB
ReStructuredText
435 lines
13 KiB
ReStructuredText
.. _doc_guidelines:
|
|
|
|
Documentation Guidelines
|
|
########################
|
|
|
|
Project ACRN content is written using the `reStructuredText`_ markup
|
|
language (``.rst`` file extension) with Sphinx extensions, and processed
|
|
using Sphinx to create a formatted standalone website. Developers can
|
|
view this content either in its raw form as ``.rst`` markup files, or (with
|
|
Sphinx installed) they can build the documentation using the Makefile
|
|
(on Linux systems) to
|
|
generate the HTML content. The HTML content can then be viewed using a
|
|
web browser. This same ``.rst`` content is also fed into the
|
|
`Project ACRN documentation`_ website.
|
|
|
|
You can read details about `reStructuredText`_
|
|
and about `Sphinx extensions`_ from their respective websites.
|
|
|
|
.. _Sphinx extensions: http://www.sphinx-doc.org/en/stable/contents.html
|
|
.. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
|
|
.. _Sphinx Inline Markup: http://sphinx-doc.org/markup/inline.html#inline-markup
|
|
.. _Project ACRN documentation: http://projectacrn.github.io
|
|
|
|
This document provides a quick reference for commonly used reST and
|
|
Sphinx-defined directives and roles used to create the documentation
|
|
you're reading.
|
|
|
|
Headings
|
|
********
|
|
|
|
Document sections are identified through their heading titles,
|
|
indicated with an underline below the title text. (While reST allows
|
|
use of both and overline and matching underline to indicate a heading,
|
|
we only use an underline indicator for headings.) For consistency in
|
|
our documentation, we define the order of characters used to indicated
|
|
the nested table of contents levels:
|
|
|
|
* Use ``#`` for the Document title underline character
|
|
* Use ``*`` for the First sub-section heading level
|
|
* Use ``=`` for the Second sub-section heading level
|
|
* Use ``-`` for the Third sub-section heading level
|
|
|
|
Additional heading level depth is discouraged.
|
|
|
|
The heading underline must be at least as long as the title it's under.
|
|
|
|
Here's an example of nested heading levels and the appropriate
|
|
underlines to use:
|
|
|
|
.. code-block:: rest
|
|
|
|
Document Title heading
|
|
######################
|
|
|
|
Section 1.0 heading
|
|
*******************
|
|
|
|
Section 2.0 heading
|
|
*******************
|
|
|
|
Section 2.1 heading
|
|
===================
|
|
|
|
Section 2.1.1 heading
|
|
---------------------
|
|
|
|
Section 2.2 heading
|
|
===================
|
|
|
|
Section 3.0 heading
|
|
*******************
|
|
|
|
|
|
|
|
Content Highlighting
|
|
********************
|
|
|
|
Some common reST inline markup samples:
|
|
|
|
* one asterisk: ``*text*`` for emphasis (*italics*),
|
|
* two asterisks: ``**text**`` for strong emphasis (**boldface**), and
|
|
* two backquotes: ````text```` for ``inline code`` samples.
|
|
|
|
ReST rules for inline markup try to be forgiving to account for common
|
|
cases of using these marks. For example using an asterisk to indicate
|
|
multiplication, such as ``2 * (x + y)`` will not be interpreted as an
|
|
unterminated italics section. For inline markup, the characters between
|
|
the beginning and ending characters must not start or end with a space,
|
|
so ``*this is italics*`` ( *this is italics*) while ``* this isn't*``
|
|
(* this isn't*).
|
|
|
|
If asterisks or backquotes appear in running text and could be confused with
|
|
inline markup delimiters, you can eliminate the confusion by adding a
|
|
backslash (``\``) before it.
|
|
|
|
Lists
|
|
*****
|
|
|
|
For bullet lists, place an asterisk (``*``) or hyphen (``-``) at
|
|
the start of a paragraph and indent continuation lines with two
|
|
spaces.
|
|
|
|
The first item in a list (or sublist) must have a blank line before it
|
|
and should be indented at the same level as the preceding paragraph
|
|
(and not indented itself).
|
|
|
|
For numbered lists
|
|
start with a ``1.`` or ``a)`` for example, and continue with autonumbering by
|
|
using a ``#`` sign and a ``.`` or ``)`` as used in the first list item.
|
|
Indent continuation lines with spaces to align with the text of first
|
|
list item:
|
|
|
|
.. code-block:: rest
|
|
|
|
* This is a bulleted list.
|
|
* It has two items, the second
|
|
item and has more than one line of reST text. Additional lines
|
|
are indented to the first character of the
|
|
text of the bullet list.
|
|
|
|
1. This is a new numbered list. If there wasn't a blank line before it,
|
|
it would be a continuation of the previous list (or paragraph).
|
|
#. It has two items too.
|
|
|
|
a) This is a numbered list using alphabetic list headings
|
|
#) It has three items (and uses autonumbering for the rest of the list)
|
|
#) Here's the third item. Use consistent punctuation on the list
|
|
number.
|
|
|
|
#. This is an autonumbered list (default is to use numbers starting
|
|
with 1).
|
|
|
|
#. This is a second-level list under the first item (also
|
|
autonumbered). Notice the indenting.
|
|
#. And a second item in the nested list.
|
|
#. And a second item back in the containing list. No blank line
|
|
needed, but it wouldn't hurt for readability.
|
|
|
|
Definition lists (with a term and its definition) are a convenient way
|
|
to document a word or phrase with an explanation. For example this reST
|
|
content:
|
|
|
|
.. code-block:: rest
|
|
|
|
The Makefile has targets that include:
|
|
|
|
html
|
|
Build the HTML output for the project
|
|
|
|
clean
|
|
Remove all generated output, restoring the folders to a
|
|
clean state.
|
|
|
|
Would be rendered as:
|
|
|
|
The Makefile has targets that include:
|
|
|
|
html
|
|
Build the HTML output for the project
|
|
|
|
clean
|
|
Remove all generated output, restoring the folders to a
|
|
clean state.
|
|
|
|
Multi-column lists
|
|
******************
|
|
|
|
If you have a long bullet list of items, where each item is short,
|
|
you can indicate the list items should be rendered in multiple columns
|
|
with a special ``hlist`` directive:
|
|
|
|
.. code-block:: rest
|
|
|
|
.. hlist::
|
|
:columns: 3
|
|
|
|
* A list of
|
|
* short items
|
|
* that should be
|
|
* displayed
|
|
* horizontally
|
|
* so it doesn't
|
|
* use up so much
|
|
* space on
|
|
* the page
|
|
|
|
This would be rendered as:
|
|
|
|
.. hlist::
|
|
:columns: 3
|
|
|
|
* A list of
|
|
* short items
|
|
* that should be
|
|
* displayed
|
|
* horizontally
|
|
* so it doesn't
|
|
* use up so much
|
|
* space on
|
|
* the page
|
|
|
|
Note the optional ``:columns:`` parameter (default is two columns), and
|
|
all the list items are indented by three spaces.
|
|
|
|
File names and Commands
|
|
***********************
|
|
|
|
Sphinx extends reST by supporting additional inline markup elements (called
|
|
"roles") used to tag text with special
|
|
meanings and allow style output formatting. (You can refer to the `Sphinx Inline Markup`_
|
|
documentation for the full list).
|
|
|
|
For example, there are roles for marking :file:`filenames`
|
|
(``:file:`name```) and command names such as :command:`make`
|
|
(``:command:`make```). You can also use the \`\`inline code\`\`
|
|
markup (double backticks) to indicate a ``filename``.
|
|
|
|
Don't use items within a single backtick, for example ```word```.
|
|
|
|
.. _internal-linking:
|
|
|
|
Internal Cross-Reference Linking
|
|
********************************
|
|
|
|
ReST links are only supported within the current file using the
|
|
notation:
|
|
|
|
.. code-block:: rest
|
|
|
|
refer to the `internal-linking`_ page
|
|
|
|
which renders as,
|
|
|
|
refer to the `internal-linking`_ page
|
|
|
|
Note the use of a trailing
|
|
underscore to indicate an outbound link. In this example, the label was
|
|
added immediately before a heading, so the text that's displayed is the
|
|
heading text itself.
|
|
|
|
With Sphinx however, we can create
|
|
link-references to any tagged text within the project documentation.
|
|
|
|
Target locations within documents are defined with a label directive:
|
|
|
|
.. code-block:: rst
|
|
|
|
.. _my label name:
|
|
|
|
Note the leading underscore indicating an inbound link.
|
|
The content immediately following
|
|
this label is the target for a ``:ref:`my label name```
|
|
reference from anywhere within the documentation set.
|
|
The label should be added immediately before a heading so there's a
|
|
natural phrase to show when referencing this label (e.g., the heading
|
|
text).
|
|
|
|
This is the same directive used to
|
|
define a label that's a reference to a URL:
|
|
|
|
.. code-block:: rest
|
|
|
|
.. _Hypervisor Wikipedia Page:
|
|
https://en.wikipedia.org/wiki/Hypervisor
|
|
|
|
To enable easy cross-page linking within the site, each file should have
|
|
a reference label before its title so it can
|
|
be referenced from another file. These reference labels must be unique
|
|
across the whole site, so generic names such as "samples" should be
|
|
avoided. For example the top of this document's ``.rst`` file is:
|
|
|
|
|
|
.. code-block:: rst
|
|
|
|
.. _doc_guidelines:
|
|
|
|
Documentation Guidelines
|
|
########################
|
|
|
|
Other ``.rst`` documents can link to this document using the ``:ref:`doc_guidelines``` tag and
|
|
it will show up as :ref:`doc_guidelines`. This type of internal cross reference works across
|
|
multiple files, and the link text is obtained from the document source so if the title changes,
|
|
the link text will update as well.
|
|
|
|
There may be times where you'd like to change the link text that's shown
|
|
in the generated document. In this case, you can add specify alternate
|
|
text using ``:ref:`alternate text <doc_guidelines>``` (renders as
|
|
:ref:`alternate text <doc_guidelines>`).
|
|
|
|
|
|
Non-ASCII Characters
|
|
********************
|
|
|
|
You can insert non-ASCII characters such as a Trademark symbol (|trade|),
|
|
by using the notation ``|trade|``. (It's also allowed to use the UTF-8
|
|
characters directly.)
|
|
Available replacement names are defined in an include file used during the Sphinx processing
|
|
of the reST files. The names of these replacement characters are the same as used in HTML
|
|
entities used to insert characters in HTML, e.g., \™ and are defined in the
|
|
file ``sphinx_build/substitutions.txt`` as listed here:
|
|
|
|
.. literalinclude:: ../substitutions.txt
|
|
:language: rst
|
|
|
|
We've kept the substitutions list small but others can be added as
|
|
needed by submitting a change to the ``substitutions.txt`` file.
|
|
|
|
Code and Command Examples
|
|
*************************
|
|
|
|
Use the reST ``code-block`` directive to create a highlighted block of
|
|
fixed-width text, typically used for showing formatted code or console
|
|
commands and output. Smart syntax highlighting is also supported (using the
|
|
Pygments package). You can also directly specify the highlighting language.
|
|
For example:
|
|
|
|
.. code-block:: rest
|
|
|
|
.. code-block:: c
|
|
|
|
struct _k_object {
|
|
char *name;
|
|
u8_t perms[CONFIG_MAX_THREAD_BYTES];
|
|
u8_t type;
|
|
u8_t flags;
|
|
u32_t data;
|
|
} __packed;
|
|
|
|
Note the blank line between the ``code-block`` directive and the first
|
|
line of the code-block body, and the body content is indented three
|
|
spaces (to the first non-white space of the directive name).
|
|
|
|
This would be rendered as:
|
|
|
|
.. code-block:: c
|
|
|
|
struct _k_object {
|
|
char *name;
|
|
u8_t perms[CONFIG_MAX_THREAD_BYTES];
|
|
u8_t type;
|
|
u8_t flags;
|
|
u32_t data;
|
|
} __packed;
|
|
|
|
|
|
You can specify other languages for the ``code-block`` directive,
|
|
including ``c``, ``python``, and ``rst``, and also ``console``,
|
|
``bash``, or ``shell``. If you want no syntax highlighting, use the
|
|
language ``none``, for example:
|
|
|
|
.. code-block:: rest
|
|
|
|
.. code-block:: none
|
|
|
|
This would be a block of text styled with a background
|
|
and box, but with no syntax highlighting.
|
|
|
|
Would display as:
|
|
|
|
.. code-block:: none
|
|
|
|
This would be a block of text styled with a background
|
|
and box, but with no syntax highlighting.
|
|
|
|
There's a shorthand for writing code blocks too: end the introductory
|
|
paragraph with a double colon (``::``) and indent the code block content
|
|
by three spaces. On output, only one colon will be shown. The
|
|
highlighting package makes a best guess at the type of content in the
|
|
block and highlighting purposes. This can lead to some odd
|
|
highlighting in the generated output.
|
|
|
|
Tabs, spaces, and indenting
|
|
***************************
|
|
|
|
Indenting is significant in reST file content, and using spaces is
|
|
preferred. Extra indenting can (unintentionally) change the way content
|
|
is rendered too. For lists and directives, indent the content text to
|
|
the first non-white space in the preceding line. For example:
|
|
|
|
.. code-block:: rest
|
|
|
|
* List item that spans multiple lines of text
|
|
showing where to indent the continuation line.
|
|
|
|
1. And for numbered list items, the continuation
|
|
line should align with the text of the line above.
|
|
|
|
.. code-block::
|
|
|
|
The text within a directive block should align with the
|
|
first character of the directive name.
|
|
|
|
Keep the line length for documentation less than 80 characters to make
|
|
it easier for reviewing in GitHub. Long lines because of URL references
|
|
are an allowed exception.
|
|
|
|
Drawings
|
|
********
|
|
|
|
You can include a picture (.jpg, .png, .svg for example) by using the
|
|
``.. image`` directive::
|
|
|
|
.. image:: ../images/ACRNlogo.png
|
|
:align: center
|
|
|
|
This results in the image being placed in the document:
|
|
|
|
.. image:: ../images/ACRNlogo.png
|
|
:align: center
|
|
|
|
Alternatively, use the ``.. figure`` directive to include a picture with
|
|
a caption and automatic figure numbering for
|
|
your image, (so you can say see :numref:`acrn-logo-figure`, by using the
|
|
notation ``:numref:`acrn-logo-figure``` and specifying the name of
|
|
figure)::
|
|
|
|
.. figure:: ../images/ACRNlogo.png
|
|
:align: center
|
|
:name: acrn-logo-figure
|
|
|
|
Caption for the figure
|
|
|
|
.. figure:: ../images/ACRNlogo.png
|
|
:align: center
|
|
:name: acrn-logo-figure
|
|
|
|
Caption for the figure
|
|
|
|
|
|
We've also included the ``graphviz`` Sphinx extension to let you use a text
|
|
description language to render drawings. See :ref:`graphviz-examples` for more
|
|
information.
|
|
|
|
|