openstack-manuals/doc/doc-contrib-guide/source/rst-conv/source-code.rst

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 non-standard-block section. Make sure to close these tags with end. Additionally, add the path tag to provide the parser with the path of the configuration files. This should allow the parser to parse the markup syntax to Bash.

Note

The end tag allows the parser to identify the scope of code blocks. The path tag allows the parser to identify the path of the config file. For more information, refer to the rst2bash section. These changes are mandatory only for the installation guides.

Input

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

.. path /path/to/config/file
.. 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

# 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 ',').

Note

When you write the command example, you should write the input and output as it is from the console in one code block, not add an extra blank line, not split them into input block and output block. You can omit the output where appropriate.

Options of code-block directive

You can add line numbers to code examples with the :linenos: parameter and highlight some specific lines with the :emphasize-lines: parameter:

Input

.. code-block:: python
   :linenos:
   :emphasize-lines: 3,5-6

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'
       print 'This one is highlighted too.'

Output

def some_function():
    interesting = False
    print 'This line is highlighted.'
    print 'This one is not...'
    print '...but this one is.'
    print 'This one is highlighted too.'

Literal block using a remote file

Directive	remote-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.

This directive behaves exactly like the code-block directive, but gets the content from a remote URL (http or https).

remote-code-block is a custom directive.

Input

.. path /path/to/config/file
.. remote-code-block:: ini

   https://git.openstack.org/cgit/openstack/nova/tree/etc/nova/api-paste.ini?h=stable/ocata

Output

############
# Metadata #
############
[composite:metadata]
use = egg:Paste#urlmap
/: meta

[pipeline:meta]
pipeline = cors ec2faultwrap logrequest metaapp