c10da1ec38
1. Adds the following subsections: * Introduction to RST * Tables * Images * Profiling * Lists * Inline markups * Decorations * Commenting 2. Restructures the toc 3. Creates separate files for each subsection included in the RST-related folder for simpler maintenance. Change-Id: I08568fb37755109552edf9692b8f259660550a69
91 lines
3.3 KiB
ReStructuredText
91 lines
3.3 KiB
ReStructuredText
============
|
|
Code samples
|
|
============
|
|
|
|
Format code snippets as standalone literal blocks. There are several ways
|
|
to define a code-block within an RST file.
|
|
|
|
Standard literal block
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
+------------------+---------------------------------------------------------+
|
|
| **Directive** | ``::`` or ``code`` |
|
|
+------------------+---------------------------------------------------------+
|
|
| **Arguments** | none |
|
|
+------------------+---------------------------------------------------------+
|
|
| **Options** | none |
|
|
+------------------+---------------------------------------------------------+
|
|
| **Description** | * Introduces a standard reST literal block. |
|
|
| | * Preserves line breaks and whitespaces. |
|
|
| | * Automatically highlights language (Python, by |
|
|
| | default) |
|
|
+------------------+---------------------------------------------------------+
|
|
|
|
Use ``::`` or ``code`` directive if you provide the code snippets written
|
|
in one programming language within one file. By default, the code-block
|
|
formatted this way is shown in a Python highlighting mode.
|
|
|
|
To define another highlighting language, use the ``code-block`` directive
|
|
as described in the :ref:`non-standard-block` section.
|
|
|
|
**Input**
|
|
|
|
.. code::
|
|
|
|
Add logging statements::
|
|
|
|
from nova.openstack.common import log as logging
|
|
LOG = logging.getLogger(__name__)
|
|
|
|
**Output**
|
|
|
|
Add logging statements::
|
|
|
|
from nova.openstack.common import log as logging
|
|
LOG = logging.getLogger(__name__)
|
|
|
|
|
|
.. _non-standard-block:
|
|
|
|
Non-standard literal block
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
+------------------+---------------------------------------------------------+
|
|
| **Directive** | ``code-block`` |
|
|
+------------------+---------------------------------------------------------+
|
|
| **Arguments** | ``python`` (default), ``ruby``, ``c``, ``console``, |
|
|
| | ``ini``, and others |
|
|
+------------------+---------------------------------------------------------+
|
|
| **Options** | ``linenos``, ``emphasize-lines`` |
|
|
+------------------+---------------------------------------------------------+
|
|
| **Description** | * Specifies the highlighting language directly. |
|
|
| | * Preserves line breaks and whitespaces. |
|
|
+------------------+---------------------------------------------------------+
|
|
|
|
To optimize the output of code for a specific programming language, specify
|
|
the corresponding argument with ``code-block``. Use ``ini`` for configuration
|
|
files, ``console`` for console inputs and outputs, and so on.
|
|
|
|
**Input**
|
|
|
|
.. code::
|
|
|
|
.. code-block:: ini
|
|
|
|
# Configuration for nova-rootwrap
|
|
# This file should be owned by (and only-writeable by) the root user
|
|
|
|
[DEFAULT]
|
|
# List of directories to load filter definitions from (separated by ',').
|
|
|
|
**Output**
|
|
|
|
.. code-block:: ini
|
|
|
|
# Configuration for nova-rootwrap
|
|
# This file should be owned by (and only-writeable by) the root user
|
|
|
|
[DEFAULT]
|
|
# List of directories to load filter definitions from (separated by ',').
|
|
|