mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
doc: Add "roles" doc to restructuredtext section
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
parent
9c2ab8c3bb
commit
3fcb1bd2dd
@ -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
|
||||
|
||||
@ -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`.
|
||||
|
||||
@ -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
|
||||
---------------
|
||||
|
||||
|
||||
@ -16,3 +16,4 @@ __ http://docutils.sourceforge.net/rst.html
|
||||
:maxdepth: 2
|
||||
|
||||
basics
|
||||
roles
|
||||
|
||||
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user