github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-20 04:33:55 +00:00
Code Issues Projects Releases Wiki Activity

doc: update doc guidelines

Browse Source 
Update the doc writing guidelines to include some new capabilities
(multi-column display, numbered instruction steps) and add more
information about writing tables.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2020-04-15 12:51:42 -07:00 committed by David Kinder
parent 2d3c60ccd3
commit c9a357c95a
1 changed files with 168 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
doc/developer-guides/doc_guidelines.rst
View File

@ -165,14 +165,13 @@ Would be rendered as:
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:
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::
.. code-block:: rest
.. hlist::
:columns: 3
.. rst-class:: rst-columns
* A list of
* short items
@ -184,10 +183,9 @@ with a special ``hlist`` directive:
* space on
* the page
This would be rendered as:
would be rendered as:
.. hlist::
:columns: 3
.. rst-class:: rst-columns
* A list of
* short items
@ -199,8 +197,88 @@ This would be rendered as:
* space on
* the page
Note the optional ``:columns:`` parameter (default is two columns), and
all the list items are indented by three spaces.
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
***********************
@ -222,7 +300,7 @@ Don't use items within a single backtick, for example ```word```.
Internal Cross-Reference Linking
********************************
ReST links are only supported within the current file using the
Traditional ReST links are only supported within the current file using the
notation:
.. code-block:: rest
@ -251,7 +329,7 @@ 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
The label **must** be added immediately before a heading so there's a
natural phrase to show when referencing this label (e.g., the heading
text).
@ -369,6 +447,30 @@ 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.
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
***************************
@ -431,4 +533,44 @@ 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.
Instruction Steps
*****************
Numbered instruction steps 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. (Second-level headings
without this ``rst-class`` directive will not be numbered.) For example::
.. rst-class:: numbered-step
Put your right hand in
**********************
.. rst-class:: numbered-step
First instruction step
**********************
This is the first instruction step material. You can do the usual paragraphs and
pictures as you'd use in normal document writing. Write the heading to
be a summary of what the step is (the step numbering is automated so you
can move steps around easily if needed).
.. rst-class:: numbered-step
Second instruction step
***********************
This is the second instruction step.
.. note:: As implemented,
only one set of numbered steps is intended per document and the steps
must be level 2 headings.
Documentation Generation
************************
For instructions on building the documentation, see :ref:`acrn_doc`.