Merge "[Contributor Guide] RST section finished"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
daf50f7774
|
|
@ -1,322 +1,52 @@
|
|||
|
||||
.. _rst_conv:
|
||||
|
||||
==========================
|
||||
RST formatting conventions
|
||||
==========================
|
||||
|
||||
Follow these guidelines for all the RST source files to keep the documentation
|
||||
format consistent.
|
||||
OpenStack documentation uses reStructuredText (RST) markup syntax
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
.. note::
|
||||
|
||||
Exception to this rule is the content of code-block elements and links
|
||||
within the references.
|
||||
All the examples provided in this chapter are for illustration purposes
|
||||
only and cannot be regarded as pieces of true technical information.
|
||||
|
||||
When formatting a table that presupposes long lines of text, give
|
||||
the preference to one of the following methods over the ``table`` directive:
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
* 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.
|
||||
rst-conv/gen-guidelines.rst
|
||||
rst-conv/titles.rst
|
||||
rst-conv/inline-markups.rst
|
||||
rst-conv/lists.rst
|
||||
rst-conv/spec-info.rst
|
||||
rst-conv/source-code.rst
|
||||
rst-conv/refs.rst
|
||||
rst-conv/tables.rst
|
||||
rst-conv/figures.rst
|
||||
rst-conv/profiling.rst
|
||||
rst-conv/comment.rst
|
||||
rst-conv/decor.rst
|
||||
|
||||
|
||||
.. _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.
|
||||
|
||||
|
||||
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
|
||||
Useful links
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Format code snippets as standalone literal blocks. There are several ways
|
||||
to define a code-block within an RST file.
|
||||
* `Sphinx documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`_
|
||||
|
||||
Standard literal block
|
||||
----------------------
|
||||
* `reStructuredText: Markup Syntax and Parser Component of Docutils
|
||||
<http://docutils.sourceforge.net/rst.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/
|
||||
* `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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>`_.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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. |
|
||||
+------------------------+---------------------------------------------------+
|
||||
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
@ -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>`_.
|
||||
|
||||
|
|
@ -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/
|
||||
|
||||
|
||||
|
|
@ -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 ',').
|
||||
|
||||
|
|
@ -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,
|
||||
* ...
|
||||
|
||||
|
|
@ -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>`_
|
||||
|
|
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue