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

doc: Add "roles" doc to restructuredtext section

Browse Source 
This is essentially the 'markup/inline' with a few small fixes. There
are also some modifications to the basic rST guide to highlight what a
role is; we were doing this for directives but not roles.

Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
2017-11-03 13:38:39 +00:00
parent 9c2ab8c3bb
commit 3fcb1bd2dd
5 changed files with 81 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/glossary.rst
View File

@@ -81,7 +81,7 @@ Glossary
role
A reStructuredText markup element that allows marking a piece of text.
Like directives, roles are extensible. The basic syntax looks like this:
``:rolename:`content```. See :ref:`inlinemarkup` for details.
``:rolename:`content```. See :ref:`rst-inline-markup` for details.
source directory
The directory which, including its subdirectories, contains all source

1
doc/markup/index.rst
View File

@@ -11,7 +11,6 @@ markup`_. This section contains the reference material for these facilities.
toctree
para
code
inline
misc
More markup is added by :ref:`domains`.

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

@@ -27,7 +27,7 @@ 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.
.. _inlinemarkup:
.. _rst-inline-markup:
Inline markup
-------------
@@ -50,22 +50,8 @@ Be aware of some restrictions of this markup:
These restrictions may be lifted in future versions of the docutils.
reST also allows for custom "interpreted text roles", which signify that the
enclosed text should be interpreted in a specific way. Sphinx uses this to
provide semantic markup and cross-referencing of identifiers, as described in
the appropriate section. The general syntax is ``:rolename:`content```.
Standard reST provides the following roles:
* :durole:`emphasis` -- alternate spelling for ``*emphasis*``
* :durole:`strong` -- alternate spelling for ``**strong**``
* :durole:`literal` -- alternate spelling for ````literal````
* :durole:`subscript` -- subscript text
* :durole:`superscript` -- superscript text
* :durole:`title-reference` -- for titles of books, periodicals, and other
materials
See :ref:`inline-markup` for roles added by Sphinx.
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.
Lists and Quote-like blocks
@@ -249,6 +235,33 @@ documentation), and use a deeper nesting level, but keep in mind that most
target formats (HTML, LaTeX) have a limited supported nesting depth.
.. TODO This ref should be 'rst-roles', but that already exists. Rename the
.. other ones
.. _rst-roles-alt:
Roles
-----
A role or "custom interpreted text role" (:duref:`ref <roles>`) is an inline
piece of explicit markup. It signifies that that the enclosed text should be
interpreted in a specific way. Sphinx uses this to provide semantic markup and
cross-referencing of identifiers, as described in the appropriate section. The
general syntax is ``:rolename:`content```.
Docutils supports the following roles:
* :durole:`emphasis` -- equivalent of ``*emphasis*``
* :durole:`strong` -- equivalent of ``**strong**``
* :durole:`literal` -- equivalent of ````literal````
* :durole:`subscript` -- subscript text
* :durole:`superscript` -- superscript text
* :durole:`title-reference` -- for titles of books, periodicals, and other
materials
Refer to :doc:`roles` for roles added by Sphinx.
Explicit Markup
---------------

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

@@ -16,3 +16,4 @@ __ http://docutils.sourceforge.net/rst.html
:maxdepth: 2
basics
roles

98
doc/markup/inline.rst → doc/usage/restructuredtext/roles.rst
View File

@@ -1,9 +1,8 @@
.. highlight:: rest
.. highlight:: rst
.. _inline-markup:
Inline markup
=============
=====
Roles
=====
Sphinx uses interpreted text roles to insert semantic markup into documents.
They are written as ``:rolename:`content```.
@@ -22,15 +21,15 @@ See :ref:`domains` for roles added by domains.
.. _xref-syntax:
Cross-referencing syntax
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------
Cross-references are generated by many semantic interpreted text roles.
Basically, you only need to write ``:role:`target```, and a link will be created
to the item named *target* of the type indicated by *role*. The link's text
will be the same as *target*.
Basically, you only need to write ``:role:`target```, and a link will be
created to the item named *target* of the type indicated by *role*. The link's
text will be the same as *target*.
There are some additional facilities, however, that make cross-referencing roles
more versatile:
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
@@ -50,7 +49,7 @@ more versatile:
.. _any-role:
Cross-referencing anything
--------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. rst:role:: any
@@ -90,9 +89,8 @@ Cross-referencing anything
:mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is
found, all object types of intersphinx inventories are also searched.
Cross-referencing objects
-------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^
These roles are described with their respective domains:
@@ -106,7 +104,7 @@ These roles are described with their respective domains:
.. _ref-role:
Cross-referencing arbitrary locations
-------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. rst:role:: ref
@@ -116,7 +114,7 @@ Cross-referencing arbitrary locations
refer to labels:
* If you place a label directly before a section title, you can reference to
it with ``:ref:`label-name```. Example::
it with ``:ref:`label-name```. For example::
.. _my-reference-label:
@@ -127,11 +125,11 @@ Cross-referencing arbitrary locations
It refers to the section itself, see :ref:`my-reference-label`.
The ``:ref:`` role would then generate a link to the section, with the link
title being "Section to cross-reference". This works just as well when
section and reference are in different source files.
The ``:ref:`` role would then generate a link to the section, with the
link title being "Section to cross-reference". This works just as well
when section and reference are in different source files.
Automatic labels also work with figures: given ::
Automatic labels also work with figures. For example::
.. _my-figure:
@@ -139,8 +137,8 @@ Cross-referencing arbitrary locations
Figure caption
a reference ``:ref:`my-figure``` would insert a reference to the figure
with link text "Figure caption".
In this case, a reference ``:ref:`my-figure``` would insert a reference
to the figure with link text "Figure caption".
The same works for tables that are given an explicit caption using the
:dudir:`table` directive.
@@ -151,17 +149,17 @@ Cross-referencing arbitrary locations
.. note::
Reference labels must start with an underscore. When referencing a
label, the underscore must be omitted (see examples above).
Reference labels must start with an underscore. When referencing a label,
the underscore must be omitted (see examples above).
Using :rst:role:`ref` is advised over standard reStructuredText links to
sections (like ```Section title`_``) because it works across files, when
section headings are changed, and for all builders that support
cross-references.
section headings are changed, will raise warnings if incorrect, and works
for all builders that support cross-references.
Cross-referencing documents
---------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 0.6
@@ -180,7 +178,7 @@ There is also a way to directly link to documents:
Referencing downloadable files
------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 0.6
@@ -213,7 +211,7 @@ Referencing downloadable files
See :download:`this example script <../example.py>`.
Cross-referencing figures by figure number
------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 1.3
@@ -238,7 +236,7 @@ Cross-referencing figures by figure number
so this role inserts not a reference but the label or the link text.
Cross-referencing other items of interest
-----------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following roles do possibly create a cross-reference, but do not refer to
objects:
@@ -280,10 +278,10 @@ The following role creates a cross-reference to a term in a
Other semantic markup
~~~~~~~~~~~~~~~~~~~~~
---------------------
The following roles don't do anything special except formatting the text
in a different style:
The following roles don't do anything special except formatting the text in a
different style:
.. rst:role:: abbr
@@ -331,22 +329,22 @@ in a different style:
.. rst:role:: kbd
Mark a sequence of keystrokes. What form the key sequence takes may depend
on platform- or application-specific conventions. When there are no relevant
conventions, the names of modifier keys should be spelled out, to improve
accessibility for new users and non-native speakers. For example, an
*xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
on platform- or application-specific conventions. When there are no
relevant conventions, the names of modifier keys should be spelled out, to
improve accessibility for new users and non-native speakers. For example,
an *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
reference to a specific application or platform, the same sequence should be
marked as ``:kbd:`Control-x Control-f```.
.. rst:role:: mailheader
The name of an RFC 822-style mail header. This markup does not imply that
the header is being used in an email message, but can be used to refer to any
header of the same "style." This is also used for headers defined by the
various MIME specifications. The header name should be entered in the same
way it would normally be found in practice, with the camel-casing conventions
being preferred where there is more than one common usage. For example:
``:mailheader:`Content-Type```.
the header is being used in an email message, but can be used to refer to
any header of the same "style." This is also used for headers defined by
the various MIME specifications. The header name should be entered in the
same way it would normally be found in practice, with the camel-casing
conventions being preferred where there is more than one common usage. For
example: ``:mailheader:`Content-Type```.
.. rst:role:: makevar
@@ -354,9 +352,9 @@ in a different style:
.. rst:role:: manpage
A reference to a Unix manual page including the section,
e.g. ``:manpage:`ls(1)```. Creates a hyperlink to an external site
rendering the manpage if :confval:`manpages_url` is defined.
A reference to a Unix manual page including the section, e.g.
``:manpage:`ls(1)```. Creates a hyperlink to an external site rendering the
manpage if :confval:`manpages_url` is defined.
.. rst:role:: menuselection
@@ -370,8 +368,8 @@ in a different style:
:menuselection:`Start --> Programs`
When including a selection that includes some trailing indicator, such as the
ellipsis some operating systems use to indicate that the command opens a
When including a selection that includes some trailing indicator, such as
the ellipsis some operating systems use to indicate that the command opens a
dialog, the indicator should be omitted from the selection name.
``menuselection`` also supports ampersand accelerators just like
@@ -386,6 +384,8 @@ in a different style:
The name of a Usenet newsgroup.
.. todo:: Is this not part of the standard domain?
.. rst:role:: program
The name of an executable program. This may differ from the file name for
@@ -432,7 +432,7 @@ the standard reST markup for that purpose.
.. _default-substitutions:
Substitutions
~~~~~~~~~~~~~
-------------
The documentation system provides three substitutions that are defined by
default. They are set in the build configuration file.