IntenseWebs/sphinx
3
0 Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2026-10-25 22:50:22 -05:00
Code Issues Packages Projects Releases Wiki Activity

Standardise on "reStructuredText" over "reST" in documentation

Browse Source
This commit is contained in:
Adam Turner committed 2024-07-15 02:15:52 +01:00
1 parent 26576590ed
commit f2640a4286
18 files changed
+111 -101
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

doc/usage/restructuredtext/basics.rst
+30 -27
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
doc/usage/restructuredtext/directives.rst
+15 -14
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::
doc/usage/restructuredtext/index.rst
+2 -3
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
doc/usage/restructuredtext/roles.rst
+1 -1
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: