IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

doc: Extend "directives" doc, part 2

Browse Source 
Continue building up this combined doc by adding the contents of the
former 'code' document. There are no changes to the content.

Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane 2018-03-21 13:55:22 +00:00
parent 0641209da9
commit e01e9e34bb
3 changed files with 268 additions and 271 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

270
doc/markup/code.rst
View File

@ -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 <http://pygments.org>`_ 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
<http://pygments.org/docs/lexers/>`_.
* 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 ``<?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
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.

1
doc/markup/index.rst
View File

@ -7,7 +7,6 @@ facilities.
.. toctree:: .. toctree::
code
misc misc
More markup is added by :ref:`domains`. More markup is added by :ref:`domains`.

268
doc/usage/restructuredtext/directives.rst
View File

@ -387,6 +387,271 @@ units as well as normal text.
.. versionadded:: 0.6 .. 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 <http://pygments.org>`_ 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
<http://pygments.org/docs/lexers/>`_.
* 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 ``<?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
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-directive:
Glossary Glossary
@ -503,3 +768,6 @@ The following is an example taken from the Python Reference Manual::
constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
these all don't match slashes. A double star ``**`` can be used to these all don't match slashes. A double star ``**`` can be used to
match any sequence of characters *including* slashes. 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.