openstack/openstack-manuals
Code Issues Proposed changes

[Contributor Guide] RST section finished

Browse Source 
1. Adds the following subsections:
   * Introduction to RST
   * Tables
   * Images
   * Profiling
   * Lists
   * Inline markups
   * Decorations
   * Commenting
2. Restructures the toc
3. Creates separate files for each subsection included in the
RST-related folder for simpler maintenance.

Change-Id: I08568fb37755109552edf9692b8f259660550a69
This commit is contained in:
OlgaGusarenko
2015-10-08 11:49:08 +03:00
committed by Alexander Adamov
parent f34960c5aa
commit c10da1ec38
13 changed files with 998 additions and 302 deletions
Download Patch File Download Diff File Expand all files Collapse all files

334
doc/contributor-guide/source/rst-conv.rst
View File

@@ -1,322 +1,52 @@
.. _rst_conv: .. _rst_conv:
========================== ==========================
RST formatting conventions RST formatting conventions
========================== ==========================
Follow these guidelines for all the RST source files to keep the documentation OpenStack documentation uses reStructuredText (RST) markup syntax
format consistent. with Sphinx extensions.
RST is a powerful and straightforward markup language, that in combination
with Sphinx, provides a wide range of facilities for intelligent and
good-looking documentation creation. It uses simple and implicit
syntax to introduce a wide range of content elements, such as, titles,
code blocks, vertical lists, and many others. All the source content formatted
using RST is stored in files with the ``.rst`` extension.
General guidelines To keep the documentation format consistent, follow the guidelines
~~~~~~~~~~~~~~~~~~ included in this chapter for all the RST source content. When in doubt
use simpler formatting.
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:: .. note::
Exception to this rule is the content of code-block elements and links All the examples provided in this chapter are for illustration purposes
within the references. only and cannot be regarded as pieces of true technical information.
When formatting a table that presupposes long lines of text, give .. toctree::
the preference to one of the following methods over the ``table`` directive: :maxdepth: 2
* format a table using the ``list-table`` directive; rst-conv/gen-guidelines.rst
* format a table using the ``csv-table`` directive; rst-conv/titles.rst
* format information as definition lists to avoid tables where possible. rst-conv/inline-markups.rst
rst-conv/lists.rst
Space and tab characters rst-conv/spec-info.rst
------------------------ rst-conv/source-code.rst
rst-conv/refs.rst
* Do not use tab characters within the code; use space characters instead. rst-conv/tables.rst
rst-conv/figures.rst
* Do not place space characters at the end of lines. If used, rst-conv/profiling.rst
the checkniceness test will fail because of the trailing whitespaces. rst-conv/comment.rst
rst-conv/decor.rst
.. _cg_titles: Useful links
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 * `Sphinx documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`_
to define a code-block within an RST file.
Standard literal block * `reStructuredText: Markup Syntax and Parser Component of Docutils
---------------------- <http://docutils.sourceforge.net/rst.html>`_
+------------------+---------------------------------------------------------+ * `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
| **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 |
| ... | ... |
+-----------------+--------------------------+
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, 4
# 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 ',').
References
~~~~~~~~~~
Cross-references
----------------
To cross-reference to arbitrary locations within one document,
use the ``ref`` role:
**Input**
.. code::
.. _cg_titles:
Titles
~~~~~~
This is the section we want to reference to.
...
The following - :ref:`cg_titles` - generates a link to the section with
the defined label using this section heading as a link title.
A link label and a reference can be defined in separate source files,
but within one directory. Otherwise, use the external linking.
**Output**
...
The following - :ref:`cg_titles` - generates a link to the section with
the defined label using this section heading as a link title.
A link label and a reference can be defined in separate source files,
but within one directory. Otherwise, use the external linking.
External references
-------------------
To link to some external locations, format RST source as follows:
#. Do not apply any markups to specify a web link.
#. If you need a specific link title to appear in the output,
format a web link as ``Link text <http://web-link.com>``
wrapping it in backticks.
#. If a source file contains a big number of external references,
you can separate a link from its definition for better readability
while reviewing as shown in the example.
**Input**
.. code::
Here is a link to the User guide: http://docs.openstack.org/user-guide/.
Here is an external web link with a link title:
`User guide <http://docs.openstack.org/user-guide/>`_.
Here is an external web link separated from its definition:
This paragraph contains the link to `User guide`_.
...
.. format the link definition at the end of the file as follows:
.. _`User guide`: http://docs.openstack.org/user-guide/
**Output**
Here is a link to the User guide: http://docs.openstack.org/user-guide/.
Here is an external web link with a link title:
`User guide <http://docs.openstack.org/user-guide/>`_.
Here is an external web link separated from its definition:
This paragraph contains the link to `User guide`_.
...
.. format the link definition at the end of the file as follows:
.. _`User guide`: http://docs.openstack.org/user-guide/

19
doc/contributor-guide/source/rst-conv/comment.rst Normal file
View File

@@ -0,0 +1,19 @@
========
Comments
========
Indicate a comment by means of the ``..`` marker.
**Input**
.. code::
.. This is a comment. It is not visible in the documentation build.
Generally, use it to include TODO within the content followed
by the initials of the person who is to perform the action.
For example:
.. TODO(OG): add a link to the Decorations section when it is available.

81
doc/contributor-guide/source/rst-conv/decor.rst Normal file
View File

@@ -0,0 +1,81 @@
===========
Decorations
===========
Sometimes, the documentation build does not look perfect. To improve
readability and, therefore, understanding of the content, you can use
some visual decorations.
This section contains a number of bells and whistles that are neither
conventions nor even recommendations, but extra features of RST markup
syntax for general educational purposes.
Adding a horizontal line
~~~~~~~~~~~~~~~~~~~~~~~~
You can create a horizontal line to visually separate content elements
by typing four ``-`` (hyphen) in a row adding blank lines before and after.
**Input**
.. code::
Paragraph 1
----
Paragraph 2
**Output**
Paragraph 1
----
Paragraph 2
Starting a new line
~~~~~~~~~~~~~~~~~~~
Use ``|`` (vertical bar) followed by a single white space to start a new line.
**Input**
.. code::
| The first line of text.
| The second line of text (new line).
| ...
**Output**
| The first line of text.
| The second line of text (new line).
| ...
Adding extra space between two content elements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use ``|`` (vertical bar) adding blank lines before and after it to add extra
space between two content elements.
**Input**
.. code::
Paragraph 1
|
Paragraph 2
**Output**
Paragraph 1
|
Paragraph 2

26
doc/contributor-guide/source/rst-conv/figures.rst Normal file
View File

@@ -0,0 +1,26 @@
=======
Figures
=======
Use the ``figure`` directive to include an image, figure, or screenshot into
the documentation.
**Syntax**
::
.. figure:: file_name.file_extension
:option: option_value
The figure directive supports the following options:
* alt
* height
* figwidth
* scale
* align
* target
* figclass
For descriptions of the options and their possible values, refer to the
`Docutils documentation <http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure>`_.

49
doc/contributor-guide/source/rst-conv/gen-guidelines.rst Normal file
View File

@@ -0,0 +1,49 @@
==================
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
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 trailing whitespaces.
Indentation
~~~~~~~~~~~
Use indentation very carefully and keep it consistent since it is significant
for content nesting. Any indentation that differs from the previous
one in length, terminates the current level of content either introducing
a new content sublevel, or shifting to an upper content level.
Use indentation to format the nested content within:
* Definition lists
* Admonitions (notes, warnings, and so on)
* Code blocks
* List and CSV tables
For more information on how to format elements from the list above,
see the related section of this chapter.

202
doc/contributor-guide/source/rst-conv/inline-markups.rst Normal file
View File

@@ -0,0 +1,202 @@
===============
Inline elements
===============
Sphinx enables specific pieces of inline text. This is emphasized by
semantic markups that format text in a different style.
Use the markups included in this section as consistent with their semantic
meaning.
.. note::
An inline semantic markup has no effect when applied to a piece of text
within a code-block element.
To insert a semantic markup into your document, use the syntax below.
**Syntax**
::
:markup:`inline text`
Application
~~~~~~~~~~~
A software application within a line of text.
+------------------------+---------------------------------------------------+
| **Markup** | ``:program:`` |
+------------------------+---------------------------------------------------+
| **Syntax** | ``:program:`RabbitMQ``` |
+------------------------+---------------------------------------------------+
| **Example of output** | Configure :program:`RabbitMQ`. |
+------------------------+---------------------------------------------------+
Code
~~~~
A fragment of code within a line of text.
+------------------------+---------------------------------------------------+
| **Markup** | `````` (double backticks) |
+------------------------+---------------------------------------------------+
| **Syntax** | `` ``m1.small`` `` |
+------------------------+---------------------------------------------------+
| **Example of output** | The following command launches an instance with |
| | the ``m1.small`` flavor. |
+------------------------+---------------------------------------------------+
Command
~~~~~~~
An inline sub-command for the command-line interfaces and inline command for
different operating systems.
+------------------------+---------------------------------------------------+
| **Markup** | ``:command:`` |
+------------------------+---------------------------------------------------+
| **Syntax** | ``:command:`nova boot``` |
+------------------------+---------------------------------------------------+
| **Example of output** | Run the :command:`nova boot` command to launch |
| | an instance. |
+------------------------+---------------------------------------------------+
File name and path
~~~~~~~~~~~~~~~~~~
Any part of a path specification, including device name, directory, file
name, and extension.
+------------------------+---------------------------------------------------+
| **Markup** | `````` (double backticks) |
+------------------------+---------------------------------------------------+
| **Syntax** | ````nova.conf```` |
+------------------------+---------------------------------------------------+
| **Example of output** | By default, the ``nova.conf`` configuration |
| | file is installed in the ``/etc/nova`` folder. |
+------------------------+---------------------------------------------------+
Glossary entry
~~~~~~~~~~~~~~
A term that appears in the glossary.
+------------------------+---------------------------------------------------+
| **Markup** | ``:term:`` |
+------------------------+---------------------------------------------------+
| **Syntax** | ``:term:`bare``` |
+------------------------+---------------------------------------------------+
| **Example of output** | |
+------------------------+---------------------------------------------------+
GUI element
~~~~~~~~~~~
Any part of interactive user interface.
+------------------------+---------------------------------------------------+
| **Markup** | ``:guilabel:`` |
+------------------------+---------------------------------------------------+
| **Syntax** | ``:guilabel:`Project tab``` |
+------------------------+---------------------------------------------------+
| **Example of output** | From the :guilabel:`Project tab` you can view and |
| | manage the resources in a selected project. |
+------------------------+---------------------------------------------------+
Keyboard key combination
~~~~~~~~~~~~~~~~~~~~~~~~
A sequence of two or more keystrokes or mouse actions.
+------------------------+---------------------------------------------------+
| **Markup** | `````` (double backticks) |
+------------------------+---------------------------------------------------+
| **Syntax** | ````Ctrl+A```` |
+------------------------+---------------------------------------------------+
| **Example of output** | Press ``Ctrl+A`` to switch between services. |
+------------------------+---------------------------------------------------+
Menu sequence
~~~~~~~~~~~~~
An action of navigating a menu to select an item one or more levels down.
+------------------------+---------------------------------------------------+
| **Markup** | ``:menuselection:`` |
+------------------------+---------------------------------------------------+
| **Syntax** | ``:menuselection:`Project > Compute``` |
+------------------------+---------------------------------------------------+
| **Example of output** | Go to the :menuselection:`Project > Compute` tab. |
+------------------------+---------------------------------------------------+
Parameter
~~~~~~~~~
Any parameter for sub-commands for the command-line interfaces.
+------------------------+---------------------------------------------------+
| **Markup** | ``:option:`` to mark parameters that start with |
| | ``-`` or ``--``, `````` (double backticks) for |
| | any other parameter |
+------------------------+---------------------------------------------------+
| **Syntax** | ``:option:`--template-url```, ````back end```` |
+------------------------+---------------------------------------------------+
| **Example of output** | * You can specify the URL with the |
| | :option:`--template-url` parameter. |
| | * Set the ``back end`` parameter. |
+------------------------+---------------------------------------------------+
Option
~~~~~~
Any option for sub-commands for the command-line interfaces or configuration
option.
+------------------------+---------------------------------------------------+
| **Markup** | ``:option:`` to mark options that start with |
| | ``-`` or ``--``, `````` (double backticks) for |
| | any other parameter |
+------------------------+---------------------------------------------------+
| **Syntax** | ``:option:`--parent```, |
| | ````force_dhcp_release = True```` |
+------------------------+---------------------------------------------------+
| **Example of output** | * The :option:`--parent` stands for the parent of |
| | the project (name or ID). |
| | * The ``force_dhcp_release = True`` option sends |
| | a dhcp release on instance termination. |
+------------------------+---------------------------------------------------+
.. note::
When documenting Boolean configuration options:
* Explicitly include the truth value
* Add spaces around the equal sign (``=``)
**Correct usage**
::
force_dhcp_release = True
use_ipv6 = False
Variable
~~~~~~~~
A literal text with a *variable* part in it wrapped in curly braces.
+------------------------+---------------------------------------------------+
| **Markup** | ``:samp:`` to mark variables with curly braces. |
| | Do not add any additional formatting |
| | to the replaceable text. |
+------------------------+---------------------------------------------------+
| **Syntax** | ``:samp:`--flavor {FLAVOR}``` |
+------------------------+---------------------------------------------------+
| **Example of output** | Use the :samp:`--flavor {FLAVOR}` parameter to |
| | specify the ID or name of the flavor. |
+------------------------+---------------------------------------------------+

130
doc/contributor-guide/source/rst-conv/lists.rst Normal file
View File

@@ -0,0 +1,130 @@
=====
Lists
=====
Select the appropriate list type to present a sequence of items.
Enumerated lists
~~~~~~~~~~~~~~~~
Use the enumerated list formatting for a sequence of items whose order
matters.
**Input**
.. code::
During the migration process the target host:
#. Ensures that live migration is enabled.
#. Installs the base VHD if it is not already present.
**Output**
During the migration process the target host:
#. Ensures that live migration is enabled.
#. Installs the base VHD if it is not already present.
Bulleted lists
~~~~~~~~~~~~~~
Use the bulleted list for a sequence of items that can happen in any order
or whose order does not matter.
**Input**
.. code::
Valid formats include:
* PNG
* JPG
* GIF
* SVG
**Output**
Valid formats include:
* PNG
* JPG
* GIF
* SVG
Definition lists
~~~~~~~~~~~~~~~~
Use the definition list for an unordered list in which each item has a short
term. For example, key, option, or phrase, followed by its definition.
Consider using a variable list instead of:
* An itemized list when your list has a regular pattern of key/value or
term/definition pairs.
* A two column table where the first column lists items of a consistent type
and the second column describes the items.
**Input**
.. code::
Spellchecking
Process of correcting spelling
Pagebreaking
Process of breaking pages
**Output**
Spellchecking
Process of correcting spelling
Pagebreaking
Process of breaking pages
Mixed lists
~~~~~~~~~~~
Use the mixed types of lists to nest lists of different types.
**Input**
.. code::
#. The system exposes these components to users:
Component A
Description of A.
Component B
Description of B.
Component C
Description of C. Note: C is available only for these OS's:
* Linux
* Mac OS X
#. API libraries are available.
**Output**
#. The system exposes these components to users:
Component A
Description of A.
Component B
Description of B.
Component C
Description of C. Note: C is available only for these OS's:
* Linux
* Mac OS X
#. API libraries are also available.

55
doc/contributor-guide/source/rst-conv/profiling.rst Normal file
View File

@@ -0,0 +1,55 @@
===============================
Profiling (conditional content)
===============================
Installation Guides has content that depends upon the operating systems.
Use the ``only`` directive to specify the content that is operating-system
specific. Define one or several tags depending on the operating system
the content belongs to.
The valid tags for the ``only`` directive are:
* ``ubuntu`` for Ubuntu
* ``debian`` for Debian
* ``rdo`` for Red Hat Enterprise Linux, CentOS, and Fedora
* ``obs`` for openSUSE and SUSE Linux Enterprise
**Input**
.. code::
Install the NTP service
-----------------------
.. only:: ubuntu or debian
.. code-block:: console
# apt-get install chrony
.. only:: rdo
.. code-block:: console
# yum install chrony
.. only:: obs
On openSUSE:
.. code-block:: console
# zypper addrepo http://download.opensuse.org/repositories/network:time/openSUSE_13.2/network:time.repo
...
On SLES:
.. code-block:: console
# zypper addrepo http://download.opensuse.org/repositories/network:time/SLE_12/network:time.repo
...
For more details refer to `Including content based on tags
<http://sphinx.readthedocs.org/en/latest/markup/misc.html?highlight=only%20directive#including-content-based-on-tags>`_.

87
doc/contributor-guide/source/rst-conv/refs.rst Normal file
View File

@@ -0,0 +1,87 @@
==========
References
==========
Cross-references
~~~~~~~~~~~~~~~~
To cross-reference to arbitrary locations within one document,
use the ``ref`` role:
**Input**
.. code::
.. _cg_titles:
Titles
~~~~~~
This is the section we want to reference to.
...
The following - :ref:`cg_titles` - generates a link to the section with
the defined label using this section heading as a link title.
A link label and a reference can be defined in separate source files,
but within one directory. Otherwise, use the external linking.
**Output**
...
The following - :ref:`cg_titles` - generates a link to the section with
the defined label using this section heading as a link title.
A link label and a reference can be defined in separate source files,
but within one directory. Otherwise, use the external linking.
External references
~~~~~~~~~~~~~~~~~~~
To link to some external locations, format RST source as follows:
* Do not apply any markups to specify a web link.
* If you need a specific link title to appear in the output,
format a web link as ``Link text <http://web-link.com>``
wrapping it in backticks.
* If a source file contains a big number of external references,
you can separate a link from its definition for better readability
while reviewing as shown in the example.
**Input**
.. code::
Here is a link to the User guide: http://docs.openstack.org/user-guide/.
Here is an external web link with a link title:
`User guide <http://docs.openstack.org/user-guide/>`_.
Here is an external web link separated from its definition:
This paragraph contains the link to `User guide`_.
...
.. format the link definition at the end of the file as follows:
.. _`User guide`: http://docs.openstack.org/user-guide/
**Output**
Here is a link to the User guide: http://docs.openstack.org/user-guide/.
Here is an external web link with a link title:
`User guide <http://docs.openstack.org/user-guide/>`_.
Here is an external web link separated from its definition:
This paragraph contains the link to `User guide`_.
...
.. format the link definition at the end of the file as follows:
.. _`User guide`: http://docs.openstack.org/user-guide/

90
doc/contributor-guide/source/rst-conv/source-code.rst Normal file
View File

@@ -0,0 +1,90 @@
============
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, use the ``code-block`` directive
as described in the :ref:`non-standard-block` section.
**Input**
.. code::
Add logging statements::
from nova.openstack.common import log as logging
LOG = logging.getLogger(__name__)
**Output**
Add logging statements::
from nova.openstack.common import log as logging
LOG = logging.getLogger(__name__)
.. _non-standard-block:
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. |
+------------------+---------------------------------------------------------+
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.
**Input**
.. code::
.. code-block:: ini
# 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 ',').
**Output**
.. code-block:: ini
# 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 ',').

48
doc/contributor-guide/source/rst-conv/spec-info.rst Normal file
View File

@@ -0,0 +1,48 @@
===========================
Specific information blocks
===========================
Use special markups to emphasize specific information within your document.
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.
A 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,
* ...

127
doc/contributor-guide/source/rst-conv/tables.rst Normal file
View File

@@ -0,0 +1,127 @@
======
Tables
======
Graphic tables
~~~~~~~~~~~~~~
Use the graphic table formatting for the content that presupposes short
lines of text and a small number of rows and columns.
.. note::
As the graphic tables are rather difficult to create and maintain,
give the preference to list and CSV tables over the graphic ones,
or format the content as definition lists where possible.
**Input**
.. code::
============ ========= =============== =============
Flavor VCPUs Disk (in GB) RAM (in MB)
============ ========= =============== =============
m1.tiny 1 1 512
m1.small 1 20 2048
m1.medium 2 40 4096
m1.large 4 80 8192
m1.xlarge 8 160 16384
============ ========= =============== =============
**Output**
============ ========= =============== =============
Flavor VCPUs Disk (in GB) RAM (in MB)
============ ========= =============== =============
m1.tiny 1 1 1
m1.small 1 20 2048
m1.medium 2 40 4096
m1.large 4 80 8192
m1.xlarge 8 160 16384
============ ========= =============== =============
List tables
~~~~~~~~~~~
Use the ``list-table`` directive to create a table that contains a large
number of raws and columns with the long lines within the cells.
**Input**
.. code::
.. list-table:: **Quota descriptions**
:widths: 10 25 10
:header-rows: 1
* - Quota Name
- Defines the number of
- Service
* - Gigabytes
- Volume gigabytes allowed for each project
- Block Storage
* - Instances
- Instances allowed for each project.
- Compute
* - Injected File Content Bytes
- Content bytes allowed for each injected file.
- Compute
**Output**
.. list-table:: **Quota descriptions**
:widths: 10 25 10
:header-rows: 1
* - Quota Name
- Defines the number of
- Service
* - Gigabytes
- Volume gigabytes allowed for each project
- Block Storage
* - Instances
- Instances allowed for each project.
- Compute
* - Injected File Content Bytes
- Content bytes allowed for each injected file.
- Compute
CSV tables
~~~~~~~~~~
The ``csv-table`` directive enables creating a table from CSV
(comma-separated values) data. It also supports RST inline markups,
such as, emphasis, strong emphasis markups, code, command, and other
directives.
**Input**
.. code::
.. csv-table:: **ipv6_ra_mode and ipv6_address_mode combinations**
:header: ipv6 ra mode, ipv6 address mode, "radvd A,M,O", "External Router A,M,O", Description
:widths: 2, 2, 2, 2, 4
*N/S*, *N/S*, Off, Not Defined, Backwards compatibility with pre-Juno IPv6 behavior.
*N/S*, slaac, Off, "1,0,0", Guest instance obtains IPv6 address from non-OpenStack
*N/S*, dhcpv6-stateful, Off, "0,1,1", Not currently implemented in the reference implementation.
**Output**
.. csv-table:: **ipv6_ra_mode and ipv6_address_mode combinations**
:header: ipv6 ra mode, ipv6 address mode, "radvd A,M,O", "External Router A,M,O", Description
:widths: 2, 2, 2, 2, 4
*N/S*, *N/S*, Off, Not Defined, Backwards compatibility with pre-Juno IPv6 behavior.
*N/S*, slaac, Off, "1,0,0", Guest instance obtains IPv6 address from non-OpenStack
*N/S*, dhcpv6-stateful, Off, "0,1,1", Not currently implemented in the reference implementation.
Useful links on table formatting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* `Graphic tables formatting details <http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables>`_
* `List tables formatting details <http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table>`_
* `CSV tables formatting details <http://docutils.sourceforge.net/docs/ref/rst/directives.html#id48>`_

52
doc/contributor-guide/source/rst-conv/titles.rst Normal file
View File

@@ -0,0 +1,52 @@
.. _cg_titles:
======
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.