611 lines
19 KiB
ReStructuredText
611 lines
19 KiB
ReStructuredText
.. _doc_guidelines:
|
|
|
|
Documentation Guidelines
|
|
########################
|
|
|
|
.. note::
|
|
|
|
For instructions on building the documentation, see :ref:`zephyr_doc`.
|
|
|
|
Zephyr Project 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, or make.bat on Windows, 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
|
|
`Zephyr documentation`_ website (with a different theme applied).
|
|
|
|
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
|
|
.. _Zephyr documentation: https://docs.zephyrproject.org
|
|
|
|
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
|
|
********
|
|
|
|
While reST allows use of both and overline and matching underline to
|
|
indicate a heading, we only use an underline indicator for headings.
|
|
|
|
* Document title (h1) use "#" for the underline character
|
|
* First section heading level (h2) use "*"
|
|
* Second section heading level (h3) use "="
|
|
* Third section heading level (h4) use "-"
|
|
|
|
The heading underline must be at least as long as the title it's under.
|
|
|
|
For example::
|
|
|
|
This is a title heading
|
|
#######################
|
|
|
|
some content goes here
|
|
|
|
First section 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.
|
|
|
|
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. Indent continuation lines with three spaces::
|
|
|
|
* 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 the 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
|
|
|
|
#. 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::
|
|
|
|
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 ``.. rst-class:: rst-columns`` directive. The directive will
|
|
apply to the next non-comment element (e.g., paragraph), or to content
|
|
indented under the directive. For example, this unordered list::
|
|
|
|
.. rst-class:: rst-columns
|
|
|
|
* A list of
|
|
* short items
|
|
* that should be
|
|
* displayed
|
|
* horizontally
|
|
* so it doesn't
|
|
* use up so much
|
|
* space on
|
|
* the page
|
|
|
|
would be rendered as:
|
|
|
|
.. rst-class:: rst-columns
|
|
|
|
* A list of
|
|
* short items
|
|
* that should be
|
|
* displayed
|
|
* horizontally
|
|
* so it doesn't
|
|
* use up so much
|
|
* space on
|
|
* the page
|
|
|
|
A maximum of three columns will be displayed, and change based on the
|
|
available width of the display window, reducing to one column on narrow
|
|
(phone) screens if necessary. We've deprecated use of the ``hlist``
|
|
directive because it misbehaves on smaller screens.
|
|
|
|
Tables
|
|
******
|
|
|
|
There are a few ways to create tables, each with their limitations or
|
|
quirks. `Grid tables
|
|
<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables>`_
|
|
offer the most capability for defining merged rows and columns, but are
|
|
hard to maintain::
|
|
|
|
+------------------------+------------+----------+----------+
|
|
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
|
|
| (header rows optional) | | | |
|
|
+========================+============+==========+==========+
|
|
| body row 1, column 1 | column 2 | column 3 | column 4 |
|
|
+------------------------+------------+----------+----------+
|
|
| body row 2 | ... | ... | you can |
|
|
+------------------------+------------+----------+ easily +
|
|
| body row 3 with a two column span | ... | span |
|
|
+------------------------+------------+----------+ rows +
|
|
| body row 4 | ... | ... | too |
|
|
+------------------------+------------+----------+----------+
|
|
|
|
This example would render as:
|
|
|
|
+------------------------+------------+----------+----------+
|
|
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
|
|
| (header rows optional) | | | |
|
|
+========================+============+==========+==========+
|
|
| body row 1, column 1 | column 2 | column 3 | column 4 |
|
|
+------------------------+------------+----------+----------+
|
|
| body row 2 | ... | ... | you can |
|
|
+------------------------+------------+----------+ easily +
|
|
| body row 3 with a two column span | ... | span |
|
|
+------------------------+------------+----------+ rows +
|
|
| body row 4 | ... | ... | too |
|
|
+------------------------+------------+----------+----------+
|
|
|
|
`List tables
|
|
<http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table>`_
|
|
are much easier to maintain, but don't support row or column spans::
|
|
|
|
.. list-table:: Table title
|
|
:widths: 15 20 40
|
|
:header-rows: 1
|
|
|
|
* - Heading 1
|
|
- Heading 2
|
|
- Heading 3
|
|
* - body row 1, column 1
|
|
- body row 1, column 2
|
|
- body row 1, column 3
|
|
* - body row 2, column 1
|
|
- body row 2, column 2
|
|
- body row 2, column 3
|
|
|
|
This example would render as:
|
|
|
|
.. list-table:: Table title
|
|
:widths: 15 20 40
|
|
:header-rows: 1
|
|
|
|
* - Heading 1
|
|
- Heading 2
|
|
- Heading 3
|
|
* - body row 1, column 1
|
|
- body row 1, column 2
|
|
- body row 1, column 3
|
|
* - body row 2, column 1
|
|
- body row 2, column 2
|
|
- body row 2, column 3
|
|
|
|
The ``:widths:`` parameter lets you define relative column widths. The
|
|
default is equal column widths. If you have a three-column table and you
|
|
want the first column to be half as wide as the other two equal-width
|
|
columns, you can specify ``:widths: 1 2 2``. If you'd like the browser
|
|
to set the column widths automatically based on the column contents, you
|
|
can use ``:widths: auto``.
|
|
|
|
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``.
|
|
|
|
For references to files that are in the Zephyr GitHub tree, a special
|
|
role can be used that creates a hyperlink to that file. For example a
|
|
reference to the reST file used to create this document can be generated
|
|
using ``:zephyr_file:\`doc/guides/documentation/index.rst\``` that will
|
|
show up as :zephyr_file:`doc/guides/documentation/index.rst`, a link to
|
|
the "blob" file in the github repo. There's also a
|
|
``:zephyr_raw:\`doc/guides/documentation/index.rst\``` role that will
|
|
link to the "raw" content,
|
|
:zephyr_file:`doc/guides/documentation/index.rst`. (You can click on
|
|
these links to see the difference.)
|
|
|
|
.. _internal-linking:
|
|
|
|
Internal Cross-Reference Linking
|
|
********************************
|
|
|
|
Traditional ReST links are only supported within the current file using the
|
|
notation::
|
|
|
|
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. You can change the text that's displayed as the
|
|
link writing this as::
|
|
|
|
Refer to the `show this text instead <internal-linking>`_ page
|
|
|
|
which renders as,
|
|
|
|
Refer to the `show this text instead <internal-linking>`_ page
|
|
|
|
|
|
External Cross-Reference Linking
|
|
********************************
|
|
|
|
With Sphinx's help, we can create
|
|
link-references to any tagged text within the Zephyr Project documentation.
|
|
|
|
Target locations in a document are defined with a label directive:
|
|
|
|
.. code-block:: rst
|
|
|
|
.. _my label name:
|
|
|
|
Heading
|
|
=======
|
|
|
|
Note the leading underscore indicating an inbound link.
|
|
The content immediately following
|
|
this label must be a heading, and is the target for a ``:ref:`my label name```
|
|
reference from anywhere within the Zephyr documentation.
|
|
The heading text is shown when referencing this label.
|
|
You can also change the text that's displayed for this link, such as::
|
|
|
|
:ref:`some other text <my label name>`
|
|
|
|
|
|
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 for the Zephyr Project
|
|
###############################################
|
|
|
|
|
|
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.
|
|
|
|
You can also define links to any URL and then reference it in your document.
|
|
For example, with this label definition in the document::
|
|
|
|
.. _Zephyr Wikipedia Page:
|
|
https://en.wikipedia.org/wiki/Zephyr_(operating_system)
|
|
|
|
you can reference it with::
|
|
|
|
Read the `Zephyr Wikipedia Page`_ for more information about the
|
|
project.
|
|
|
|
|
|
\`any\` links
|
|
*************
|
|
|
|
Within the Zephyr project, we've defined the default role to be "any",
|
|
meaning if you just write a phrase in back-ticks, e.g.,
|
|
```doc_guidelines```, Sphinx will search through all domains looking for
|
|
something called doc_guidelines to link to. In this case it will find
|
|
the label at the top of this document, and link to `doc_guidelines`.
|
|
This can be useful for linking to doxygen-generated links for function
|
|
names and such, but will cause a warning such as::
|
|
|
|
WARNING: 'any' reference target not found: doc_giudelines
|
|
|
|
if you misspelled ```doc_guidelines``` as ```doc_giudelines```.
|
|
|
|
Non-ASCII Characters
|
|
********************
|
|
|
|
You can insert non-ASCII characters such as a Trademark symbol (|trade|),
|
|
by using the notation ``|trade|``.
|
|
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:: c
|
|
|
|
struct z_object {
|
|
char *name;
|
|
uint8_t perms[CONFIG_MAX_THREAD_BYTES];
|
|
uint8_t type;
|
|
uint8_t flags;
|
|
uint32_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 z_object {
|
|
char *name;
|
|
uint8_t perms[CONFIG_MAX_THREAD_BYTES];
|
|
uint8_t type;
|
|
uint8_t flags;
|
|
uint32_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:: 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.
|
|
|
|
Images
|
|
******
|
|
|
|
Images are included in documentation by using an image directive::
|
|
|
|
.. image:: ../../images/doc-gen-flow.png
|
|
:align: center
|
|
:alt: alt text for the image
|
|
|
|
or if you'd like to add an image caption, use::
|
|
|
|
.. figure:: ../../images/doc-gen-flow.png
|
|
:alt: image description
|
|
|
|
Caption for the figure
|
|
|
|
The file name specified is relative to the document source file,
|
|
and we recommend putting images into an ``images`` folder where the document
|
|
source is found. The usual image formats handled by a web browser are
|
|
supported: JPEG, PNG, GIF, and SVG. Keep the image size only as large
|
|
as needed, generally at least 500 px wide but no more than 1000 px, and
|
|
no more than 250 KB unless a particularly large image is needed for
|
|
clarity.
|
|
|
|
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::
|
|
|
|
* 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.
|
|
|
|
zephyr-app-commands Directive
|
|
*****************************
|
|
|
|
.. include:: ../../_extensions/zephyr/application.py
|
|
:start-line: 10
|
|
:start-after: '''
|
|
:end-before: '''
|
|
|
|
For example, the ``.. zephyr-app-commands`` listed above would
|
|
render like this in the generated HTML output:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:board: qemu_x86
|
|
:goals: build
|
|
|
|
Alternative Tabbed Content
|
|
**************************
|
|
|
|
As introduced in the :ref:`getting_started`, you can provide alternative
|
|
content to the reader via a tabbed interface. When the reader clicks on
|
|
a tab, the content for that tab is displayed, for example::
|
|
|
|
.. tabs::
|
|
|
|
.. tab:: Apples
|
|
|
|
Apples are green, or sometimes red.
|
|
|
|
.. tab:: Pears
|
|
|
|
Pears are green.
|
|
|
|
.. tab:: Oranges
|
|
|
|
Oranges are orange.
|
|
|
|
will display as:
|
|
|
|
.. tabs::
|
|
|
|
.. tab:: Apples
|
|
|
|
Apples are green, or sometimes red.
|
|
|
|
.. tab:: Pears
|
|
|
|
Pears are green.
|
|
|
|
.. tab:: Oranges
|
|
|
|
Oranges are orange.
|
|
|
|
Tabs can also be grouped, so that changing the current tab in one area
|
|
changes all tabs with the same name throughout the page. For example:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: Linux
|
|
|
|
Linux Line 1
|
|
|
|
.. group-tab:: macOS
|
|
|
|
macOS Line 1
|
|
|
|
.. group-tab:: Windows
|
|
|
|
Windows Line 1
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: Linux
|
|
|
|
Linux Line 2
|
|
|
|
.. group-tab:: macOS
|
|
|
|
macOS Line 2
|
|
|
|
.. group-tab:: Windows
|
|
|
|
Windows Line 2
|
|
|
|
In this latter case, we're using ``.. group-tab::`` instead of simply
|
|
``.. tab::``. Under the hood, we're using the `sphinx-tabs
|
|
<https://github.com/djungelorm/sphinx-tabs>`_ extension that's included
|
|
in the Zephyr setup. Within a tab, you can have most any content *other
|
|
than a heading* (code-blocks, ordered and unordered lists, pictures,
|
|
paragraphs, and such). You can read more about sphinx-tabs from the
|
|
link above.
|
|
|
|
Instruction Steps
|
|
*****************
|
|
|
|
Also introduced in the :ref:`getting_started` is a style that makes it
|
|
easy to create tutorial guides with clearly identified steps. Add
|
|
the ``.. rst-class:: numbered-step`` directive immediately before a
|
|
second-level heading (by project convention, a heading underlined with
|
|
asterisks ``******``, and it will be displayed as a numbered step,
|
|
sequentially numbered within the document. For example::
|
|
|
|
.. rst-class:: numbered-step
|
|
|
|
Put your right hand in
|
|
**********************
|
|
|
|
.. rst-class:: numbered-step
|
|
|
|
Put your right hand in
|
|
**********************
|
|
|
|
See the :zephyr_raw:`doc/getting_started/index.rst` source file and compare
|
|
with the :ref:`getting_started` to see a full example. As implemented,
|
|
only one set of numbered steps is intended per document.
|
|
|
|
For instructions on building the documentation, see :ref:`zephyr_doc`.
|