From f06e86691702fbde44f6ddb8c6934a6acc2f8318 Mon Sep 17 00:00:00 2001 From: KATO Tomoyuki Date: Sun, 10 Jul 2016 08:17:27 +0900 Subject: [PATCH] [contributor] reorganize RST/JSON conventions Change-Id: Idac1e6c049438819d5c363b694102c22d67fa19b Implements: blueprint contributor-guide-reorg --- doc/contributor-guide/source/index.rst | 2 +- .../{json-conventions.rst => json-conv.rst} | 5 ++-- doc/contributor-guide/source/rst-conv.rst | 18 +++++------ .../source/rst-conv/comment.rst | 8 ++--- .../rst-conv/{decor.rst => decorations.rst} | 9 ++---- .../source/rst-conv/figures.rst | 6 ++-- ...-guidelines.rst => general-guidelines.rst} | 1 - .../source/rst-conv/inline-markups.rst | 3 -- .../source/rst-conv/lists.rst | 10 +++---- .../source/rst-conv/profiling.rst | 3 +- .../rst-conv/{refs.rst => references.rst} | 4 +-- .../source/rst-conv/source-code.rst | 7 ++--- .../{spec-info.rst => specific-info.rst} | 5 ++-- .../source/rst-conv/tables.rst | 30 +++++++++---------- 14 files changed, 47 insertions(+), 64 deletions(-) rename doc/contributor-guide/source/{json-conventions.rst => json-conv.rst} (91%) rename doc/contributor-guide/source/rst-conv/{decor.rst => decorations.rst} (95%) rename doc/contributor-guide/source/rst-conv/{gen-guidelines.rst => general-guidelines.rst} (99%) rename doc/contributor-guide/source/rst-conv/{refs.rst => references.rst} (97%) rename doc/contributor-guide/source/rst-conv/{spec-info.rst => specific-info.rst} (93%) diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index 6bbb873dc0..701e0c95b0 100644 --- a/doc/contributor-guide/source/index.rst +++ b/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 diff --git a/doc/contributor-guide/source/json-conventions.rst b/doc/contributor-guide/source/json-conv.rst similarity index 91% rename from doc/contributor-guide/source/json-conventions.rst rename to doc/contributor-guide/source/json-conv.rst index 6551fe0403..c6718a83a6 100644 --- a/doc/contributor-guide/source/json-conventions.rst +++ b/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 diff --git a/doc/contributor-guide/source/rst-conv.rst b/doc/contributor-guide/source/rst-conv.rst index 4d5228df28..11955bd7c5 100644 --- a/doc/contributor-guide/source/rst-conv.rst +++ b/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 `_ - * `reStructuredText: Markup Syntax and Parser Component of Docutils `_ - * `Quick reStructuredText `_ - diff --git a/doc/contributor-guide/source/rst-conv/comment.rst b/doc/contributor-guide/source/rst-conv/comment.rst index 3d1cf932e9..6841f3b8b2 100644 --- a/doc/contributor-guide/source/rst-conv/comment.rst +++ b/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: - - .. TODO(OG): add a link to the Decorations section when it is available. - + For example: + .. TODO(OG): add a link to the Decorations section when it is available. diff --git a/doc/contributor-guide/source/rst-conv/decor.rst b/doc/contributor-guide/source/rst-conv/decorations.rst similarity index 95% rename from doc/contributor-guide/source/rst-conv/decor.rst rename to doc/contributor-guide/source/rst-conv/decorations.rst index 3a94661177..90c95d737a 100644 --- a/doc/contributor-guide/source/rst-conv/decor.rst +++ b/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 - diff --git a/doc/contributor-guide/source/rst-conv/figures.rst b/doc/contributor-guide/source/rst-conv/figures.rst index 99d39e0e67..9ed98515f1 100644 --- a/doc/contributor-guide/source/rst-conv/figures.rst +++ b/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 `_. -For details on figure titles, see :ref:`figure_table_titles`. +.. seealso:: + + For the style guidelines on figure titles, see :ref:`figure_table_titles`. diff --git a/doc/contributor-guide/source/rst-conv/gen-guidelines.rst b/doc/contributor-guide/source/rst-conv/general-guidelines.rst similarity index 99% rename from doc/contributor-guide/source/rst-conv/gen-guidelines.rst rename to doc/contributor-guide/source/rst-conv/general-guidelines.rst index 885aca0504..cbd8523b0c 100644 --- a/doc/contributor-guide/source/rst-conv/gen-guidelines.rst +++ b/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. - diff --git a/doc/contributor-guide/source/rst-conv/inline-markups.rst b/doc/contributor-guide/source/rst-conv/inline-markups.rst index d80e97e80d..a88f3f98ce 100644 --- a/doc/contributor-guide/source/rst-conv/inline-markups.rst +++ b/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. | +------------------------+---------------------------------------------------+ - - diff --git a/doc/contributor-guide/source/rst-conv/lists.rst b/doc/contributor-guide/source/rst-conv/lists.rst index 1e05864e3c..7165f74b67 100644 --- a/doc/contributor-guide/source/rst-conv/lists.rst +++ b/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. - - diff --git a/doc/contributor-guide/source/rst-conv/profiling.rst b/doc/contributor-guide/source/rst-conv/profiling.rst index 7816a033c6..fcbcf9c7a5 100644 --- a/doc/contributor-guide/source/rst-conv/profiling.rst +++ b/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 `_. - diff --git a/doc/contributor-guide/source/rst-conv/refs.rst b/doc/contributor-guide/source/rst-conv/references.rst similarity index 97% rename from doc/contributor-guide/source/rst-conv/refs.rst rename to doc/contributor-guide/source/rst-conv/references.rst index b8840b6da6..41167651c4 100644 --- a/doc/contributor-guide/source/rst-conv/refs.rst +++ b/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/. diff --git a/doc/contributor-guide/source/rst-conv/source-code.rst b/doc/contributor-guide/source/rst-conv/source-code.rst index e893d8123a..2172a2f094 100644 --- a/doc/contributor-guide/source/rst-conv/source-code.rst +++ b/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 diff --git a/doc/contributor-guide/source/rst-conv/spec-info.rst b/doc/contributor-guide/source/rst-conv/specific-info.rst similarity index 93% rename from doc/contributor-guide/source/rst-conv/spec-info.rst rename to doc/contributor-guide/source/rst-conv/specific-info.rst index 6ff68e2f93..181490b00c 100644 --- a/doc/contributor-guide/source/rst-conv/spec-info.rst +++ b/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, * ... - diff --git a/doc/contributor-guide/source/rst-conv/tables.rst b/doc/contributor-guide/source/rst-conv/tables.rst index aeeb2207bc..765dd6fd8d 100644 --- a/doc/contributor-guide/source/rst-conv/tables.rst +++ b/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 - :widths: 2, 2, 2, 2, 4 + :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. + *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** @@ -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 `_ - -* `List tables formatting details `_ - -* `CSV tables formatting details `_ +* `Graphic tables formatting details + `_ +* `List tables formatting details + `_ +* `CSV tables formatting details + `_