openstack/openstack-manuals
Code Issues Proposed changes

[Contributor Guide] RST section, partial

Browse Source 
Includes rst conventions for:

1. lines length
2. spaces and tabs
3. titles
4. admonitions
5. code-blocks

Implements: blueprint docs-contributor-guide

Change-Id: I6e7e51d9196ea7488510dfb038ecbdf5a004cf50
This commit is contained in:
OlgaGusarenko 2015-08-21 17:24:06 +03:00
parent 04543f2d6d
commit 674470be07
2 changed files with 271 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/contributor-guide/source/index.rst
View File

@ -12,6 +12,7 @@ Contents
:maxdepth: 2
introduction.rst
rst_conv.rst
Search in this guide
~~~~~~~~~~~~~~~~~~~~

270
doc/contributor-guide/source/rst_conv.rst Normal file
View File

@ -0,0 +1,270 @@
.. _rst_conv:
==========================
RST formatting conventions
==========================
Follow these guidelines for all the RST source files to keep the documentation
format consistent.
General guidelines
~~~~~~~~~~~~~~~~~~
Lines length
------------
Wrap source lines so that lines length does not exceed 79 characters.
This requirement matches PEP8 standards (from Python) and helps with
side-by-side diffs on reviews.
.. note::
Exception to this rule is the content of code-block elements and links
within the references.
When formatting a table that presupposes long lines of text, give
the preference to one of the following methods over the ``table`` directive:
* format a table using the ``list-table`` directive;
* format a table using the ``csv-table`` directive;
* format information as definition lists to avoid tables where possible.
Space and tab characters
------------------------
* Do not use tab characters within the code; use space characters instead.
* Do not place space characters at the end of lines. If used,
the checkniceness test will fail because of the trailing whitespaces.
Titles
~~~~~~
Each RST source file has the tree structure. Define up to three heading
levels within one file using the following non-alphanumeric characters:
* **Heading 1** - underline and overline with equal signs;
* **Heading 2** - underline with tildes;
* **Heading 3** - underline with dashes.
**Input**
.. code::
=========
Heading 1
=========
Body of the first level section that includes general overview
of the subject to be covered by the whole section.
Can include several focused Heading-2-sections.
Heading 2
~~~~~~~~~
Body of the second level section that gives detailed explanation of one
of the aspects of the subject. Can include several Heading-3-sections.
Within user guides, it is mostly used to entitle a procedure with a set
of actions targeted at a single task performance.
For example, "Associate floating IP addresses".
Heading 3
---------
Body of the third level section.
It includes very specific content; and occurs mainly in guides containing
technical information for advanced users.
.. note::
Under- and overlines should be of the same length
as that of the heading text.
Avoid using lower heading levels by information
rewriting and reorganizing.
Specific information
~~~~~~~~~~~~~~~~~~~~
Use special markups to emphasize specific content within the text.
Depending on specific semantic meaning of the message, you can use:
* **note** - for a message of generic meaning.
* **warning** or **important** - includes details that can be easily missed,
but should not be ignored by a user and are valuable before proceeding.
* **caution** - delivers information that prevents a user from mistakes
and undesirable consequences when following the procedures.
* **tip** - wraps extra but helpful information.
Here is the example of the note directive usage; these can be applied to all
the admonition directives described above.
**Input**
.. code::
.. note:: This is the text of a generic admonition.
This line is the continuation of the first line.
Note may contain bulleted or enumerated lists,
as well as code blocks:
* first option,
* ...
**Output**
.. note:: This is the text of a note admonition.
This line is the continuation of the first line.
Note may contain bulleted or enumerated lists,
as well as code blocks:
* first option,
* ...
Code samples
~~~~~~~~~~~~
Format code snippets as standalone literal blocks. There are several ways
to define a code-block within an RST file.
Standard literal block
----------------------
+------------------+---------------------------------------------------------+
| **Directive** | ``::`` or ``code`` |
+------------------+---------------------------------------------------------+
| **Arguments** | none |
+------------------+---------------------------------------------------------+
| **Options** | none |
+------------------+---------------------------------------------------------+
| **Description** | * Introduces a standard reST literal block. |
| | * Preserves line breaks and whitespaces. |
| | * Automatically highlights language (Python, by |
| | default) |
+------------------+---------------------------------------------------------+
Use ``::`` or ``code`` directive if you provide the code snippets written
in one programming language within one file. By default, the code-block
formatted this way is shown in a Python highlighting mode.
To define another highlighting language, specify the ``highlight`` directive
at the top of the file. Use the ``linenothreshold`` option with it
to enumerate lines within the code-block.
Always switch on the enumeration for the code-blocks that include more
than 5 lines.
**Input**
.. code::
.. highlight:: console
:linenothreshold: 5
This is the file body with the code snippet within:
::
$ neutron ext-list -c alias -c name
+-----------------+--------------------------+
| alias | name |
+-----------------+--------------------------+
| agent_scheduler | Agent Schedulers |
| binding | Port Binding |
| quotas | Quota management support |
| ... | ... |
+-----------------+--------------------------+
**Output**
.. highlight:: console
:linenothreshold: 5
This is the file body with the code snippet within:
::
$ neutron ext-list -c alias -c name
+-----------------+--------------------------+
| alias | name |
+-----------------+--------------------------+
| agent_scheduler | Agent Schedulers |
| binding | Port Binding |
| quotas | Quota management support |
| ... | ... |
+-----------------+--------------------------+
Non-standard literal block
--------------------------
+------------------+---------------------------------------------------------+
| **Directive** | ``code-block`` |
+------------------+---------------------------------------------------------+
| **Arguments** | ``python`` (default), ``ruby``, ``c``, ``console``, |
| | ``ini``, and others |
+------------------+---------------------------------------------------------+
| **Options** | ``linenos``, ``emphasize-lines`` |
+------------------+---------------------------------------------------------+
| **Description** | * Specifies the highlighting language directly. |
| | * Preserves line breaks and whitespaces. |
| | * Has special options to number lines and emphasize |
| | specific lines within the block. |
+------------------+---------------------------------------------------------+
To optimize the output of code for a specific programming language, specify
the corresponding argument with ``code-block``. Use ``ini`` for configuration
files, ``console`` for console inputs and outputs, and so on.
Specify ``linenos`` for automatic enumeration of the code-blocks that include
more than 5 lines.
If you need to draw a user's attention to the particular code lines, use
the ``emphasize-lines`` option followed by the numbers of the lines to
emphasize.
**Input**
.. code::
.. code-block:: ini
:emphasize-lines: 1, 5-7
:linenos:
# Configuration for nova-rootwrap
# This file should be owned by (and only-writeable by) the root user
[DEFAULT]
# List of directories to load filter definitions from (separated by ',').
# These directories MUST all be only writeable by root !
filters_path=/etc/nova/rootwrap.d,/usr/share/nova/rootwrap
**Output**
.. code-block:: ini
:emphasize-lines: 1, 5-7
:linenos:
# Configuration for nova-rootwrap
# This file should be owned by (and only-writeable by) the root user
[DEFAULT]
# List of directories to load filter definitions from (separated by ',').
# These directories MUST all be only writeable by root !
filters_path=/etc/nova/rootwrap.d,/usr/share/nova/rootwrap