mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
124 lines
3.8 KiB
ReStructuredText
124 lines
3.8 KiB
ReStructuredText
.. highlight:: rest
|
|
|
|
.. _code-examples:
|
|
|
|
Showing code examples
|
|
---------------------
|
|
|
|
.. index:: pair: code; examples
|
|
single: sourcecode
|
|
|
|
Examples of Python source code or interactive sessions are represented using
|
|
standard reST literal blocks. They are started by a ``::`` at the end of the
|
|
preceding paragraph and delimited by indentation.
|
|
|
|
Representing an interactive session requires including the prompts and output
|
|
along with the Python code. No special markup is required for interactive
|
|
sessions. After the last line of input or output presented, there should not be
|
|
an "unused" primary prompt; this is an example of what *not* to do::
|
|
|
|
>>> 1 + 1
|
|
2
|
|
>>>
|
|
|
|
Syntax highlighting is done with `Pygments <http://pygments.org>`_ (if it's
|
|
installed) and handled in a smart way:
|
|
|
|
* There is a "highlighting language" for each source file. Per default, this is
|
|
``'python'`` as the majority of files will have to highlight Python snippets,
|
|
but the doc-wide default can be set with the :confval:`highlight_language`
|
|
config value.
|
|
|
|
* Within Python highlighting mode, interactive sessions are recognized
|
|
automatically and highlighted appropriately.
|
|
|
|
* The highlighting language can be changed using the ``highlight`` directive,
|
|
used as follows::
|
|
|
|
.. highlight:: c
|
|
|
|
This language is used until the next ``highlight`` directive is encountered.
|
|
|
|
* For documents that have to show snippets in different languages, there's also
|
|
a :dir:`code-block` directive that is given the highlighting language
|
|
directly::
|
|
|
|
.. code-block:: ruby
|
|
|
|
Some Ruby code.
|
|
|
|
The directive's alias name :dir:`sourcecode` works as well.
|
|
|
|
* The valid values for the highlighting language are:
|
|
|
|
* ``none`` (no highlighting)
|
|
* ``python`` (the default when :confval:`highlight_language` isn't set)
|
|
* ``guess`` (let Pygments guess the lexer based on contents, only works with
|
|
certain well-recognizable languages)
|
|
* ``rest``
|
|
* ``c``
|
|
* ... and any other lexer name that Pygments supports.
|
|
|
|
* If highlighting with the selected language fails, the block is not highlighted
|
|
in any way.
|
|
|
|
Line numbers
|
|
^^^^^^^^^^^^
|
|
|
|
If installed, Pygments can generate line numbers for code blocks. For
|
|
automatically-highlighted blocks (those started by ``::``), line numbers must be
|
|
switched on in a :dir:`highlight` directive, with the ``linenothreshold``
|
|
option::
|
|
|
|
.. highlight:: python
|
|
:linenothreshold: 5
|
|
|
|
This will produce line numbers for all code blocks longer than five lines.
|
|
|
|
For :dir:`code-block` blocks, a ``linenos`` flag option can be given to switch
|
|
on line numbers for the individual block::
|
|
|
|
.. code-block:: ruby
|
|
:linenos:
|
|
|
|
Some more Ruby code.
|
|
|
|
|
|
Includes
|
|
^^^^^^^^
|
|
|
|
.. directive:: .. literalinclude:: filename
|
|
|
|
Longer displays of verbatim text may be included by storing the example text in
|
|
an external file containing only plain text. The file may be included using the
|
|
``literalinclude`` directive. [1]_ For example, to include the Python source file
|
|
:file:`example.py`, use::
|
|
|
|
.. literalinclude:: example.py
|
|
|
|
The file name is relative to the current file's path.
|
|
|
|
The directive also supports the ``linenos`` flag option to switch on line
|
|
numbers, and a ``language`` option to select a language different from the
|
|
current file's standard language. Example with options::
|
|
|
|
.. literalinclude:: example.rb
|
|
:language: ruby
|
|
:linenos:
|
|
|
|
Include files are assumed to be encoded in the :confval:`source_encoding`.
|
|
If the file has a different encoding, you can specify it with the
|
|
``encoding`` option::
|
|
|
|
.. literalinclude:: example.py
|
|
:encoding: latin-1
|
|
|
|
.. versionadded:: 0.4.3
|
|
The ``encoding`` option.
|
|
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [1] There is a standard ``.. include`` directive, but it raises errors if the
|
|
file is not found. This one only emits a warning.
|