From 674470be07eecce33aa0ba5239e277706416ca55 Mon Sep 17 00:00:00 2001 From: OlgaGusarenko Date: Fri, 21 Aug 2015 17:24:06 +0300 Subject: [PATCH] [Contributor Guide] RST section, partial 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 --- doc/contributor-guide/source/index.rst | 1 + doc/contributor-guide/source/rst_conv.rst | 270 ++++++++++++++++++++++ 2 files changed, 271 insertions(+) create mode 100644 doc/contributor-guide/source/rst_conv.rst diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index 1935019541..70df9c6d15 100644 --- a/doc/contributor-guide/source/index.rst +++ b/doc/contributor-guide/source/index.rst @@ -12,6 +12,7 @@ Contents :maxdepth: 2 introduction.rst + rst_conv.rst Search in this guide ~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/contributor-guide/source/rst_conv.rst b/doc/contributor-guide/source/rst_conv.rst new file mode 100644 index 0000000000..e89f0dd1ca --- /dev/null +++ b/doc/contributor-guide/source/rst_conv.rst @@ -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 + +