Merge "[contributor] reorganize RST/JSON conventions"
This commit is contained in:
commit
aa927308b5
|
@ -31,7 +31,7 @@ Contents
|
||||||
writing-style.rst
|
writing-style.rst
|
||||||
ui-text-guidelines.rst
|
ui-text-guidelines.rst
|
||||||
rst-conv.rst
|
rst-conv.rst
|
||||||
json-conventions.rst
|
json-conv.rst
|
||||||
tools-and-content-overview.rst
|
tools-and-content-overview.rst
|
||||||
docs-builds.rst
|
docs-builds.rst
|
||||||
build-locally.rst
|
build-locally.rst
|
||||||
|
|
|
@ -1,11 +1,10 @@
|
||||||
.. _json:
|
.. _json_conv:
|
||||||
|
|
||||||
================
|
================
|
||||||
JSON conventions
|
JSON conventions
|
||||||
================
|
================
|
||||||
|
|
||||||
JSON formatting conventions
|
OpenStack uses JSON format. Use the following JSON formatting conventions:
|
||||||
---------------------------
|
|
||||||
|
|
||||||
* Format JSON files to be human readable.
|
* Format JSON files to be human readable.
|
||||||
* Use four spaces for indentation (matching OpenStack conventions used in
|
* Use four spaces for indentation (matching OpenStack conventions used in
|
|
@ -1,8 +1,8 @@
|
||||||
.. _rst_conv:
|
.. _rst_conv:
|
||||||
|
|
||||||
==========================
|
===============
|
||||||
RST formatting conventions
|
RST conventions
|
||||||
==========================
|
===============
|
||||||
|
|
||||||
OpenStack documentation uses reStructuredText (RST) markup syntax
|
OpenStack documentation uses reStructuredText (RST) markup syntax
|
||||||
with Sphinx extensions.
|
with Sphinx extensions.
|
||||||
|
@ -26,27 +26,23 @@ use simpler formatting.
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
rst-conv/gen-guidelines.rst
|
rst-conv/general-guidelines.rst
|
||||||
rst-conv/titles.rst
|
rst-conv/titles.rst
|
||||||
rst-conv/inline-markups.rst
|
rst-conv/inline-markups.rst
|
||||||
rst-conv/lists.rst
|
rst-conv/lists.rst
|
||||||
rst-conv/spec-info.rst
|
rst-conv/specific-info.rst
|
||||||
rst-conv/source-code.rst
|
rst-conv/source-code.rst
|
||||||
rst-conv/refs.rst
|
rst-conv/references.rst
|
||||||
rst-conv/tables.rst
|
rst-conv/tables.rst
|
||||||
rst-conv/figures.rst
|
rst-conv/figures.rst
|
||||||
rst-conv/profiling.rst
|
rst-conv/profiling.rst
|
||||||
rst-conv/comment.rst
|
rst-conv/comment.rst
|
||||||
rst-conv/decor.rst
|
rst-conv/decorations.rst
|
||||||
|
|
||||||
|
|
||||||
Useful links
|
Useful links
|
||||||
~~~~~~~~~~~~
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
* `Sphinx documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`_
|
* `Sphinx documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`_
|
||||||
|
|
||||||
* `reStructuredText: Markup Syntax and Parser Component of Docutils
|
* `reStructuredText: Markup Syntax and Parser Component of Docutils
|
||||||
<http://docutils.sourceforge.net/rst.html>`_
|
<http://docutils.sourceforge.net/rst.html>`_
|
||||||
|
|
||||||
* `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
|
* `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
|
||||||
|
|
||||||
|
|
|
@ -6,14 +6,12 @@ Indicate a comment by means of the ``..`` marker.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
.. This is a comment. It is not visible in the documentation build.
|
.. This is a comment. It is not visible in the documentation build.
|
||||||
Generally, use it to include TODO within the content followed
|
Generally, use it to include TODO within the content followed
|
||||||
by the initials of the person who is to perform the action.
|
by the initials of the person who is to perform the action.
|
||||||
|
|
||||||
For example:
|
For example:
|
||||||
|
|
||||||
.. TODO(OG): add a link to the Decorations section when it is available.
|
|
||||||
|
|
||||||
|
|
||||||
|
.. TODO(OG): add a link to the Decorations section when it is available.
|
||||||
|
|
|
@ -10,7 +10,6 @@ This section contains a number of bells and whistles that are neither
|
||||||
conventions nor even recommendations, but extra features of RST markup
|
conventions nor even recommendations, but extra features of RST markup
|
||||||
syntax for general educational purposes.
|
syntax for general educational purposes.
|
||||||
|
|
||||||
|
|
||||||
Adding a horizontal line
|
Adding a horizontal line
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
@ -19,7 +18,7 @@ by typing four ``-`` (hyphen) in a row adding blank lines before and after.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
Paragraph 1
|
Paragraph 1
|
||||||
|
|
||||||
|
@ -35,7 +34,6 @@ Paragraph 1
|
||||||
|
|
||||||
Paragraph 2
|
Paragraph 2
|
||||||
|
|
||||||
|
|
||||||
Starting a new line
|
Starting a new line
|
||||||
~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
@ -43,7 +41,7 @@ Use ``|`` (vertical bar) followed by a single white space to start a new line.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
| The first line of text.
|
| The first line of text.
|
||||||
| The second line of text (new line).
|
| The second line of text (new line).
|
||||||
|
@ -63,7 +61,7 @@ space between two content elements.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
Paragraph 1
|
Paragraph 1
|
||||||
|
|
||||||
|
@ -78,4 +76,3 @@ Paragraph 1
|
||||||
|
|
|
|
||||||
|
|
||||||
Paragraph 2
|
Paragraph 2
|
||||||
|
|
|
@ -14,7 +14,7 @@ preferred.
|
||||||
|
|
||||||
**Syntax**
|
**Syntax**
|
||||||
|
|
||||||
::
|
.. code-block:: none
|
||||||
|
|
||||||
.. figure:: file_name.file_extension
|
.. figure:: file_name.file_extension
|
||||||
:option: option_value
|
:option: option_value
|
||||||
|
@ -32,4 +32,6 @@ The figure directive supports the following options:
|
||||||
For descriptions of the options and their possible values, refer to the
|
For descriptions of the options and their possible values, refer to the
|
||||||
`Docutils documentation <http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure>`_.
|
`Docutils documentation <http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure>`_.
|
||||||
|
|
||||||
For details on figure titles, see :ref:`figure_table_titles`.
|
.. seealso::
|
||||||
|
|
||||||
|
For the style guidelines on figure titles, see :ref:`figure_table_titles`.
|
||||||
|
|
|
@ -46,4 +46,3 @@ Use indentation to format the nested content within:
|
||||||
|
|
||||||
For more information on how to format elements from the list above,
|
For more information on how to format elements from the list above,
|
||||||
see the related section of this chapter.
|
see the related section of this chapter.
|
||||||
|
|
|
@ -23,7 +23,6 @@ To insert a semantic markup into your document, use the syntax below.
|
||||||
|
|
||||||
:markup:`inline text`
|
:markup:`inline text`
|
||||||
|
|
||||||
|
|
||||||
Application
|
Application
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
@ -205,5 +204,3 @@ A literal text with a *variable* part in it wrapped in curly braces.
|
||||||
| **Example of output** | Use the :samp:`--flavor {FLAVOR}` parameter to |
|
| **Example of output** | Use the :samp:`--flavor {FLAVOR}` parameter to |
|
||||||
| | specify the ID or name of the flavor. |
|
| | specify the ID or name of the flavor. |
|
||||||
+------------------------+---------------------------------------------------+
|
+------------------------+---------------------------------------------------+
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -12,7 +12,7 @@ matters.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
During the migration process the target host:
|
During the migration process the target host:
|
||||||
|
|
||||||
|
@ -34,7 +34,7 @@ or whose order does not matter.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
Valid formats include:
|
Valid formats include:
|
||||||
|
|
||||||
|
@ -68,7 +68,7 @@ Consider using a variable list instead of:
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
Spellchecking
|
Spellchecking
|
||||||
Process of correcting spelling
|
Process of correcting spelling
|
||||||
|
@ -91,7 +91,7 @@ Use the mixed types of lists to nest lists of different types.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
#. The system exposes these components to users:
|
#. The system exposes these components to users:
|
||||||
|
|
||||||
|
@ -126,5 +126,3 @@ Use the mixed types of lists to nest lists of different types.
|
||||||
* Mac OS X
|
* Mac OS X
|
||||||
|
|
||||||
#. API libraries are also available.
|
#. API libraries are also available.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -17,7 +17,7 @@ The valid tags for the ``only`` directive are:
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
Install the NTP service
|
Install the NTP service
|
||||||
-----------------------
|
-----------------------
|
||||||
|
@ -52,4 +52,3 @@ The valid tags for the ``only`` directive are:
|
||||||
|
|
||||||
For more details refer to `Including content based on tags
|
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>`_.
|
<http://sphinx.readthedocs.org/en/latest/markup/misc.html?highlight=only%20directive#including-content-based-on-tags>`_.
|
||||||
|
|
||||||
|
|
|
@ -10,7 +10,7 @@ use the ``ref`` role:
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
.. _cg_titles:
|
.. _cg_titles:
|
||||||
|
|
||||||
|
@ -54,7 +54,7 @@ To link to some external locations, format the RST source as follows:
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
Here is a link to the User guide: http://docs.openstack.org/user-guide/.
|
Here is a link to the User guide: http://docs.openstack.org/user-guide/.
|
||||||
|
|
|
@ -32,7 +32,7 @@ as described in the :ref:`non-standard-block` section.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
Add logging statements::
|
Add logging statements::
|
||||||
|
|
||||||
|
@ -46,7 +46,6 @@ Add logging statements::
|
||||||
from nova.openstack.common import log as logging
|
from nova.openstack.common import log as logging
|
||||||
LOG = logging.getLogger(__name__)
|
LOG = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
|
||||||
.. _non-standard-block:
|
.. _non-standard-block:
|
||||||
|
|
||||||
Non-standard literal block
|
Non-standard literal block
|
||||||
|
@ -70,7 +69,7 @@ files, ``console`` for console inputs and outputs, and so on.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
|
|
||||||
|
@ -121,7 +120,7 @@ content from a remote URL (``http`` or ``https``).
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
.. remote-code-block:: ini
|
.. remote-code-block:: ini
|
||||||
|
|
||||||
|
|
|
@ -13,14 +13,14 @@ Depending on specific semantic meaning of the message, you can use:
|
||||||
* **caution** - delivers information that prevents a user from mistakes
|
* **caution** - delivers information that prevents a user from mistakes
|
||||||
and undesirable consequences when following the procedures.
|
and undesirable consequences when following the procedures.
|
||||||
|
|
||||||
* **tip** - wraps extra but helpful information.
|
* **tip** or **seealso** - wraps extra but helpful information.
|
||||||
|
|
||||||
Here is the example of the note directive usage; these can be applied to all
|
Here is the example of the note directive usage; these can be applied to all
|
||||||
the admonition directives described above.
|
the admonition directives described above.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
|
@ -45,4 +45,3 @@ the admonition directives described above.
|
||||||
|
|
||||||
* First option,
|
* First option,
|
||||||
* ...
|
* ...
|
||||||
|
|
|
@ -11,7 +11,7 @@ formatting details.
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
|
|
||||||
:ref:`figure_table_titles`
|
For the style guidelines on table titles, see :ref:`figure_table_titles`.
|
||||||
|
|
||||||
Graphic tables
|
Graphic tables
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
@ -27,7 +27,7 @@ lines of text and a small number of rows and columns.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
.. table:: **Default flavors**
|
.. table:: **Default flavors**
|
||||||
|
|
||||||
|
@ -63,7 +63,7 @@ number of rows and columns with the long lines within the cells.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
.. list-table:: **Quota descriptions**
|
.. list-table:: **Quota descriptions**
|
||||||
:widths: 10 25 10
|
:widths: 10 25 10
|
||||||
|
@ -111,15 +111,15 @@ directives.
|
||||||
|
|
||||||
**Input**
|
**Input**
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
.. csv-table:: **ipv6_ra_mode and ipv6_address_mode combinations**
|
.. 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
|
:header: ipv6 ra mode, ipv6 address mode, "radvd A,M,O", "External Router A,M,O", Description
|
||||||
:widths: 2, 2, 2, 2, 4
|
:widths: 2, 2, 2, 2, 4
|
||||||
|
|
||||||
*N/S*, *N/S*, Off, Not Defined, Backwards compatibility with pre-Juno IPv6 behavior.
|
*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*, 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.
|
*N/S*, dhcpv6-stateful, Off, "0,1,1", Not currently implemented in the reference implementation.
|
||||||
|
|
||||||
**Output**
|
**Output**
|
||||||
|
|
||||||
|
@ -131,12 +131,12 @@ directives.
|
||||||
*N/S*, slaac, Off, "1,0,0", Guest instance obtains IPv6 address from non-OpenStack
|
*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.
|
*N/S*, dhcpv6-stateful, Off, "0,1,1", Not currently implemented in the reference implementation.
|
||||||
|
|
||||||
|
|
||||||
Useful links on table formatting
|
Useful links on table formatting
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
* `Graphic tables formatting details <http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables>`_
|
* `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>`_
|
* `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>`_
|
* `CSV tables formatting details
|
||||||
|
<http://docutils.sourceforge.net/docs/ref/rst/directives.html#id48>`_
|
||||||
|
|
Loading…
Reference in New Issue