diff --git a/doc/markup/code.rst b/doc/markup/code.rst deleted file mode 100644 index 3152630f4..000000000 --- a/doc/markup/code.rst +++ /dev/null @@ -1,270 +0,0 @@ -.. highlight:: rst - -.. _code-examples: - -Showing code examples ---------------------- - -.. index:: pair: code; examples - single: sourcecode - -.. todo:: Rework this to remove the bullet points - -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 `_ 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. Normal Python code is only - highlighted if it is parseable (so you can use Python as the default, but - interspersed snippets of shell commands or other code blocks will not be - highlighted as Python). - -* The highlighting language can be changed using the ``highlight`` directive, - used as follows: - - .. rst:directive:: .. highlight:: language - - 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: - - .. rst:directive:: .. code-block:: language - - Use it like this:: - - .. code-block:: ruby - - Some Ruby code. - - The directive's alias name :rst: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 alias that Pygments supports - `_. - -* If highlighting with the selected language fails (i.e. Pygments emits an - "Error" token), the block is not highlighted in any way. - -Line numbers -^^^^^^^^^^^^ - -Pygments can generate line numbers for code blocks. For -automatically-highlighted blocks (those started by ``::``), line numbers must -be switched on in a :rst: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 :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`` flag is automatically activated:: - - .. 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:: - - .. code-block:: python - :emphasize-lines: 3,5 - - def some_function(): - interesting = False - print 'This line is highlighted.' - print 'This one is not...' - print '...but this one is.' - -.. versionchanged:: 1.1 - ``emphasize-lines`` has been added. - -.. versionchanged:: 1.3 - ``lineno-start`` has been added. - -.. versionchanged:: 1.6.6 - LaTeX supports the ``emphasize-lines`` option. - -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. [#]_ For example, to include the - Python source file :file:`example.py`, use:: - - .. literalinclude:: example.py - - The file name is usually relative to the current file's path. However, if - it is absolute (starting with ``/``), it is relative to the top source - directory. - - Tabs in the input are expanded if you give a ``tab-width`` option with the - desired tab width. - - 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 - :emphasize-lines: 12,15-18 - :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 - - The directive also supports including only parts of the file. If it is a - Python module, you can select a class, function or method to include using - the ``pyobject`` option:: - - .. literalinclude:: example.py - :pyobject: Timer.start - - This would only include the code lines belonging to the ``start()`` method - in the ``Timer`` class within the file. - - Alternately, you can specify exactly which lines to include by giving a - ``lines`` option:: - - .. literalinclude:: example.py - :lines: 1,3,5-10,20- - - This includes the lines 1, 3, 5 to 10 and lines 20 to the last line. - - Another way to control which part of the file is included is to use the - ``start-after`` and ``end-before`` options (or only one of them). If - ``start-after`` is given as a string option, only lines that follow the - first line containing that string are included. If ``end-before`` is given - as a string option, only lines that precede the first lines containing that - string are included. - - With lines selected using ``start-after`` it is still possible to use - ``lines``, the first allowed line having by convention the line number - ``1``. - - When lines have been selected in any of the ways described above, the line - numbers in ``emphasize-lines`` refer to those selected lines, counted - consecutively starting at ``1``. - - When specifying particular parts of a file to display, it can be useful to - display the original line numbers. This can be done using the - ``lineno-match`` option, which is however allowed only when the selection - consists of contiguous lines. - - 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 ```` 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 - The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options, - 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. - .. versionchanged:: 1.6 - With both ``start-after`` and ``lines`` in use, the first line as per - ``start-after`` is considered to be with line number ``1`` for ``lines``. - -Caption and name -^^^^^^^^^^^^^^^^ - -.. versionadded:: 1.3 - -A ``caption`` option can be given to show that name before the code block. -A ``name`` option can be provided implicit target name that can be referenced -by using :rst:role:`ref`. -For example:: - - .. code-block:: python - :caption: this.py - :name: this-py - - print 'Explicit is better than implicit.' - -:rst:dir:`literalinclude` also supports the ``caption`` and ``name`` option. -``caption`` has an 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 indentation 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 - -.. [#] There is a standard ``.. include`` directive, but it raises errors if the - file is not found. This one only emits a warning. diff --git a/doc/markup/index.rst b/doc/markup/index.rst index 6591db00d..70f361d04 100644 --- a/doc/markup/index.rst +++ b/doc/markup/index.rst @@ -7,7 +7,6 @@ facilities. .. toctree:: - code misc More markup is added by :ref:`domains`. diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 53f242abc..b2e79fa91 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -387,6 +387,271 @@ units as well as normal text. .. versionadded:: 0.6 +.. _code-examples: + +Showing code examples +--------------------- + +.. index:: pair: code; examples + single: sourcecode + +.. todo:: Rework this to remove the bullet points + +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 `_ 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. Normal Python code is only + highlighted if it is parseable (so you can use Python as the default, but + interspersed snippets of shell commands or other code blocks will not be + highlighted as Python). + +* The highlighting language can be changed using the ``highlight`` directive, + used as follows: + + .. rst:directive:: .. highlight:: language + + 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: + + .. rst:directive:: .. code-block:: language + + Use it like this:: + + .. code-block:: ruby + + Some Ruby code. + + The directive's alias name :rst: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 alias that Pygments supports + `_. + +* If highlighting with the selected language fails (i.e. Pygments emits an + "Error" token), the block is not highlighted in any way. + +Line numbers +^^^^^^^^^^^^ + +Pygments can generate line numbers for code blocks. For +automatically-highlighted blocks (those started by ``::``), line numbers must +be switched on in a :rst: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 :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`` flag is automatically activated:: + + .. 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:: + + .. code-block:: python + :emphasize-lines: 3,5 + + def some_function(): + interesting = False + print 'This line is highlighted.' + print 'This one is not...' + print '...but this one is.' + +.. versionchanged:: 1.1 + ``emphasize-lines`` has been added. + +.. versionchanged:: 1.3 + ``lineno-start`` has been added. + +.. versionchanged:: 1.6.6 + LaTeX supports the ``emphasize-lines`` option. + +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. [#]_ For example, to include the + Python source file :file:`example.py`, use:: + + .. literalinclude:: example.py + + The file name is usually relative to the current file's path. However, if + it is absolute (starting with ``/``), it is relative to the top source + directory. + + Tabs in the input are expanded if you give a ``tab-width`` option with the + desired tab width. + + 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 + :emphasize-lines: 12,15-18 + :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 + + The directive also supports including only parts of the file. If it is a + Python module, you can select a class, function or method to include using + the ``pyobject`` option:: + + .. literalinclude:: example.py + :pyobject: Timer.start + + This would only include the code lines belonging to the ``start()`` method + in the ``Timer`` class within the file. + + Alternately, you can specify exactly which lines to include by giving a + ``lines`` option:: + + .. literalinclude:: example.py + :lines: 1,3,5-10,20- + + This includes the lines 1, 3, 5 to 10 and lines 20 to the last line. + + Another way to control which part of the file is included is to use the + ``start-after`` and ``end-before`` options (or only one of them). If + ``start-after`` is given as a string option, only lines that follow the + first line containing that string are included. If ``end-before`` is given + as a string option, only lines that precede the first lines containing that + string are included. + + With lines selected using ``start-after`` it is still possible to use + ``lines``, the first allowed line having by convention the line number + ``1``. + + When lines have been selected in any of the ways described above, the line + numbers in ``emphasize-lines`` refer to those selected lines, counted + consecutively starting at ``1``. + + When specifying particular parts of a file to display, it can be useful to + display the original line numbers. This can be done using the + ``lineno-match`` option, which is however allowed only when the selection + consists of contiguous lines. + + 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 ```` 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 + The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options, + 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. + .. versionchanged:: 1.6 + With both ``start-after`` and ``lines`` in use, the first line as per + ``start-after`` is considered to be with line number ``1`` for ``lines``. + +Caption and name +^^^^^^^^^^^^^^^^ + +.. versionadded:: 1.3 + +A ``caption`` option can be given to show that name before the code block. +A ``name`` option can be provided implicit target name that can be referenced +by using :rst:role:`ref`. +For example:: + + .. code-block:: python + :caption: this.py + :name: this-py + + print 'Explicit is better than implicit.' + +:rst:dir:`literalinclude` also supports the ``caption`` and ``name`` option. +``caption`` has an 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 indentation 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. + + .. _glossary-directive: Glossary @@ -503,3 +768,6 @@ The following is an example taken from the Python Reference Manual:: constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that these all don't match slashes. A double star ``**`` can be used to match any sequence of characters *including* slashes. + +.. [#] There is a standard ``.. include`` directive, but it raises errors if the + file is not found. This one only emits a warning.