diff --git a/_images/style_guide_titles.png b/_images/style_guide_titles.png new file mode 100644 index 000000000..19ae9a7c5 Binary files /dev/null and b/_images/style_guide_titles.png differ diff --git a/pages/style-guide/0300-coding.rst b/pages/style-guide/0300-coding.rst index 56685a0ca..85741a417 100644 --- a/pages/style-guide/0300-coding.rst +++ b/pages/style-guide/0300-coding.rst @@ -4,3 +4,263 @@ Coding and formatting practices =============================== +Mirantis OpenStack documentation uses reStructuredText (RST) markup syntax +with the Sphinx extensions. This section provides general guidelines on the +coding and formatting rules to follow while contributing. + +Besides, we provide the real-life examples of what you type in a source .rst +file and what you get when you build it. These include references +and cross-links, code-blocks, tables, and other frequently used content elements +and inline markups throughout the Mirantis OpenStack documentation. + + +Titles +------ + +To mark a section heading, underline or underline-and-overline +the heading text using non-alphanumeric characters. + +The generic rules you must always be aware of are: + +* underline and overline must not be shorter than the title text itself; +* the order of the adornment style used for each header level is essential. + +Use the following conventions for headings formatting: + +**Source:** + +:: + + Heading 1 + ========= + A brief overview of the information included in the whole section. + + + Heading 2 + --------- + Content of this subsection. + + + Heading 3 + +++++++++ + Any specific content that is in the child relationship with the Heading 2 + subsection content. + + +**Build:** + +.. image:: /_images/style_guide_titles.png + +Do not go beyond the Heading 3 level. Use the bold markup in case you want to +emphasize the line, for example, :code:`**Heading 4**` + +.. note:: + + In case you are using the `include + `_ + directive, keep in mind that the file you include is deemed to conform + the headings level order of its parent file. + +In addition, precede each Heading 1 with the label. It can be used for +cross-referencing throught the documentation and does not appear in the +build: + +**Source:** + +:: + + .. _syntax-style: + + Writing syntax + ============== + + +Code blocks +----------- + +Use the code-block element to format commands usage and their output samples, +lines of code, and configuration files extracts. + +Format each program source or code snippet as a standalone block. + +To start a code block, use one of the following directives: + +* :code:`::` starts the standard reST literal block; + +* :code:`.. code-block::` allows the code snippet for a specific + programming language optimization. The highlighting is handled with + `Pygments `_. + +It is preferable to use the ``code-block`` directive where possible as the +documentation contains snippets in different programming languages. +For better readability, use the following options with the ``code-block`` +directive: + +* ``linenos`` for automatic code-lines enumeration; + +* ``emphasize-lines`` for particular lines emphasizing. + + +Examples +++++++++ + +The ``bash`` pygments lexer usage. + +**Source:** + +:: + + .. code-block:: bash + cat /proc/cpuinfo | grep --color "vmx\|svm" + +**Build:** + +.. code-block:: bash + + cat /proc/cpuinfo | grep --color "vmx\|svm" + +----- + +The ``python`` pygments lexer usage. It also shows how to highlight definite +lines and apply line enumeration. + +**Source:** + +:: + + .. code-block:: python + :emphasize-lines: 3 + :linenos: + + @property + def total_active_instances(self): + return sum(1 for s in self.server_usages if s['ended_at'] is None) + +**Build:** + +.. code-block:: python + :emphasize-lines: 3 + :linenos: + + @property + def total_active_instances(self): + return sum(1 for s in self.server_usages if s['ended_at'] is None) + +---- + +The ``ruby`` pygments lexer usage. + +**Source:** + +:: + + .. code-block:: ruby + + # See what type of server this is + >> server.flavor.name + => "256 server" + >> server.image.name + => "Ubuntu 8.04.2 LTS (hardy)" + +**Build:** + +.. code-block:: ruby + + # See what type of server this is + >> server.flavor.name + => "256 server" + >> server.image.name + => "Ubuntu 8.04.2 LTS (hardy)" + +----- + +.. seealso:: + + * Sphinx: `Showing code examples `_ + + * Pygments: `Available lexers `_ + + +Notes, warnings, and see also +----------------------------- + +Use notes, warnings, and see also blocks to emphasize special information. + +Notes ++++++ + +Notes include tips, shortcuts, alternative approaches, or any additional +information on the subject. + +**Source:** + +:: + + .. note:: + + The note text. + +**Build:** + +.. note:: + + The note text. + + +Warnings +++++++++ + +Warnings contain the details that can be easily missed, but should not be +ignored. The information included in a warning block is valuable for the user +before proceeding. + +**Source:** + +:: + + .. warning:: + + The warning text. + +**Build:** + +.. warning:: + + The warning text. + + +See also +++++++++ + +See also blocks contain links to external documentation relevant to a subject. + +**Source:** + +:: + + .. seealso:: + + The see also block text. + + +**Build:** + +.. seealso:: + + The see also block text + + +Tables +------ + +Images +------ + +Bulleted and enumerated lists +----------------------------- + +Definition lists +---------------- + +Inline markups +--------------