diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/usage/restructuredtext/basics.rst | 72 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/directives.rst | 395 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/field-lists.rst | 6 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/index.rst | 5 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/roles.rst | 2 |
5 files changed, 335 insertions, 145 deletions
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 7aab544..5354748 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -9,24 +9,26 @@ reStructuredText Primer reStructuredText is the default plaintext markup language used by Sphinx. This section is a brief introduction to reStructuredText (reST) concepts and syntax, intended to provide authors with enough information to author documents -productively. Since reST was designed to be a simple, unobtrusive markup +productively. Since reStructuredText was designed to be a simple, unobtrusive markup language, this will not take too long. .. seealso:: The authoritative `reStructuredText User Documentation - <https://docutils.sourceforge.io/rst.html>`_. The "ref" links in this - document link to the description of the individual constructs in the reST - reference. + <https://docutils.sourceforge.io/rst.html>`_. + The "ref" links in this document link to the description of + the individual constructs in the reStructuredText reference. Paragraphs ---------- -The paragraph (:duref:`ref <paragraphs>`) is the most basic block in a reST -document. Paragraphs are simply chunks of text separated by one or more blank -lines. As in Python, indentation is significant in reST, so all lines of the -same paragraph must be left-aligned to the same level of indentation. +The paragraph (:duref:`ref <paragraphs>`) is the most basic block +in a reStructuredText document. +Paragraphs are simply chunks of text separated by one or more blank lines. +As in Python, indentation is significant in reStructuredText, +so all lines of the same paragraph must be left-aligned +to the same level of indentation. .. _rst-inline-markup: @@ -34,7 +36,7 @@ same paragraph must be left-aligned to the same level of indentation. Inline markup ------------- -The standard reST inline markup is quite simple: use +The standard reStructuredText inline markup is quite simple: use * one asterisk: ``*text*`` for emphasis (italics), * two asterisks: ``**text**`` for strong emphasis (boldface), and @@ -53,7 +55,7 @@ Be aware of some restrictions of this markup: These restrictions may be lifted in future versions of the docutils. It is also possible to replace or expand upon some of this inline markup with -roles. Refer to :ref:`rst-roles-alt` for more information. +roles. Refer to :ref:`rst-roles` for more information. Lists and Quote-like blocks @@ -220,8 +222,8 @@ You can also separate the link and the target definition (:duref:`ref Internal links ~~~~~~~~~~~~~~ -Internal linking is done via a special reST role provided by Sphinx, see the -section on specific markup, :ref:`ref-role`. +Internal linking is done via a special reStructuredText role provided by Sphinx, +see the section on specific markup, :ref:`ref-role`. .. _rst-sections: @@ -250,7 +252,7 @@ follow: * ``^`` for subsubsections * ``"`` for paragraphs -Of course, you are free to use your own marker characters (see the reST +Of course, you are free to use your own marker characters (see the reStructuredText documentation), and use a deeper nesting level, but keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth. @@ -281,10 +283,7 @@ at the beginning of documents. Refer to :doc:`field-lists` for more information. -.. TODO This ref should be 'rst-roles', but that already exists. Rename the -.. other ones - -.. _rst-roles-alt: +.. _rst-roles: Roles ----- @@ -311,8 +310,8 @@ Refer to :doc:`roles` for roles added by Sphinx. Explicit Markup --------------- -"Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in reST for -most constructs that need special handling, such as footnotes, +"Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in +reStructuredText for most constructs that need special handling, such as footnotes, specially-highlighted paragraphs, comments, and generic directives. An explicit markup block begins with a line starting with ``..`` followed by @@ -328,8 +327,8 @@ Directives ---------- A directive (:duref:`ref <directives>`) is a generic block of explicit markup. -Along with roles, it is one of the extension mechanisms of reST, and Sphinx -makes heavy use of it. +Along with roles, it is one of the extension mechanisms of reStructuredText, +and Sphinx makes heavy use of it. Docutils supports the following directives: @@ -380,6 +379,12 @@ Docutils supports the following directives: When the default domain contains a ``class`` directive, this directive will be shadowed. Therefore, Sphinx re-exports it as ``rst-class``. + .. tip:: + + If you want to add a class to a directive, + you may consider the ``:class:`` :dudir:`option <common-options>` instead, + which is supported by most directives and allows for a more compact notation. + * HTML specifics: - :dudir:`meta` @@ -444,7 +449,7 @@ it does not start with a space. Images ------ -reST supports an image directive (:dudir:`ref <image>`), used like so:: +reStructuredText supports an image directive (:dudir:`ref <image>`), used like so:: .. image:: gnu.png (options) @@ -510,9 +515,9 @@ footnotes without names (``[#]_``). Citations --------- -Standard reST citations (:duref:`ref <citations>`) are supported, with the -additional feature that they are "global", i.e. all citations can be referenced -from all files. Use them like so:: +Standard reStructuredText citations (:duref:`ref <citations>`) are supported, +with the additional feature that they are "global", +i.e. all citations can be referenced from all files. Use them like so:: Lorem ipsum [Ref]_ dolor sit amet. @@ -525,9 +530,9 @@ numeric or begins with ``#``. Substitutions ------------- -reST supports "substitutions" (:duref:`ref <substitution-definitions>`), which -are pieces of text and/or markup referred to in the text by ``|name|``. They -are defined like footnotes with explicit markup blocks, like this:: +reStructuredText supports "substitutions" (:duref:`ref <substitution-definitions>`), +which are pieces of text and/or markup referred to in the text by ``|name|``. +They are defined like footnotes with explicit markup blocks, like this:: .. |name| replace:: replacement *text* @@ -536,8 +541,8 @@ or this:: .. |caution| image:: warning.png :alt: Warning! -See the :duref:`reST reference for substitutions <substitution-definitions>` -for details. +See the :duref:`reStructuredText reference for substitutions +<substitution-definitions>` for details. .. index:: ! pair: global; substitutions @@ -584,7 +589,7 @@ directive:: will generate the following HTML output: -.. code:: html +.. code-block:: html <meta name="description" content="The Sphinx documentation builder"> <meta name="keywords" content="Sphinx, documentation, builder"> @@ -612,7 +617,7 @@ Source encoding --------------- Since the easiest way to include special characters like em dashes or copyright -signs in reST is to directly write them as Unicode characters, one has to +signs in reStructuredText is to directly write them as Unicode characters, one has to specify an encoding. Sphinx assumes source files to be encoded in UTF-8 by default; you can change this with the :confval:`source_encoding` config value. @@ -620,7 +625,8 @@ default; you can change this with the :confval:`source_encoding` config value. Gotchas ------- -There are some problems one commonly runs into while authoring reST documents: +There are some problems one commonly runs into +while authoring reStructuredText documents: * **Separation of inline markup:** As said above, inline markup spans must be separated from the surrounding text by non-word characters, you have to use a diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index ff42524..19079d2 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -24,10 +24,11 @@ Table of contents .. index:: pair: table of; contents -Since reST does not have facilities to interconnect several documents, or split -documents into multiple output files, Sphinx uses a custom directive to add -relations between the single files the documentation is made of, as well as -tables of contents. The ``toctree`` directive is the central element. +Since reStructuredText does not have facilities to interconnect several documents, +or split documents into multiple output files, +Sphinx uses a custom directive to add relations between +the single files the documentation is made of, as well as tables of contents. +The ``toctree`` directive is the central element. .. note:: @@ -37,7 +38,7 @@ tables of contents. The ``toctree`` directive is the central element. .. note:: To create table of contents for current document (.rst file), use the - standard reST :dudir:`contents directive <table-of-contents>`. + standard reStructuredText :dudir:`contents directive <table-of-contents>`. .. rst:directive:: toctree @@ -49,8 +50,8 @@ tables of contents. The ``toctree`` directive is the central element. indicate the depth of the tree; by default, all levels are included. [#]_ The representation of "TOC tree" is changed in each output format. The - builders that output multiple files (ex. HTML) treat it as a collection of - hyperlinks. On the other hand, the builders that output a single file (ex. + builders that output multiple files (e.g. HTML) treat it as a collection of + hyperlinks. On the other hand, the builders that output a single file (e.g. LaTeX, man page, etc.) replace it with the content of the documents on the TOC tree. @@ -79,7 +80,7 @@ tables of contents. The ``toctree`` directive is the central element. Document titles in the :rst:dir:`toctree` will be automatically read from the title of the referenced document. If that isn't what you want, you can - specify an explicit title and target using a similar syntax to reST + specify an explicit title and target using a similar syntax to reStructuredText hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This looks like:: @@ -124,6 +125,14 @@ tables of contents. The ``toctree`` directive is the central element. foo + As with :dudir:`most directives <common-options>`, + you can use the ``class`` option to assign `class attributes`_:: + + .. toctree:: + :class: custom-toc + + .. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes + If you want only the titles of documents in the tree to show up, not other headings of the same level, you can use the ``titlesonly`` option:: @@ -223,150 +232,327 @@ tables of contents. The ``toctree`` directive is the central element. Special names ^^^^^^^^^^^^^ +.. index:: pair: genindex; toctree + pair: modindex; toctree + pair: search; toctree + Sphinx reserves some document names for its own use; you should not try to create documents with these names -- it will cause problems. The special document names (and pages generated for them) are: -* ``genindex``, ``modindex``, ``search`` +* ``genindex`` - These are used for the general index, the Python module index, and the search - page, respectively. + This is used for the general index, + which is populated with entries from :rst:dir:`index` directives + and all index-generating :ref:`object descriptions <basic-domain-markup>`. + For example, see Sphinx's :ref:`genindex`. - The general index is populated with entries from modules, all - index-generating :ref:`object descriptions <basic-domain-markup>`, and from - :rst:dir:`index` directives. +* ``modindex`` - The Python module index contains one entry per :rst:dir:`py:module` - directive. + This is used for the Python module index, + which contains one entry per :rst:dir:`py:module` directive. + For example, see Sphinx's :ref:`py-modindex`. - 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 - should work on every major browser that supports modern JavaScript. +* ``search`` -* every name beginning with ``_`` + This is used for the search page, + which contains a form that uses the generated JSON search index and JavaScript + to full-text search the generated documents for search words; + it works on every major browser. + For example, see Sphinx's :ref:`search`. - Though 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.) +* Every name beginning with ``_`` -.. warning:: + Though 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.) - Be careful with unusual characters in filenames. Some formats may interpret - these characters in unexpected ways: +.. warning:: - * Do not use the colon ``:`` for HTML based formats. Links to other parts - may not work. + Be careful with unusual characters in filenames. + Some formats may interpret these characters in unexpected ways: - * Do not use the plus ``+`` for the ePub format. Some resources may not be - found. + * Do not use the colon ``:`` for HTML based formats. + Links to other parts may not work. + * Do not use the plus ``+`` for the ePub format. + Some resources may not be found. Paragraph-level markup ---------------------- -.. index:: note, warning - pair: changes; in version - These directives create short paragraphs and can be used inside information units as well as normal text. + +Admonitions, messages, and warnings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: admonition, admonitions + pair: attention; admonition + pair: caution; admonition + pair: danger; admonition + pair: error; admonition + pair: hint; admonition + pair: important; admonition + pair: note; admonition + pair: tip; admonition + pair: warning; admonition + +The admonition directives create 'admonition' elements, +a standardised system of communicating different types of information, +from a helpful :rst:dir:`tip` to matters of paramount :rst:dir:`danger`. +These directives can be used anywhere an ordinary body element can, +and can contain arbitrary body elements. +There are nine specific named admonitions +and the generic :rst:dir:`admonition` directive. + +.. rst:directive:: .. attention:: + + Information that requires the reader's attention. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. attention:: + + Please may I have your attention. + +.. rst:directive:: .. caution:: + + Information with regard to which the reader should exercise care. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. caution:: + + Exercise due caution. + +.. rst:directive:: .. danger:: + + Information which may lead to near and present danger if not heeded. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. danger:: + + Let none think to fly the danger for soon or late love is his own avenger. + +.. rst:directive:: .. error:: + + Information relating to failure modes of some description. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. error:: + + ERROR 418: I'm a teapot. + +.. rst:directive:: .. hint:: + + Information that is helpful to the reader. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. hint:: + + Look under the flowerpot. + +.. rst:directive:: .. important:: + + Information that is of paramount importance + and which the reader must not ignore. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. important:: + + This is a statement of paramount importance. + .. rst:directive:: .. note:: - An especially important bit of information about an API that a user should be - aware of when using whatever bit of API the note pertains to. The content of - the directive should be written in complete sentences and include all - appropriate punctuation. + An especially important bit of information that the reader should know. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. - Example:: + Example: + + .. note:: + + This function is not suitable for sending tins of spam. + +.. rst:directive:: .. tip:: - .. note:: + Some useful tidbit of information for the reader. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. - This function is not suitable for sending spam e-mails. + Example: + + .. tip:: + + Remember your sun cream! .. rst:directive:: .. warning:: - An important bit of information about an API that a user should be very aware - of when using whatever bit of API the warning pertains to. The content of - the directive should be written in complete sentences and include all - appropriate punctuation. This differs from :rst:dir:`note` in that it is - recommended over :rst:dir:`note` for information regarding security. + An important bit of information that the reader should be very aware of. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: -.. rst:directive:: .. versionadded:: version + .. warning:: + + Beware of the dog. + +.. rst:directive:: .. admonition:: title + + A generic admonition, with an optional title. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. admonition:: This is a title + + This is the content of the admonition. + + +.. rst:directive:: seealso + + Many sections include a list of references to module documentation or + external documents. + These lists are created using the :rst:dir:`seealso` directive. + + The :rst:dir:`!seealso` directive is typically placed in a section + just before any subsections. + The content of the :rst:dir:`seealso` directive should be + either a single line or a reStructuredText `definition list`_. - This directive documents the version of the project which added the described - feature to the library or C API. When this applies to an entire module, it - should be placed at the top of the module section before any prose. + .. _definition list: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists + + Example:: + + .. seealso:: + + Python's :py:mod:`zipfile` module + Documentation of Python's standard :py:mod:`zipfile` module. + + `GNU tar manual, Basic Tar Format <https://example.org>`_ + Documentation for tar archive files, including GNU tar extensions. + + .. seealso:: + + Module :py:mod:`zipfile` + Documentation of the :py:mod:`zipfile` standard module. + + `GNU tar manual, Basic Tar Format <https://example.org>`_ + Documentation for tar archive files, including GNU tar extensions. + + +Describing changes between versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: pair: added; in version + pair: changes; in version + pair: removed; in version + +.. rst:directive:: .. versionadded:: version [brief explanation] + + This directive documents the version of the project + which added the described feature. + When this applies to an entire module or component, + it should be placed at the top of the relevant section before any prose. The first argument must be given and is the version in question; you can add a second argument consisting of a *brief* explanation of the change. + .. attention:: + There must be no blank line between the directive head and the explanation; + this is to make these blocks visually continuous in the markup. + Example:: .. versionadded:: 2.5 The *spam* parameter. - Note that there must be no blank line between the directive head and the - explanation; this is to make these blocks visually continuous in the markup. + .. versionadded:: 2.5 + The *spam* parameter. -.. rst:directive:: .. versionchanged:: version +.. rst:directive:: .. versionchanged:: version [brief explanation] Similar to :rst:dir:`versionadded`, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.). -.. rst:directive:: .. deprecated:: version + Example:: - Similar to :rst:dir:`versionchanged`, but describes when the feature was - deprecated. An explanation can also be given, for example to inform the - reader what should be used instead. Example:: + .. versionchanged:: 2.8 + The *spam* parameter is now of type *boson*. - .. deprecated:: 3.1 - Use :func:`spam` instead. + .. versionchanged:: 2.8 + The *spam* parameter is now of type *boson*. -.. rst:directive:: .. versionremoved:: version +.. rst:directive:: .. deprecated:: version [brief explanation] + + Similar to :rst:dir:`versionadded`, but describes when the feature was + deprecated. + A *brief* explanation can also be given, + for example to tell the reader what to use instead. - Similar to :rst:dir:`versionadded`, but describes when the feature was removed. - An explanation may be provided to inform the reader what to use instead, - or why the feature was removed. Example:: - .. versionremoved:: 4.0 - The :func:`spam` function is more flexible, and should be used instead. + .. deprecated:: 3.1 + Use :py:func:`spam` instead. - .. versionadded:: 7.3 + .. deprecated:: 3.1 + Use :py:func:`!spam` instead. -.. rst:directive:: seealso +.. rst:directive:: .. versionremoved:: version [brief explanation] - Many sections include a list of references to module documentation or - external documents. These lists are created using the :rst:dir:`seealso` - directive. + Similar to :rst:dir:`versionadded`, but describes when the feature was removed. + An explanation may be provided to tell the reader what to use instead, + or why the feature was removed. - The :rst:dir:`seealso` directive is typically placed in a section just before - any subsections. For the HTML output, it is shown boxed off from the main - flow of the text. + .. versionadded:: 7.3 - The content of the :rst:dir:`seealso` directive should be a reST definition - list. Example:: + Example:: - .. seealso:: + .. versionremoved:: 4.0 + The :py:func:`spam` function is more flexible, and should be used instead. - Module :py:mod:`zipfile` - Documentation of the :py:mod:`zipfile` standard module. + .. versionremoved:: 4.0 + The :py:func:`!spam` function is more flexible, and should be used instead. - `GNU tar manual, Basic Tar Format <https://link>`_ - Documentation for tar archive files, including GNU tar extensions. - There's also a "short form" allowed that looks like this:: +Presentational +^^^^^^^^^^^^^^ + +.. rst:directive:: .. rubric:: title - .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile` + A rubric is like an informal heading that doesn't correspond to the document's structure, + i.e. it does not create a table of contents node. - .. versionadded:: 0.5 - The short form. + .. rst:directive:option:: heading-level: n + :type: number from 1 to 6 -.. rst:directive:: .. rubric:: title + .. versionadded:: 7.4.1 - This directive creates a paragraph heading that is not used to create a - table of contents node. + Use this option to specify the heading level of the rubric. + In this case the rubric will be rendered as ``<h1>`` to ``<h6>`` for HTML output, + or as the corresponding non-numbered sectioning command for LaTeX + (see :confval:`latex_toplevel_sectioning`). .. note:: @@ -377,10 +563,7 @@ units as well as normal text. .. rst:directive:: centered - This directive creates a centered boldfaced line of text. Use it as - follows:: - - .. centered:: LICENSE AGREEMENT + This directive creates a centered boldfaced line of text. .. deprecated:: 1.1 This presentation-only directive is a legacy from older versions. @@ -419,8 +602,8 @@ Showing code examples There are multiple ways to show syntax-highlighted literal code blocks in Sphinx: -* using :ref:`reST doctest blocks <rst-doctest-blocks>`; -* using :ref:`reST literal blocks <rst-literal-blocks>`, optionally in +* using :ref:`reStructuredText doctest blocks <rst-doctest-blocks>`; +* using :ref:`reStructuredText literal blocks <rst-literal-blocks>`, optionally in combination with the :rst:dir:`highlight` directive; * using the :rst:dir:`code-block` directive; * and using the :rst:dir:`literalinclude` directive. @@ -503,6 +686,7 @@ __ https://pygments.org/docs/lexers .. rst:directive:: .. code-block:: [language] .. sourcecode:: [language] + .. code:: [language] Example:: @@ -802,8 +986,8 @@ Glossary .. rst:directive:: .. glossary:: - This directive must contain a reST definition-list-like markup with terms and - definitions. The definitions will then be referenceable with the + This directive must contain a reStructuredText definition-list-like markup + with terms and definitions. The definitions will then be referenceable with the :rst:role:`term` role. Example:: .. glossary:: @@ -934,7 +1118,7 @@ mainly contained in information units, such as the language reference. (this notation is also used below to describe what entries are created). Examples: - .. code:: reStructuredText + .. code-block:: rst .. index:: single: execution single: execution; context @@ -947,7 +1131,7 @@ mainly contained in information units, such as the language reference. The pair of values must be separated by a semicolon. Example: - .. code:: reStructuredText + .. code-block:: rst .. index:: pair: loop; statement @@ -957,7 +1141,7 @@ mainly contained in information units, such as the language reference. All three values must be separated by a semicolon. Example: - .. code:: reStructuredText + .. code-block:: rst .. index:: triple: module; search; path @@ -967,7 +1151,7 @@ mainly contained in information units, such as the language reference. A shortcut to create an index entry that refers to another entry. Example: - .. code:: reStructuredText + .. code-block:: rst .. index:: see: entry; other @@ -1034,7 +1218,7 @@ mainly contained in information units, such as the language reference. 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 + This is a normal reStructuredText :index:`paragraph` that contains several :index:`index entries <pair: index; entry>`. .. versionadded:: 1.1 @@ -1052,10 +1236,11 @@ Including content based on tags .. only:: html and draft - Undefined tags are false, defined tags (via the ``-t`` command-line option or - within :file:`conf.py`, see :ref:`here <conf-tags>`) are true. Boolean - expressions, also using parentheses (like ``(latex or html) and draft``) are - supported. + Undefined tags are false, defined tags are true + (tags can be defined via the :option:`--tag <sphinx-build --tag>` + command-line option or within :file:`conf.py`, see :ref:`here <conf-tags>`). + Boolean expressions (like ``(latex or html) and draft``) are supported + and may use parentheses. The *format* and the *name* of the current builder (``html``, ``latex`` or ``text``) are always set as a tag [#]_. To make the distinction between @@ -1287,8 +1472,8 @@ the definition of the symbol. There is this directive: an explicit title can be given (e.g., "``myTitle <myGroup:sum>``"), or the target can be prefixed with a tilde (e.g., "``~myGroup:sum``"). - Note that no further reST parsing is done in the production, so that you - don't have to escape ``*`` or ``|`` characters. + Note that no further reStructuredText parsing is done in the production, + so that you don't have to escape ``*`` or ``|`` characters. The following is an example taken from the Python Reference Manual:: diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst index 62dad5c..d352633 100644 --- a/doc/usage/restructuredtext/field-lists.rst +++ b/doc/usage/restructuredtext/field-lists.rst @@ -48,9 +48,9 @@ At the moment, these metadata fields are recognized: .. note:: - This metadata effects to the depth of local toctree. But it does not - effect to the depth of *global* toctree. So this would not be change - the sidebar of some themes which uses global one. + This metadata affects the depth of the local toctree. But it does not + affect the depth of the *global* toctree. So this does not change + the sidebar of themes that use the global toctree. .. versionadded:: 0.4 diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst index 0fe311e..ada40c5 100644 --- a/doc/usage/restructuredtext/index.rst +++ b/doc/usage/restructuredtext/index.rst @@ -8,9 +8,8 @@ reStructuredText (reST) is the default plaintext markup language used by both Docutils and Sphinx. Docutils provides the basic reStructuredText syntax, while Sphinx extends this to support additional functionality. -The below guides go through the most important aspects of reST. For the -authoritative reStructuredText reference, refer to the `docutils -documentation`__. +The below guides go through the most important aspects of reStructuredText. +For the authoritative reference, refer to the `docutils documentation`__. __ https://docutils.sourceforge.io/rst.html diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst index b21a2b7..ea5d99c 100644 --- a/doc/usage/restructuredtext/roles.rst +++ b/doc/usage/restructuredtext/roles.rst @@ -268,7 +268,7 @@ The following roles generate external links: For example: :rfc:`2324` Note that there are no special roles for including hyperlinks as you can use -the standard reST markup for that purpose. +the standard reStructuredText markup for that purpose. .. _default-substitutions: |