openstack-manuals/doc/contributor-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.

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

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

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

.. remote-code-block:: ini

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

Output

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

[pipeline:meta]
pipeline = cors ec2faultwrap logrequest metaapp