openstack/openstack-manuals
Code Issues Proposed changes

[contributor] reorganize RST/JSON conventions

Browse Source 
Change-Id: Idac1e6c049438819d5c363b694102c22d67fa19b
Implements: blueprint contributor-guide-reorg
This commit is contained in:
KATO Tomoyuki 2016-07-10 08:17:27 +09:00 committed by Olena Logvinova
parent e3f4faba77
commit f06e866917
14 changed files with 47 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/contributor-guide/source/index.rst
View File

@ -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

5
doc/contributor-guide/source/json-conventions.rst → doc/contributor-guide/source/json-conv.rst
View File

@ -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

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

@ -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>`_

8
doc/contributor-guide/source/rst-conv/comment.rst
View File

@ -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.

9
doc/contributor-guide/source/rst-conv/decor.rst → doc/contributor-guide/source/rst-conv/decorations.rst
View File

@ -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

6
doc/contributor-guide/source/rst-conv/figures.rst
View File

@ -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`.

1
doc/contributor-guide/source/rst-conv/gen-guidelines.rst → doc/contributor-guide/source/rst-conv/general-guidelines.rst
View File

@ -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.

3
doc/contributor-guide/source/rst-conv/inline-markups.rst
View File

@ -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. |
+------------------------+---------------------------------------------------+

10
doc/contributor-guide/source/rst-conv/lists.rst
View File

@ -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.

3
doc/contributor-guide/source/rst-conv/profiling.rst
View File

@ -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>`_.

4
doc/contributor-guide/source/rst-conv/refs.rst → doc/contributor-guide/source/rst-conv/references.rst
View File

@ -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/.

7
doc/contributor-guide/source/rst-conv/source-code.rst
View File

@ -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

5
doc/contributor-guide/source/rst-conv/spec-info.rst → doc/contributor-guide/source/rst-conv/specific-info.rst
View File

@ -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,
* ...

30
doc/contributor-guide/source/rst-conv/tables.rst
View File

@ -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 <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>`_
* `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>`_