mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
b4f71aa642
svn+ssh://pythondev@svn.python.org/doctools/branches/0.4.x ........ r65283 | georg.brandl | 2008-07-29 10:07:26 +0000 (Tue, 29 Jul 2008) | 2 lines Update ez_setup.py. ........ r65303 | benjamin.peterson | 2008-07-30 12:35:34 +0000 (Wed, 30 Jul 2008) | 1 line add a with_testapp decorator for test functions that passes the TestApp instance in a cleans up after it ........ r65316 | benjamin.peterson | 2008-07-30 23:12:07 +0000 (Wed, 30 Jul 2008) | 1 line make the app for test_markup global to the module ........ r65317 | benjamin.peterson | 2008-07-30 23:31:29 +0000 (Wed, 30 Jul 2008) | 1 line make TestApp.cleanup more aggressive ........ r65372 | georg.brandl | 2008-08-01 19:11:22 +0000 (Fri, 01 Aug 2008) | 2 lines Add more tests, fix a few bugs in image handling. ........ r65373 | georg.brandl | 2008-08-01 19:28:33 +0000 (Fri, 01 Aug 2008) | 2 lines Fix oversight. ........ r65374 | benjamin.peterson | 2008-08-01 19:36:32 +0000 (Fri, 01 Aug 2008) | 1 line fix one broken test ........ r65375 | georg.brandl | 2008-08-01 19:41:11 +0000 (Fri, 01 Aug 2008) | 2 lines Fix the handling of non-ASCII input in quickstart. ........ r65377 | georg.brandl | 2008-08-01 19:48:24 +0000 (Fri, 01 Aug 2008) | 2 lines Allow REs in markup checks. ........ r65380 | georg.brandl | 2008-08-01 20:31:18 +0000 (Fri, 01 Aug 2008) | 2 lines Don't rely on mtimes being different for changed files. ........ r65483 | georg.brandl | 2008-08-04 09:01:40 +0000 (Mon, 04 Aug 2008) | 4 lines Add an "encoding" option to literalinclude. Add tests for include directives. ........ r65484 | georg.brandl | 2008-08-04 09:11:17 +0000 (Mon, 04 Aug 2008) | 2 lines Add changelog entry. ........ r65485 | georg.brandl | 2008-08-04 09:21:58 +0000 (Mon, 04 Aug 2008) | 2 lines Fix markup. ........ r65494 | georg.brandl | 2008-08-04 16:34:59 +0000 (Mon, 04 Aug 2008) | 2 lines Correctly use HTML file suffix in templates. ........
117 lines
3.5 KiB
ReStructuredText
117 lines
3.5 KiB
ReStructuredText
.. highlight:: rest
|
|
|
|
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.
|
|
|
|
* 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)
|
|
* ``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 UTF-8. 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.
|