diff options
Diffstat (limited to 'doc/markup/code.rst')
| -rw-r--r-- | doc/markup/code.rst | 106 |
1 files changed, 89 insertions, 17 deletions
diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 957774f0..9a503519 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -36,21 +36,29 @@ installed) and handled in a smart way: highlighted as Python). * The highlighting language can be changed using the ``highlight`` directive, - used as follows:: + used as follows: - .. highlight:: c + .. rst:directive:: .. highlight:: language - This language is used until the next ``highlight`` directive is encountered. + Example:: + + .. 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 :rst:dir:`code-block` directive that is given the highlighting language - directly:: + directly: + + .. rst:directive:: .. code-block:: language + + Use it like this:: - .. code-block:: ruby + .. code-block:: ruby - Some Ruby code. + Some Ruby code. - The directive's alias name :rst:dir:`sourcecode` works as well. + The directive's alias name :rst:dir:`sourcecode` works as well. * The valid values for the highlighting language are: @@ -79,14 +87,22 @@ option:: This will produce line numbers for all code blocks longer than five lines. -For :rst:dir:`code-block` blocks, a ``linenos`` flag option can be given to switch -on line numbers for the individual block:: +For :rst: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. +The first line number can be selected with the ``lineno-start`` option. If +present, ``linenos`` is automatically activated as well. + + .. code-block:: ruby + :lineno-start: 10 + + Some more Ruby code, with line numbering starting at 10. + Additionally, an ``emphasize-lines`` option can be given to have Pygments emphasize particular lines:: @@ -102,16 +118,19 @@ emphasize particular lines:: .. versionchanged:: 1.1 ``emphasize-lines`` has been added. +.. versionchanged:: 1.3 + ``lineno-start`` has been added. + Includes ^^^^^^^^ .. rst: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:: + 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 @@ -122,10 +141,11 @@ Includes Tabs in the input are expanded if you give a ``tab-width`` option with the desired tab width. - The directive also supports the ``linenos`` flag option to switch on line - numbers, the ``emphasize-lines`` option to emphasize particular lines, and - a ``language`` option to select a language different from the current - file's standard language. Example with options:: + Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag + option to switch on line numbers, the ``lineno-start`` option to select the + first line number, the ``emphasize-lines`` option to emphasize particular + lines, and a ``language`` option to select a language different from the + current file's standard language. Example with options:: .. literalinclude:: example.rb :language: ruby @@ -164,10 +184,24 @@ Includes string option, only lines that precede the first lines containing that string are included. + When specifying particular parts of a file to display, it can be useful to + display exactly which lines are being presented. + This can be done using the ``lineno-match`` option. + You can prepend and/or append a line to the included code, using the ``prepend`` and ``append`` option, respectively. This is useful e.g. for highlighting PHP code that doesn't include the ``<?php``/``?>`` markers. + + If you want to show the diff of the code, you can specify the old + file by giving a ``diff`` option:: + + .. literalinclude:: example.py + :diff: example.py.orig + + This shows the diff between example.py and example.py.orig with unified diff + format. + .. versionadded:: 0.4.3 The ``encoding`` option. .. versionadded:: 0.6 @@ -175,6 +209,44 @@ Includes as well as support for absolute filenames. .. versionadded:: 1.0 The ``prepend`` and ``append`` options, as well as ``tab-width``. + .. versionadded:: 1.3 + The ``diff`` option. + The ``lineno-match`` option. + + +Showing a file name +^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 1.3 + +A ``caption`` option can be given to show that name before the code block. For +example:: + + .. code-block:: python + :caption: this.py + + print 'Explicit is better than implicit.' + + +:rst:dir:`literalinclude` also supports the ``caption`` option, with the +additional feature that if you leave the value empty, the shown filename will be +exactly the one given as an argument. + + +Dedent +^^^^^^ + +.. versionadded:: 1.3 + +A ``dedent`` option can be given to strip a precedence characters from the code +block. For example:: + + .. literalinclude:: example.rb + :language: ruby + :dedent: 4 + :lines: 10-15 + +:rst:dir:`code-block` also supports the ``dedent`` option. .. rubric:: Footnotes |