diff --git a/doc/glossary.rst b/doc/glossary.rst index acac3a590..216277f41 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -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 diff --git a/doc/markup/index.rst b/doc/markup/index.rst index ca70b9581..c3f23967e 100644 --- a/doc/markup/index.rst +++ b/doc/markup/index.rst @@ -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`. diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 4084997e6..de18f7f4d 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -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 `) 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 --------------- diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst index 5dc8f25dd..8b7b75a1a 100644 --- a/doc/usage/restructuredtext/index.rst +++ b/doc/usage/restructuredtext/index.rst @@ -16,3 +16,4 @@ __ http://docutils.sourceforge.net/rst.html :maxdepth: 2 basics + roles diff --git a/doc/markup/inline.rst b/doc/usage/restructuredtext/roles.rst similarity index 87% rename from doc/markup/inline.rst rename to doc/usage/restructuredtext/roles.rst index c8dfb6ff7..8bfc3adcb 100644 --- a/doc/markup/inline.rst +++ b/doc/usage/restructuredtext/roles.rst @@ -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 ``` 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.