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 |
|
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 literal 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 Parser syntax 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 |
|
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 ',').
.. end
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.
Literal block using a remote file¶
| Directive | remote-code-block |
| Arguments | python (default), ruby, c, console,
ini, and others |
| Options | linenos, emphasize-lines |
| Description |
|
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
.. end
Output
############
# Metadata #
############
[composite:metadata]
use = egg:Paste#urlmap
/: meta
[pipeline:meta]
pipeline = cors ec2faultwrap logrequest metaapp
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.