From ecd193cde8de3c663638c9458cc1d53041ebc4c5 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Wed, 21 Mar 2018 13:57:00 +0000 Subject: [PATCH] doc: Extend "directives" doc, part 3 Finish building up this combined doc by adding the contents of the former 'misc' document. There are no changes to the content. Signed-off-by: Stephen Finucane --- doc/contents.rst | 1 - doc/markup/index.rst | 14 - doc/markup/misc.rst | 310 ---------------------- doc/usage/restructuredtext/directives.rst | 306 +++++++++++++++++++++ 4 files changed, 306 insertions(+), 325 deletions(-) delete mode 100644 doc/markup/index.rst delete mode 100644 doc/markup/misc.rst diff --git a/doc/contents.rst b/doc/contents.rst index 1abd1d26b..7a74e8b2e 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -13,7 +13,6 @@ Sphinx documentation contents intro man/index - markup/index domains builders config diff --git a/doc/markup/index.rst b/doc/markup/index.rst deleted file mode 100644 index 70f361d04..000000000 --- a/doc/markup/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -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. - -.. toctree:: - - misc - -More markup is added by :ref:`domains`. - -.. _standard reST markup: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst deleted file mode 100644 index 5705edf8d..000000000 --- a/doc/markup/misc.rst +++ /dev/null @@ -1,310 +0,0 @@ -.. highlight:: rst - -Miscellaneous markup -==================== - -Meta-information markup ------------------------ - -.. rst:directive:: .. sectionauthor:: name - - Identifies the author of the current section. The argument should include - the author's name such that it can be used for presentation and email - address. The domain name portion of the address should be lower case. - Example:: - - .. sectionauthor:: Guido van Rossum - - By default, this markup isn't reflected in the output in any way (it helps - keep track of contributions), but you can set the configuration value - :confval:`show_authors` to ``True`` to make them produce a paragraph in the - output. - - -.. rst:directive:: .. codeauthor:: name - - The :rst:dir:`codeauthor` directive, which can appear multiple times, names - the authors of the described code, just like :rst:dir:`sectionauthor` names - the author(s) of a piece of documentation. It too only produces output if - the :confval:`show_authors` configuration value is ``True``. - - -Index-generating markup ------------------------ - -Sphinx automatically creates index entries from all object descriptions (like -functions, classes or attributes) like discussed in :ref:`domains`. - -However, there is also explicit markup available, to make the index more -comprehensive and enable index entries in documents where information is not -mainly contained in information units, such as the language reference. - -.. rst:directive:: .. index:: - - This directive contains one or more index entries. Each entry consists of a - type and a value, separated by a colon. - - For example:: - - .. index:: - single: execution; context - module: __main__ - module: sys - triple: module; search; path - - The execution context - --------------------- - - ... - - This directive contains five entries, which will be converted to entries in - the generated index which link to the exact location of the index statement - (or, in case of offline media, the corresponding page number). - - Since index directives generate cross-reference targets at their location in - the source, it makes sense to put them *before* the thing they refer to -- - e.g. a heading, as in the example above. - - The possible entry types are: - - single - Creates a single index entry. Can be made a subentry by separating the - subentry text with a semicolon (this notation is also used below to - describe what entries are created). - pair - ``pair: loop; statement`` is a shortcut that creates two index entries, - namely ``loop; statement`` and ``statement; loop``. - triple - Likewise, ``triple: module; search; path`` is a shortcut that creates - three index entries, which are ``module; search path``, ``search; path, - module`` and ``path; module search``. - see - ``see: entry; other`` creates an index entry that refers from ``entry`` to - ``other``. - seealso - Like ``see``, but inserts "see also" instead of "see". - module, keyword, operator, object, exception, statement, builtin - These all create two index entries. For example, ``module: hashlib`` - creates the entries ``module; hashlib`` and ``hashlib; module``. (These - are Python-specific and therefore deprecated.) - - You can mark up "main" index entries by prefixing them with an exclamation - mark. The references to "main" entries are emphasized in the generated - index. For example, if two pages contain :: - - .. index:: Python - - and one page contains :: - - .. index:: ! Python - - then the backlink to the latter page is emphasized among the three backlinks. - - For index directives containing only "single" entries, there is a shorthand - notation:: - - .. index:: BNF, grammar, syntax, notation - - This creates four index entries. - - .. versionchanged:: 1.1 - Added ``see`` and ``seealso`` types, as well as marking main entries. - -.. rst:role:: index - - While the :rst:dir:`index` directive is a block-level markup and links to the - beginning of the next paragraph, there is also a corresponding role that sets - the link target directly where it is used. - - The content of the role can be a simple phrase, which is then kept in the - text and used as an index entry. It can also be a combination of text and - index entry, styled like with explicit targets of cross-references. In that - case, the "target" part can be a full entry as described for the directive - above. For example:: - - This is a normal reST :index:`paragraph` that contains several - :index:`index entries `. - - .. versionadded:: 1.1 - - -.. _tags: - -Including content based on tags -------------------------------- - -.. rst:directive:: .. only:: - - Include the content of the directive only if the *expression* is true. The - expression should consist of tags, like this:: - - .. only:: html and draft - - Undefined tags are false, defined tags (via the ``-t`` command-line option or - within :file:`conf.py`, see :ref:`here `) are true. Boolean - expressions, also using parentheses (like ``html and (latex or draft)``) are - supported. - - The *format* and the *name* of the current builder (``html``, ``latex`` or - ``text``) are always set as a tag [#]_. To make the distinction between - format and name explicit, they are also added with the prefix ``format_`` and - ``builder_``, e.g. the epub builder defines the tags ``html``, ``epub``, - ``format_html`` and ``builder_epub``. - - These standard tags are set *after* the configuration file is read, so they - are not available there. - - All tags must follow the standard Python identifier syntax as set out in - the `Identifiers and keywords - `_ - documentation. That is, a tag expression may only consist of tags that - conform to the syntax of Python variables. In ASCII, this consists of the - uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_`` - and, except for the first character, the digits ``0`` through ``9``. - - .. versionadded:: 0.6 - .. versionchanged:: 1.2 - Added the name of the builder and the prefixes. - - .. warning:: - - This directive is designed to control only content of document. It could - not control sections, labels and so on. - -.. _table-directives: - -Tables ------- - -Use :ref:`reStructuredText tables `, i.e. either - -- grid table syntax (:duref:`ref `), -- simple table syntax (:duref:`ref `), -- :dudir:`csv-table` syntax, -- or :dudir:`list-table` syntax. - -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: - -.. rst:directive:: .. tabularcolumns:: column spec - - This directive gives a "column spec" for the next table occurring in the - source file. The spec is the second argument to the LaTeX ``tabulary`` - package's environment (which Sphinx uses to translate tables). It can have - values like :: - - |l|l|l| - - which means three left-adjusted, nonbreaking columns. For columns with - longer text that should automatically be broken, use either the standard - ``p{width}`` construct, or tabulary's automatic specifiers: - - +-----+------------------------------------------+ - |``L``| flush left column with automatic width | - +-----+------------------------------------------+ - |``R``| flush right column with automatic width | - +-----+------------------------------------------+ - |``C``| centered column with automatic width | - +-----+------------------------------------------+ - |``J``| justified column with automatic width | - +-----+------------------------------------------+ - - The automatic widths of the ``LRCJ`` columns are attributed by ``tabulary`` - in proportion to the observed shares in a first pass where the table cells - are rendered at their natural "horizontal" widths. - - By default, Sphinx uses a table layout with ``J`` for every column. - - .. versionadded:: 0.3 - - .. versionchanged:: 1.6 - Merged cells may now contain multiple paragraphs and are much better - handled, thanks to custom Sphinx LaTeX macros. This novel situation - motivated the switch to ``J`` specifier and not ``L`` by default. - - .. hint:: - - Sphinx actually uses ``T`` specifier having done ``\newcolumntype{T}{J}``. - To revert to previous default, insert ``\newcolumntype{T}{L}`` in the - LaTeX preamble (see :confval:`latex_elements`). - - A frequent issue with tabulary is that columns with little contents are - "squeezed". The minimal column width is a tabulary parameter called - ``\tymin``. You may set it globally in the LaTeX preamble via - ``\setlength{\tymin}{40pt}`` for example. - - Else, use the :rst:dir:`tabularcolumns` directive with an explicit - ``p{40pt}`` (for example) for that column. You may use also ``l`` - specifier but this makes the task of setting column widths more difficult - if some merged cell intersects that column. - - .. warning:: - - Tables with more than 30 rows are rendered using ``longtable``, not - ``tabulary``, in order to allow pagebreaks. The ``L``, ``R``, ... specifiers - do not work for these tables. - - Tables that contain list-like elements such as object descriptions, - blockquotes or any kind of lists cannot be set out of the box with - ``tabulary``. They are therefore set with the standard LaTeX ``tabular`` (or - ``longtable``) environment if you don't give a ``tabularcolumns`` directive. - If you do, the table will be set with ``tabulary`` but you must use the - ``p{width}`` construct (or Sphinx's ``\X`` and ``\Y`` specifiers described - below) for the columns containing these elements. - - Literal blocks do not work with ``tabulary`` at all, so tables containing - a literal block are always set with ``tabular``. The verbatim environment - used for literal blocks only works in ``p{width}`` (and ``\X`` or ``\Y``) - columns, hence Sphinx generates such column specs for tables containing - literal blocks. - - Since Sphinx 1.5, the ``\X{a}{b}`` specifier is used (there *is* a backslash - in the specifier letter). It is like ``p{width}`` with the width set to a - fraction ``a/b`` of the current line width. You can use it in the - :rst:dir:`tabularcolumns` (it is not a problem if some LaTeX macro is also - called ``\X``.) - - It is *not* needed for ``b`` to be the total number of columns, nor for the - sum of the fractions of the ``\X`` specifiers to add up to one. For example - ``|\X{2}{5}|\X{1}{5}|\X{1}{5}|`` is legitimate and the table will occupy - 80% of the line width, the first of its three columns having the same width - as the sum of the next two. - - This is used by the ``:widths:`` option of the :dudir:`table` directive. - - Since Sphinx 1.6, there is also the ``\Y{f}`` specifier which admits a - decimal argument, such has ``\Y{0.15}``: this would have the same effect as - ``\X{3}{20}``. - - .. versionchanged:: 1.6 - - Merged cells from complex grid tables (either multi-row, multi-column, or - both) now allow blockquotes, lists, literal blocks, ... as do regular cells. - - Sphinx's merged cells interact well with ``p{width}``, ``\X{a}{b}``, ``Y{f}`` - and tabulary's columns. - - .. note:: - - :rst:dir:`tabularcolumns` conflicts with ``:widths:`` option of table - directives. If both are specified, ``:widths:`` option will be ignored. - -Math ----- - -.. todo:: Move this in here. - -See :ref:`math-support`. - -.. rubric:: Footnotes - -.. [#] For most builders name and format are the same. At the moment only - builders derived from the html builder distinguish between the builder - format and the builder name. - - Note that the current builder tag is not available in ``conf.py``, it is - only available after the builder is initialized. diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index b2e79fa91..ed35113c3 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -716,6 +716,305 @@ Glossary Index key for glossary term should be considered *experimental*. +Meta-information markup +----------------------- + +.. rst:directive:: .. sectionauthor:: name + + Identifies the author of the current section. The argument should include + the author's name such that it can be used for presentation and email + address. The domain name portion of the address should be lower case. + Example:: + + .. sectionauthor:: Guido van Rossum + + By default, this markup isn't reflected in the output in any way (it helps + keep track of contributions), but you can set the configuration value + :confval:`show_authors` to ``True`` to make them produce a paragraph in the + output. + + +.. rst:directive:: .. codeauthor:: name + + The :rst:dir:`codeauthor` directive, which can appear multiple times, names + the authors of the described code, just like :rst:dir:`sectionauthor` names + the author(s) of a piece of documentation. It too only produces output if + the :confval:`show_authors` configuration value is ``True``. + + +Index-generating markup +----------------------- + +Sphinx automatically creates index entries from all object descriptions (like +functions, classes or attributes) like discussed in :ref:`domains`. + +However, there is also explicit markup available, to make the index more +comprehensive and enable index entries in documents where information is not +mainly contained in information units, such as the language reference. + +.. rst:directive:: .. index:: + + This directive contains one or more index entries. Each entry consists of a + type and a value, separated by a colon. + + For example:: + + .. index:: + single: execution; context + module: __main__ + module: sys + triple: module; search; path + + The execution context + --------------------- + + ... + + This directive contains five entries, which will be converted to entries in + the generated index which link to the exact location of the index statement + (or, in case of offline media, the corresponding page number). + + Since index directives generate cross-reference targets at their location in + the source, it makes sense to put them *before* the thing they refer to -- + e.g. a heading, as in the example above. + + The possible entry types are: + + single + Creates a single index entry. Can be made a subentry by separating the + subentry text with a semicolon (this notation is also used below to + describe what entries are created). + pair + ``pair: loop; statement`` is a shortcut that creates two index entries, + namely ``loop; statement`` and ``statement; loop``. + triple + Likewise, ``triple: module; search; path`` is a shortcut that creates + three index entries, which are ``module; search path``, ``search; path, + module`` and ``path; module search``. + see + ``see: entry; other`` creates an index entry that refers from ``entry`` to + ``other``. + seealso + Like ``see``, but inserts "see also" instead of "see". + module, keyword, operator, object, exception, statement, builtin + These all create two index entries. For example, ``module: hashlib`` + creates the entries ``module; hashlib`` and ``hashlib; module``. (These + are Python-specific and therefore deprecated.) + + You can mark up "main" index entries by prefixing them with an exclamation + mark. The references to "main" entries are emphasized in the generated + index. For example, if two pages contain :: + + .. index:: Python + + and one page contains :: + + .. index:: ! Python + + then the backlink to the latter page is emphasized among the three backlinks. + + For index directives containing only "single" entries, there is a shorthand + notation:: + + .. index:: BNF, grammar, syntax, notation + + This creates four index entries. + + .. versionchanged:: 1.1 + Added ``see`` and ``seealso`` types, as well as marking main entries. + +.. rst:role:: index + + While the :rst:dir:`index` directive is a block-level markup and links to the + beginning of the next paragraph, there is also a corresponding role that sets + the link target directly where it is used. + + The content of the role can be a simple phrase, which is then kept in the + text and used as an index entry. It can also be a combination of text and + index entry, styled like with explicit targets of cross-references. In that + case, the "target" part can be a full entry as described for the directive + above. For example:: + + This is a normal reST :index:`paragraph` that contains several + :index:`index entries `. + + .. versionadded:: 1.1 + + +.. _tags: + +Including content based on tags +------------------------------- + +.. rst:directive:: .. only:: + + Include the content of the directive only if the *expression* is true. The + expression should consist of tags, like this:: + + .. only:: html and draft + + Undefined tags are false, defined tags (via the ``-t`` command-line option or + within :file:`conf.py`, see :ref:`here `) are true. Boolean + expressions, also using parentheses (like ``html and (latex or draft)``) are + supported. + + The *format* and the *name* of the current builder (``html``, ``latex`` or + ``text``) are always set as a tag [#]_. To make the distinction between + format and name explicit, they are also added with the prefix ``format_`` and + ``builder_``, e.g. the epub builder defines the tags ``html``, ``epub``, + ``format_html`` and ``builder_epub``. + + These standard tags are set *after* the configuration file is read, so they + are not available there. + + All tags must follow the standard Python identifier syntax as set out in + the `Identifiers and keywords + `_ + documentation. That is, a tag expression may only consist of tags that + conform to the syntax of Python variables. In ASCII, this consists of the + uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_`` + and, except for the first character, the digits ``0`` through ``9``. + + .. versionadded:: 0.6 + .. versionchanged:: 1.2 + Added the name of the builder and the prefixes. + + .. warning:: + + This directive is designed to control only content of document. It could + not control sections, labels and so on. + +.. _table-directives: + +Tables +------ + +Use :ref:`reStructuredText tables `, i.e. either + +- grid table syntax (:duref:`ref `), +- simple table syntax (:duref:`ref `), +- :dudir:`csv-table` syntax, +- or :dudir:`list-table` syntax. + +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: + +.. rst:directive:: .. tabularcolumns:: column spec + + This directive gives a "column spec" for the next table occurring in the + source file. The spec is the second argument to the LaTeX ``tabulary`` + package's environment (which Sphinx uses to translate tables). It can have + values like :: + + |l|l|l| + + which means three left-adjusted, nonbreaking columns. For columns with + longer text that should automatically be broken, use either the standard + ``p{width}`` construct, or tabulary's automatic specifiers: + + +-----+------------------------------------------+ + |``L``| flush left column with automatic width | + +-----+------------------------------------------+ + |``R``| flush right column with automatic width | + +-----+------------------------------------------+ + |``C``| centered column with automatic width | + +-----+------------------------------------------+ + |``J``| justified column with automatic width | + +-----+------------------------------------------+ + + The automatic widths of the ``LRCJ`` columns are attributed by ``tabulary`` + in proportion to the observed shares in a first pass where the table cells + are rendered at their natural "horizontal" widths. + + By default, Sphinx uses a table layout with ``J`` for every column. + + .. versionadded:: 0.3 + + .. versionchanged:: 1.6 + Merged cells may now contain multiple paragraphs and are much better + handled, thanks to custom Sphinx LaTeX macros. This novel situation + motivated the switch to ``J`` specifier and not ``L`` by default. + + .. hint:: + + Sphinx actually uses ``T`` specifier having done ``\newcolumntype{T}{J}``. + To revert to previous default, insert ``\newcolumntype{T}{L}`` in the + LaTeX preamble (see :confval:`latex_elements`). + + A frequent issue with tabulary is that columns with little contents are + "squeezed". The minimal column width is a tabulary parameter called + ``\tymin``. You may set it globally in the LaTeX preamble via + ``\setlength{\tymin}{40pt}`` for example. + + Else, use the :rst:dir:`tabularcolumns` directive with an explicit + ``p{40pt}`` (for example) for that column. You may use also ``l`` + specifier but this makes the task of setting column widths more difficult + if some merged cell intersects that column. + + .. warning:: + + Tables with more than 30 rows are rendered using ``longtable``, not + ``tabulary``, in order to allow pagebreaks. The ``L``, ``R``, ... specifiers + do not work for these tables. + + Tables that contain list-like elements such as object descriptions, + blockquotes or any kind of lists cannot be set out of the box with + ``tabulary``. They are therefore set with the standard LaTeX ``tabular`` (or + ``longtable``) environment if you don't give a ``tabularcolumns`` directive. + If you do, the table will be set with ``tabulary`` but you must use the + ``p{width}`` construct (or Sphinx's ``\X`` and ``\Y`` specifiers described + below) for the columns containing these elements. + + Literal blocks do not work with ``tabulary`` at all, so tables containing + a literal block are always set with ``tabular``. The verbatim environment + used for literal blocks only works in ``p{width}`` (and ``\X`` or ``\Y``) + columns, hence Sphinx generates such column specs for tables containing + literal blocks. + + Since Sphinx 1.5, the ``\X{a}{b}`` specifier is used (there *is* a backslash + in the specifier letter). It is like ``p{width}`` with the width set to a + fraction ``a/b`` of the current line width. You can use it in the + :rst:dir:`tabularcolumns` (it is not a problem if some LaTeX macro is also + called ``\X``.) + + It is *not* needed for ``b`` to be the total number of columns, nor for the + sum of the fractions of the ``\X`` specifiers to add up to one. For example + ``|\X{2}{5}|\X{1}{5}|\X{1}{5}|`` is legitimate and the table will occupy + 80% of the line width, the first of its three columns having the same width + as the sum of the next two. + + This is used by the ``:widths:`` option of the :dudir:`table` directive. + + Since Sphinx 1.6, there is also the ``\Y{f}`` specifier which admits a + decimal argument, such has ``\Y{0.15}``: this would have the same effect as + ``\X{3}{20}``. + + .. versionchanged:: 1.6 + + Merged cells from complex grid tables (either multi-row, multi-column, or + both) now allow blockquotes, lists, literal blocks, ... as do regular cells. + + Sphinx's merged cells interact well with ``p{width}``, ``\X{a}{b}``, ``Y{f}`` + and tabulary's columns. + + .. note:: + + :rst:dir:`tabularcolumns` conflicts with ``:widths:`` option of table + directives. If both are specified, ``:widths:`` option will be ignored. + + +Math +---- + +.. todo:: Move this in here. + +See :ref:`math-support`. + + Grammar production displays --------------------------- @@ -771,3 +1070,10 @@ The following is an example taken from the Python Reference Manual:: .. [#] There is a standard ``.. include`` directive, but it raises errors if the file is not found. This one only emits a warning. + +.. [#] For most builders name and format are the same. At the moment only + builders derived from the html builder distinguish between the builder + format and the builder name. + + Note that the current builder tag is not available in ``conf.py``, it is + only available after the builder is initialized.