mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
doc: Rework "markup" documents
These are going to form the basis of a future 'directive' document, so we do some cleanup before this happens. There are a number of cleanup items. - Some paragraphs are reworded or clarified - Semantic markup is added where possible - Everything is wrapped to ~80 characters Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
parent
08ff8160b8
commit
0167c009c2
@ -1,4 +1,4 @@
|
||||
.. highlight:: rest
|
||||
.. highlight:: rst
|
||||
|
||||
.. _code-examples:
|
||||
|
||||
@ -8,14 +8,16 @@ 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::
|
||||
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
|
||||
@ -24,10 +26,10 @@ an "unused" primary prompt; this is an example of what *not* to do::
|
||||
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.
|
||||
* 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
|
||||
@ -44,7 +46,8 @@ in a smart way:
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
This language is used until the next ``highlight`` directive is encountered.
|
||||
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
|
||||
@ -78,9 +81,9 @@ 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::
|
||||
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
|
||||
@ -131,13 +134,13 @@ Includes
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
@ -168,8 +171,8 @@ Includes
|
||||
.. 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.
|
||||
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::
|
||||
@ -181,16 +184,17 @@ Includes
|
||||
|
||||
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.
|
||||
``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``.
|
||||
``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
|
||||
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
|
||||
@ -202,15 +206,14 @@ Includes
|
||||
``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::
|
||||
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.
|
||||
This shows the diff between ``example.py`` and ``example.py.orig`` with
|
||||
unified diff format.
|
||||
|
||||
.. versionadded:: 0.4.3
|
||||
The ``encoding`` option.
|
||||
@ -242,11 +245,9 @@ For example::
|
||||
|
||||
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.
|
||||
|
||||
``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
|
||||
^^^^^^
|
||||
@ -263,8 +264,7 @@ block. For example::
|
||||
|
||||
:rst:dir:`code-block` also supports the ``dedent`` option.
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [1] There is a standard ``.. include`` directive, but it raises errors if the
|
||||
.. [#] There is a standard ``.. include`` directive, but it raises errors if the
|
||||
file is not found. This one only emits a warning.
|
||||
|
||||
@ -3,8 +3,9 @@
|
||||
Sphinx Markup Constructs
|
||||
========================
|
||||
|
||||
Sphinx adds a lot of new directives and interpreted text roles to `standard reST
|
||||
markup`_. This section contains the reference material for these facilities.
|
||||
Sphinx adds a lot of new directives and interpreted text roles to `standard
|
||||
reST markup`_. This section contains the reference material for these
|
||||
facilities.
|
||||
|
||||
.. toctree::
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. highlight:: rest
|
||||
.. highlight:: rst
|
||||
|
||||
Miscellaneous markup
|
||||
====================
|
||||
@ -186,10 +186,9 @@ Use :ref:`reStructuredText tables <rst-tables>`, i.e. either
|
||||
The :dudir:`table` directive serves as optional wrapper of the *grid* and
|
||||
*simple* syntaxes.
|
||||
|
||||
They work fine in
|
||||
HTML output, however there are some gotchas when using tables in LaTeX: the
|
||||
column width is hard to determine correctly automatically. For this reason, the
|
||||
following directive exists:
|
||||
They work fine in HTML output, however there are some gotchas when using tables
|
||||
in LaTeX: the column width is hard to determine correctly automatically. For
|
||||
this reason, the following directive exists:
|
||||
|
||||
.. rst:directive:: .. tabularcolumns:: column spec
|
||||
|
||||
@ -297,6 +296,8 @@ following directive exists:
|
||||
Math
|
||||
----
|
||||
|
||||
.. todo:: Move this in here.
|
||||
|
||||
See :ref:`math-support`.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
@ -307,4 +308,3 @@ See :ref:`math-support`.
|
||||
|
||||
Note that the current builder tag is not available in ``conf.py``, it is
|
||||
only available after the builder is initialized.
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. highlight:: rest
|
||||
.. highlight:: rst
|
||||
|
||||
Paragraph-level markup
|
||||
----------------------
|
||||
@ -7,7 +7,7 @@ Paragraph-level markup
|
||||
pair: changes; in version
|
||||
|
||||
These directives create short paragraphs and can be used inside information
|
||||
units as well as normal text:
|
||||
units as well as normal text.
|
||||
|
||||
.. rst:directive:: .. note::
|
||||
|
||||
@ -61,9 +61,6 @@ units as well as normal text:
|
||||
.. deprecated:: 3.1
|
||||
Use :func:`spam` instead.
|
||||
|
||||
|
||||
--------------
|
||||
|
||||
.. rst:directive:: seealso
|
||||
|
||||
Many sections include a list of references to module documentation or
|
||||
@ -104,7 +101,6 @@ units as well as normal text:
|
||||
assumed to only contain footnote definitions and therefore would create an
|
||||
empty heading.
|
||||
|
||||
|
||||
.. rst:directive:: centered
|
||||
|
||||
This directive creates a centered boldfaced line of text. Use it as
|
||||
@ -116,7 +112,6 @@ units as well as normal text:
|
||||
This presentation-only directive is a legacy from older versions. Use a
|
||||
:rst:dir:`rst-class` directive instead and add an appropriate style.
|
||||
|
||||
|
||||
.. rst:directive:: hlist
|
||||
|
||||
This directive must contain a bullet list. It will transform it into a more
|
||||
@ -138,16 +133,6 @@ units as well as normal text:
|
||||
.. versionadded:: 0.6
|
||||
|
||||
|
||||
Table-of-contents markup
|
||||
------------------------
|
||||
|
||||
The :rst:dir:`toctree` directive, which generates tables of contents of
|
||||
subdocuments, is described in :ref:`toctree-directive`.
|
||||
|
||||
For local tables of contents, use the standard reST :dudir:`contents directive
|
||||
<table-of-contents>`.
|
||||
|
||||
|
||||
.. _glossary-directive:
|
||||
|
||||
Glossary
|
||||
@ -222,11 +207,11 @@ the definition of the symbol. There is this directive:
|
||||
|
||||
.. rst:directive:: .. productionlist:: [name]
|
||||
|
||||
This directive is used to enclose a group of productions. Each production is
|
||||
given on a single line and consists of a name, separated by a colon from the
|
||||
following definition. If the definition spans multiple lines, each
|
||||
continuation line must begin with a colon placed at the same column as in the
|
||||
first line.
|
||||
This directive is used to enclose a group of productions. Each production
|
||||
is given on a single line and consists of a name, separated by a colon from
|
||||
the following definition. If the definition spans multiple lines, each
|
||||
continuation line must begin with a colon placed at the same column as in
|
||||
the first line.
|
||||
|
||||
The argument to :rst:dir:`productionlist` serves to distinguish different
|
||||
sets of production lists that belong to different grammars.
|
||||
@ -234,9 +219,10 @@ the definition of the symbol. There is this directive:
|
||||
Blank lines are not allowed within ``productionlist`` directive arguments.
|
||||
|
||||
The definition can contain token names which are marked as interpreted text
|
||||
(e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
|
||||
to the productions of these tokens. Outside of the production list, you can
|
||||
reference to token productions using :rst:role:`token`.
|
||||
(e.g. ``sum ::= `integer` "+" `integer```) -- this generates
|
||||
cross-references to the productions of these tokens. Outside of the
|
||||
production list, you can reference to token productions using
|
||||
:rst:role:`token`.
|
||||
|
||||
Note that no further reST parsing is done in the production, so that you
|
||||
don't have to escape ``*`` or ``|`` characters.
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
.. highlight:: rst
|
||||
.. _toctree-directive:
|
||||
|
||||
The TOC tree
|
||||
============
|
||||
Table of contents
|
||||
-----------------
|
||||
|
||||
.. index:: pair: table of; contents
|
||||
|
||||
@ -16,6 +16,11 @@ tables of contents. The ``toctree`` directive is the central element.
|
||||
Simple "inclusion" of one file in another can be done with the
|
||||
:dudir:`include` directive.
|
||||
|
||||
.. note::
|
||||
|
||||
For local tables of contents, use the standard reST :dudir:`contents
|
||||
directive <table-of-contents>`.
|
||||
|
||||
.. rst:directive:: toctree
|
||||
|
||||
This directive inserts a "TOC tree" at the current location, using the
|
||||
@ -192,7 +197,7 @@ tables of contents. The ``toctree`` directive is the central element.
|
||||
Added "caption" and "name" option.
|
||||
|
||||
Special names
|
||||
-------------
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Sphinx reserves some document names for its own use; you should not try to
|
||||
create documents with these names -- it will cause problems.
|
||||
@ -204,11 +209,12 @@ The special document names (and pages generated for them) are:
|
||||
These are used for the general index, the Python module index, and the search
|
||||
page, respectively.
|
||||
|
||||
The general index is populated with entries from modules, all index-generating
|
||||
:ref:`object descriptions <basic-domain-markup>`, and from :rst:dir:`index`
|
||||
directives.
|
||||
The general index is populated with entries from modules, all
|
||||
index-generating :ref:`object descriptions <basic-domain-markup>`, and from
|
||||
:rst:dir:`index` directives.
|
||||
|
||||
The Python module index contains one entry per :rst:dir:`py:module` directive.
|
||||
The Python module index contains one entry per :rst:dir:`py:module`
|
||||
directive.
|
||||
|
||||
The search page contains a form that uses the generated JSON search index and
|
||||
JavaScript to full-text search the generated documents for search words; it
|
||||
@ -216,9 +222,9 @@ The special document names (and pages generated for them) are:
|
||||
|
||||
* every name beginning with ``_``
|
||||
|
||||
Though only few such names are currently used by Sphinx, you should not create
|
||||
documents or document-containing directories with such names. (Using ``_`` as
|
||||
a prefix for a custom template directory is fine.)
|
||||
Though only few such names are currently used by Sphinx, you should not
|
||||
create documents or document-containing directories with such names. (Using
|
||||
``_`` as a prefix for a custom template directory is fine.)
|
||||
|
||||
.. warning::
|
||||
|
||||
@ -238,5 +244,5 @@ The special document names (and pages generated for them) are:
|
||||
|
||||
.. [#] A note on available globbing syntax: you can use the standard shell
|
||||
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.
|
||||
these all don't match slashes. A double star ``**`` can be used to
|
||||
match any sequence of characters *including* slashes.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user