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

Standardise on "reStructuredText" over "reST" in documentation

Browse Source
This commit is contained in:
Adam Turner
2024-07-14 06:00:08 +01:00
parent 26576590ed
commit f2640a4286
18 changed files with 111 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/development/html_themes/templating.rst
View File

@@ -289,8 +289,8 @@ in the future.
.. data:: has_source
True if the reST document sources are copied (if :confval:`html_copy_source`
is ``True``).
True if the reStructuredText document sources are copied
(if :confval:`html_copy_source` is ``True``).
.. data:: language
@@ -326,8 +326,8 @@ in the future.
.. data:: pagename
The "page name" of the current file, i.e. either the document name if the
file is generated from a reST source, or the equivalent hierarchical name
relative to the output directory
file is generated from a reStructuredText source,
or the equivalent hierarchical name relative to the output directory
(``[directory/]filename_without_extension``).
.. data:: project

2
doc/development/tutorials/extending_syntax.rst
View File

@@ -138,7 +138,7 @@ The simplest thing you can do is to call the
:meth:`.Sphinx.add_role` and :meth:`.Sphinx.add_directive` methods,
which is what we've done here.
For this particular call, the first argument is the name of the role/directive itself
as used in a reST file.
as used in a reStructuredText file.
In this case, we would use ``hello``. For example:
.. code-block:: rst

8
doc/extdev/event_callbacks.rst
View File

@@ -369,15 +369,15 @@ These events are emitted by specific builders.
The *pagename* argument is the canonical name of the page being rendered,
that is, without ``.html`` suffix and using slashes as path separators.
The *templatename* is the name of the template to render, this will be
``'page.html'`` for all pages from reST documents.
``'page.html'`` for all pages from reStructuredText documents.
The *context* argument is a dictionary of values that are given to the
template engine to render the page and can be modified to include custom
values.
The *doctree* argument will be a doctree when the page is created from a reST
documents; it will be ``None`` when the page is created from an HTML template
alone.
The *doctree* argument will be a doctree when
the page is created from a reStructuredText documents;
it will be ``None`` when the page is created from an HTML template alone.
You can return a string from the handler, it will then replace
``'page.html'`` as the HTML template for this page.

8
doc/faq.rst
View File

@@ -33,7 +33,7 @@ How do I...
See the :ref:`extension-tutorials-index`.
... convert from my existing docs using MoinMoin markup?
The easiest way is to convert to xhtml, then convert `xhtml to reST`_.
The easiest way is to convert to xhtml, then convert `xhtml to reStructuredText`_.
You'll still need to mark up classes and such, but the headings and code
examples come through cleanly.
@@ -58,8 +58,8 @@ Epydoc
Epydoc's API docs for a given identifier.
Doxygen
Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe
<https://github.com/michaeljones/breathe/tree/master>`_.
Michael Jones has developed a reStructuredText/Sphinx bridge to doxygen
called `breathe <https://github.com/breathe-doc/breathe/tree/master>`_.
SCons
Glenn Hutchings has written a SCons build script to build Sphinx
@@ -147,7 +147,7 @@ Google Search
.. _Getting Started: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
.. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
.. _xhtml to reST: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py
.. _xhtml to reStructuredText: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py
Sphinx vs. Docutils

7
doc/glossary.rst
View File

@@ -36,9 +36,10 @@ Glossary
See :ref:`rst-directives` for more information.
document name
Since reST source files can have different extensions (some people like
``.txt``, some like ``.rst`` -- the extension can be configured with
:confval:`source_suffix`) and different OSes have different path
Since reStructuredText source files can have different extensions
(some people like ``.txt``, some like ``.rst`` -- the extension can be
configured with :confval:`source_suffix`)
and different OSes have different path
separators, Sphinx abstracts them: :dfn:`document names` are always
relative to the :term:`source directory`, the extension is stripped, and
path separators are converted to slashes. All values, parameters and such

2
doc/tutorial/automatic-doc-generation.rst
View File

@@ -142,7 +142,7 @@ contain two new pages:
- ``api.html``, corresponding to ``docs/source/api.rst`` and containing a table
with the objects you included in the ``autosummary`` directive (in this case,
only one).
- ``generated/lumache.html``, corresponding to a newly created reST file
- ``generated/lumache.html``, corresponding to a newly created reStructuredText file
``generated/lumache.rst`` and containing a summary of members of the module,
in this case one function and one exception.

4
doc/usage/advanced/intl.rst
View File

@@ -160,8 +160,8 @@ section describe an easy way to translate with *sphinx-intl*.
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
Please be careful not to break reST notation. Most po-editors will help you
with that.
Please be careful not to break reStructuredText notation.
Most po-editors will help you with that.
#. Build translated document.

16
doc/usage/builders/index.rst
View File

@@ -71,9 +71,9 @@ The most common builders are:
.. class:: StandaloneHTMLBuilder
This is the standard HTML builder. Its output is a directory with HTML
files, complete with style sheets and optionally the reST sources. There are
quite a few configuration values that customize the output of this builder,
see the chapter :ref:`html-options` for details.
files, complete with style sheets and optionally the reStructuredText sources.
There are quite a few configuration values that customize
the output of this builder, see the chapter :ref:`html-options` for details.
.. autoattribute:: name
@@ -306,9 +306,9 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
.. module:: sphinx.builders.text
.. class:: TextBuilder
This builder produces a text file for each reST file -- this is almost the
same as the reST source, but with much of the markup stripped for better
readability.
This builder produces a text file for each reStructuredText file.
This is almost the same as the reStructuredText source,
but with much of the markup stripped for better readability.
.. autoattribute:: name
@@ -548,8 +548,8 @@ Serialization builder details
-----------------------------
All serialization builders outputs one file per source file and a few special
files. They also copy the reST source files in the directory ``_sources``
under the output directory.
files. They also copy the reStructuredText source files
to the ``_sources`` directory under the output directory.
The :class:`.PickleHTMLBuilder` is a builtin subclass that implements the pickle
serialization interface.

2
doc/usage/domains/c.rst
View File

@@ -24,7 +24,7 @@ The C domain (name **c**) is suited for documentation of C API.
.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
Note that you don't have to backslash-escape asterisks in the signature, as
it is not parsed by the reST inliner.
it is not parsed by the reStructuredText inliner.
In the description of a function you can use the following info fields
(see also :ref:`info-field-lists`).

3
doc/usage/domains/python.rst
View File

@@ -573,7 +573,8 @@ Info field lists
meta fields are added.
Inside Python object description directives, reST field lists with these fields
Inside Python object description directives,
reStructuredText field lists with these fields
are recognized and formatted nicely:
* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:

11
doc/usage/domains/restructuredtext.rst
View File

@@ -10,9 +10,10 @@ The reStructuredText domain (name **rst**) provides the following directives:
.. rst:directive:: .. rst:directive:: name
Describes a reST directive. The *name* can be a single directive name or
actual directive syntax (`..` prefix and `::` suffix) with arguments that
will be rendered differently. For example::
Describes a reStructuredText directive.
The *name* can be a single directive name or actual directive syntax
(`..` prefix and `::` suffix) with arguments that will be rendered differently.
For example::
.. rst:directive:: foo
@@ -38,7 +39,7 @@ The reStructuredText domain (name **rst**) provides the following directives:
.. rst:directive:: .. rst:directive:option:: name
Describes an option for reST directive. The *name* can be a single option
Describes an option for reStructuredText directive. The *name* can be a single option
name or option name with arguments which separated with colon (``:``).
For example::
@@ -77,7 +78,7 @@ The reStructuredText domain (name **rst**) provides the following directives:
.. rst:directive:: .. rst:role:: name
Describes a reST role. For example::
Describes a reStructuredText role. For example::
.. rst:role:: foo

6
doc/usage/extensions/autodoc.rst
View File

@@ -328,7 +328,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
once by specifying the option to :rst:dir:`automodule` directive.
Note: this will lead to markup errors if the inherited members come from a
module whose docstrings are not reST formatted.
module whose docstrings are not reStructuredText formatted.
.. versionadded:: 0.3
@@ -873,8 +873,8 @@ needed docstring processing in event :event:`autodoc-process-docstring`:
.. versionadded:: 4.1
.. versionchanged:: 4.3
``bases`` can contain a string as a base class name. It will be processed
as reST mark-up'ed text.
``bases`` can contain a string as a base class name.
It will be processed as reStructuredText.
Skipping members

16
doc/usage/extensions/doctest.rst
View File

@@ -344,12 +344,12 @@ The doctest extension uses the following configuration values:
.. confval:: doctest_test_doctest_blocks
If this is a nonempty string (the default is ``'default'``), standard reST
doctest blocks will be tested too. They will be assigned to the group name
given.
If this is a nonempty string (the default is ``'default'``),
standard reStructuredText doctest blocks will be tested too.
They will be assigned to the group name given.
reST doctest blocks are simply doctests put into a paragraph of their own,
like so::
reStructuredText doctest blocks are simply doctests
put into a paragraph of their own, like so::
Some documentation text.
@@ -378,8 +378,8 @@ The doctest extension uses the following configuration values:
with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a
special directive.
Note though that you can't have blank lines in reST doctest blocks. They
will be interpreted as one block ending and another one starting. Also,
removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
Note though that you can't have blank lines in reStructuredText doctest blocks.
They will be interpreted as one block ending and another one starting.
Also, removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
:rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags`
to achieve that in all code blocks with Python console content.

26
doc/usage/referencing.rst
View File

@@ -12,9 +12,10 @@ text will be the same as *target*.
There are some additional facilities, however, that make cross-referencing
roles more versatile:
* You may supply an explicit title and reference target, like in reST direct
hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link
text will be *title*.
* You may supply an explicit title and reference target,
like in reStructuredText direct hyperlinks:
``:role:`title <target>``` will refer to *target*,
but the link text will be *title*.
* If you prefix the content with ``!``, no reference/hyperlink will be created.
@@ -89,10 +90,11 @@ Cross-referencing arbitrary locations
.. rst:role:: ref
To support cross-referencing to arbitrary locations in any document, the
standard reST labels are used. For this to work label names must be unique
throughout the entire documentation. There are two ways in which you can
refer to labels:
To support cross-referencing to arbitrary locations in any document,
the standard reStructuredText labels are used.
For this to work label names must be unique
throughout the entire documentation.
There are two ways in which you can refer to labels:
* If you place a label directly before a section title, you can reference to
it with ``:ref:`label-name```. For example::
@@ -165,8 +167,9 @@ Referencing downloadable files
.. rst:role:: download
This role lets you link to files within your source tree that are not reST
documents that can be viewed, but files that can be downloaded.
This role lets you link to files within your source tree
that are not reStructuredText documents that can be viewed,
but files that can be downloaded.
When you use this role, the referenced file is automatically marked for
inclusion in the output when building (obviously, for HTML output only).
@@ -202,8 +205,9 @@ Cross-referencing figures by figure number
.. rst:role:: numref
Link to the specified figures, tables, code-blocks and sections; the standard
reST labels are used. When you use this role, it will insert a reference to
Link to the specified figures, tables, code-blocks and sections;
the standard reStructuredText labels are used.
When you use this role, it will insert a reference to
the figure with link text by its figure number like "Fig. 1.1".
If an explicit link text is given (as usual: ``:numref:`Image of Sphinx (Fig.

57
doc/usage/restructuredtext/basics.rst
View File

@@ -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
@@ -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.
@@ -308,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
@@ -325,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:
@@ -447,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)
@@ -513,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.
@@ -528,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*
@@ -539,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
@@ -615,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.
@@ -623,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

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

@@ -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
@@ -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::
@@ -353,7 +354,7 @@ units as well as normal text.
any subsections. For the HTML output, it is shown boxed off from the main
flow of the text.
The content of the :rst:dir:`seealso` directive should be a reST definition
The content of the :rst:dir:`seealso` directive should be a reStructuredText definition
list. Example::
.. seealso::
@@ -437,8 +438,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.
@@ -820,8 +821,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::
@@ -1052,7 +1053,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
@@ -1306,8 +1307,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::

5
doc/usage/restructuredtext/index.rst
View File

@@ -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

2
doc/usage/restructuredtext/roles.rst
View File

@@ -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: