Merge "[contributor] reorganize RST/JSON conventions"

doc/contributor-guide/source/index.rst

@@ -31,7 +31,7 @@ Contents
    writing-style.rst
    ui-text-guidelines.rst
    rst-conv.rst
-   json-conventions.rst
+   json-conv.rst
    tools-and-content-overview.rst
    docs-builds.rst
    build-locally.rst

doc/contributor-guide/source/json-conv.rst

@@ -1,11 +1,10 @@
-.. _json:
+.. _json_conv:
 
 ================
 JSON conventions
 ================
 
-JSON formatting conventions
+OpenStack uses JSON format. Use the following JSON formatting conventions:
----------------------------
 
 * Format JSON files to be human readable.
 * Use four spaces for indentation (matching OpenStack conventions used in

doc/contributor-guide/source/rst-conv.rst

@@ -1,8 +1,8 @@
 .. _rst_conv:
 
-==========================
+===============
-RST formatting conventions
+RST conventions
-==========================
+===============
 
 OpenStack documentation uses reStructuredText (RST) markup syntax
 with Sphinx extensions.
@@ -26,27 +26,23 @@ use simpler formatting.
 .. toctree::
    :maxdepth: 2
 
-   rst-conv/gen-guidelines.rst
+   rst-conv/general-guidelines.rst
    rst-conv/titles.rst
    rst-conv/inline-markups.rst
    rst-conv/lists.rst
-   rst-conv/spec-info.rst
+   rst-conv/specific-info.rst
    rst-conv/source-code.rst
-   rst-conv/refs.rst
+   rst-conv/references.rst
    rst-conv/tables.rst
    rst-conv/figures.rst
    rst-conv/profiling.rst
    rst-conv/comment.rst
-   rst-conv/decor.rst
+   rst-conv/decorations.rst
-
 
 Useful links
 ~~~~~~~~~~~~
 
 * `Sphinx documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`_
-
 * `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>`_
-

doc/contributor-guide/source/rst-conv/comment.rst

@@ -6,14 +6,12 @@ Indicate a comment by means of the ``..`` marker.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    .. 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:
+   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.

doc/contributor-guide/source/rst-conv/decorations.rst

@@ -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
 syntax for general educational purposes.
 
-
 Adding a horizontal line
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -19,7 +18,7 @@ by typing four ``-`` (hyphen) in a row adding blank lines before and after.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    Paragraph 1
 
@@ -35,7 +34,6 @@ Paragraph 1
 
 Paragraph 2
 
-
 Starting a new line
 ~~~~~~~~~~~~~~~~~~~
 
@@ -43,7 +41,7 @@ Use ``|`` (vertical bar) followed by a single white space to start a new line.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    | The first line of text.
    | The second line of text (new line).
@@ -63,7 +61,7 @@ space between two content elements.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    Paragraph 1
 
@@ -78,4 +76,3 @@ Paragraph 1
 |
 
 Paragraph 2
-

doc/contributor-guide/source/rst-conv/figures.rst

@@ -14,7 +14,7 @@ preferred.
 
 **Syntax**
 
-::
+.. code-block:: none
 
   .. figure:: file_name.file_extension
      :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
 `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`.

doc/contributor-guide/source/rst-conv/general-guidelines.rst

@@ -46,4 +46,3 @@ Use indentation to format the nested content within:
 
 For more information on how to format elements from the list above,
 see the related section of this chapter.
-

doc/contributor-guide/source/rst-conv/inline-markups.rst

@@ -23,7 +23,6 @@ To insert a semantic markup into your document, use the syntax below.
 
   :markup:`inline text`
 
-
 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    |
 |                        | specify the ID or name of the flavor.             |
 +------------------------+---------------------------------------------------+
-
-

doc/contributor-guide/source/rst-conv/lists.rst

@@ -12,7 +12,7 @@ matters.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    During the migration process the target host:
 
@@ -34,7 +34,7 @@ or whose order does not matter.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
   Valid formats include:
 
@@ -68,7 +68,7 @@ Consider using a variable list instead of:
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    Spellchecking
     Process of correcting spelling
@@ -91,7 +91,7 @@ Use the mixed types of lists to nest lists of different types.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    #. 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
 
 #. API libraries are also available.
-
-

doc/contributor-guide/source/rst-conv/profiling.rst

@@ -17,7 +17,7 @@ The valid tags for the ``only`` directive are:
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    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
 <http://sphinx.readthedocs.org/en/latest/markup/misc.html?highlight=only%20directive#including-content-based-on-tags>`_.
-

doc/contributor-guide/source/rst-conv/references.rst

@@ -10,7 +10,7 @@ use the ``ref`` role:
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    .. _cg_titles:
 
@@ -54,7 +54,7 @@ To link to some external locations, format the RST source as follows:
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    Here is a link to the User guide: http://docs.openstack.org/user-guide/.
 

doc/contributor-guide/source/rst-conv/source-code.rst

@@ -32,7 +32,7 @@ as described in the :ref:`non-standard-block` section.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    Add logging statements::
 
@@ -46,7 +46,6 @@ Add logging statements::
   from nova.openstack.common import log as logging
   LOG = logging.getLogger(__name__)
 
-
 .. _non-standard-block:
 
 Non-standard literal block
@@ -70,7 +69,7 @@ files, ``console`` for console inputs and outputs, and so on.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    .. code-block:: ini
 
@@ -121,7 +120,7 @@ content from a remote URL (``http`` or ``https``).
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    .. remote-code-block:: ini
 

doc/contributor-guide/source/rst-conv/specific-info.rst

@@ -13,14 +13,14 @@ Depending on specific semantic meaning of the message, you can use:
 * **caution** - delivers information that prevents a user from mistakes
   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
 the admonition directives described above.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    .. note::
 
@@ -45,4 +45,3 @@ the admonition directives described above.
 
    * First option,
    * ...
-

doc/contributor-guide/source/rst-conv/tables.rst

@@ -11,7 +11,7 @@ formatting details.
 
 .. seealso::
 
-   :ref:`figure_table_titles`
+   For the style guidelines on table titles, see :ref:`figure_table_titles`.
 
 Graphic tables
 ~~~~~~~~~~~~~~
@@ -27,7 +27,7 @@ lines of text and a small number of rows and columns.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    .. table:: **Default flavors**
 
@@ -63,7 +63,7 @@ number of rows and columns with the long lines within the cells.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    .. list-table:: **Quota descriptions**
       :widths: 10 25 10
@@ -111,15 +111,15 @@ directives.
 
 **Input**
 
-.. code::
+.. code-block:: none
 
    .. 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**
 
@@ -131,12 +131,12 @@ directives.
    *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>`_
+* `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>`_