mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Move inline markup description to domains page.
This commit is contained in:
Georg Brandl
parent
3e9182550a
commit
a479d56b24
110
doc/domains.rst
110
doc/domains.rst
@ -90,6 +90,24 @@ giving the domain name, i.e. ::
|
||||
Reference to :func:`pyfunc`.
|
||||
|
||||
|
||||
Cross-referencing syntax
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For cross-reference roles provided by domains, the same facilities exist as for
|
||||
general cross-references. See :ref:`xref-syntax`.
|
||||
|
||||
In short:
|
||||
|
||||
* You may supply an explicit title and reference target: ``: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.
|
||||
|
||||
* If you prefix the content with ``~``, the link text will only be the last
|
||||
component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will
|
||||
refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
|
||||
|
||||
|
||||
The Python Domain
|
||||
-----------------
|
||||
|
||||
@ -280,6 +298,75 @@ This will render like this:
|
||||
:rtype: list of strings
|
||||
|
||||
|
||||
Cross-referencing Python objects
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The following roles refer to objects in modules and are possibly hyperlinked if
|
||||
a matching identifier is found:
|
||||
|
||||
.. role:: py:mod
|
||||
|
||||
Reference a module; a dotted name may be used. This should also be used for
|
||||
package names.
|
||||
|
||||
.. role:: py:func
|
||||
|
||||
Reference a Python function; dotted names may be used. The role text needs
|
||||
not include trailing parentheses to enhance readability; they will be added
|
||||
automatically by Sphinx if the :confval:`add_function_parentheses` config
|
||||
value is true (the default).
|
||||
|
||||
.. role:: py:data
|
||||
|
||||
Reference a module-level variable.
|
||||
|
||||
.. role:: py:const
|
||||
|
||||
Reference a "defined" constant. This may be a C-language ``#define`` or a
|
||||
Python variable that is not intended to be changed.
|
||||
|
||||
.. role:: py:class
|
||||
|
||||
Reference a class; a dotted name may be used.
|
||||
|
||||
.. role:: py:meth
|
||||
|
||||
Reference a method of an object. The role text can include the type name and
|
||||
the method name; if it occurs within the description of a type, the type name
|
||||
can be omitted. A dotted name may be used.
|
||||
|
||||
.. role:: py:attr
|
||||
|
||||
Reference a data attribute of an object.
|
||||
|
||||
.. role:: py:exc
|
||||
|
||||
Reference an exception. A dotted name may be used.
|
||||
|
||||
.. role:: py:obj
|
||||
|
||||
Reference an object of unspecified type. Useful e.g. as the
|
||||
:confval:`default_role`.
|
||||
|
||||
.. versionadded:: 0.4
|
||||
|
||||
The name enclosed in this markup can include a module name and/or a class name.
|
||||
For example, ``:py:func:`filter``` could refer to a function named ``filter`` in
|
||||
the current module, or the built-in function of that name. In contrast,
|
||||
``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the
|
||||
``foo`` module.
|
||||
|
||||
Normally, names in these roles are searched first without any further
|
||||
qualification, then with the current module name prepended, then with the
|
||||
current module and class name (if any) prepended. If you prefix the name with a
|
||||
dot, this order is reversed. For example, in the documentation of Python's
|
||||
:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in
|
||||
function, while ``:py:func:`.open``` refers to :func:`codecs.open`.
|
||||
|
||||
A similar heuristic is used to determine whether the name is an attribute of the
|
||||
currently documented class.
|
||||
|
||||
|
||||
The C Domain
|
||||
------------
|
||||
|
||||
@ -328,6 +415,29 @@ The C domain (name **c**) is suited for documentation of C API.
|
||||
.. c:var:: PyObject* PyClass_Type
|
||||
|
||||
|
||||
Cross-referencing C constructs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The following roles create cross-references to C-language constructs if they are
|
||||
defined in the documentation:
|
||||
|
||||
.. role:: c:data
|
||||
|
||||
Reference a C-language variable.
|
||||
|
||||
.. role:: c:func
|
||||
|
||||
Reference a C-language function. Should include trailing parentheses.
|
||||
|
||||
.. role:: c:macro
|
||||
|
||||
Reference a "simple" C macro, as defined above.
|
||||
|
||||
.. role:: c:type
|
||||
|
||||
Reference a C-language type.
|
||||
|
||||
|
||||
The Standard Domain
|
||||
-------------------
|
||||
|
||||
|
||||
@ -56,5 +56,5 @@ or some (not broken) SVN trunk snapshot.
|
||||
Usage
|
||||
-----
|
||||
|
||||
See :doc:`the tutorial <tutorial>` for an introduction. It also contains links
|
||||
to more advanced sections in this manual for the topics it discusses.
|
||||
See :doc:`tutorial` for an introduction. It also contains links to more
|
||||
advanced sections in this manual for the topics it discusses.
|
||||
|
||||
@ -12,11 +12,13 @@ They are written as ``:rolename:`content```.
|
||||
free to use it for anything you like, e.g. variable names; use the
|
||||
:confval:`default_role` config value to set it to a known role.
|
||||
|
||||
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
|
||||
@ -32,149 +34,14 @@ more versatile:
|
||||
|
||||
* If you prefix the content with ``!``, no reference/hyperlink will be created.
|
||||
|
||||
* For the Python object roles, if you prefix the content with ``~``, the link
|
||||
text will only be the last component of the target. For example,
|
||||
``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only
|
||||
display ``get`` as the link text.
|
||||
* If you prefix the content with ``~``, the link text will only be the last
|
||||
component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will
|
||||
refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
|
||||
|
||||
In HTML output, the link's ``title`` attribute (that is e.g. shown as a
|
||||
tool-tip on mouse-hover) will always be the full target name.
|
||||
|
||||
|
||||
Cross-referencing Python objects
|
||||
--------------------------------
|
||||
|
||||
The following roles refer to objects in modules and are possibly hyperlinked if
|
||||
a matching identifier is found:
|
||||
|
||||
.. role:: mod
|
||||
|
||||
The name of a module; a dotted name may be used. This should also be used for
|
||||
package names.
|
||||
|
||||
.. role:: func
|
||||
|
||||
The name of a Python function; dotted names may be used. The role text
|
||||
needs not include trailing parentheses to enhance readability; they will be
|
||||
added automatically by Sphinx if the :confval:`add_function_parentheses`
|
||||
config value is true (the default).
|
||||
|
||||
.. role:: data
|
||||
|
||||
The name of a module-level variable.
|
||||
|
||||
.. role:: const
|
||||
|
||||
The name of a "defined" constant. This may be a C-language ``#define``
|
||||
or a Python variable that is not intended to be changed.
|
||||
|
||||
.. role:: class
|
||||
|
||||
A class name; a dotted name may be used.
|
||||
|
||||
.. role:: meth
|
||||
|
||||
The name of a method of an object. The role text should include the type
|
||||
name and the method name; if it occurs within the description of a type,
|
||||
the type name can be omitted. A dotted name may be used.
|
||||
|
||||
.. role:: attr
|
||||
|
||||
The name of a data attribute of an object.
|
||||
|
||||
.. role:: exc
|
||||
|
||||
The name of an exception. A dotted name may be used.
|
||||
|
||||
.. role:: obj
|
||||
|
||||
The name of an object of unspecified type. Useful e.g. as the
|
||||
:confval:`default_role`.
|
||||
|
||||
.. versionadded:: 0.4
|
||||
|
||||
The name enclosed in this markup can include a module name and/or a class name.
|
||||
For example, ``:func:`filter``` could refer to a function named ``filter`` in
|
||||
the current module, or the built-in function of that name. In contrast,
|
||||
``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
|
||||
module.
|
||||
|
||||
Normally, names in these roles are searched first without any further
|
||||
qualification, then with the current module name prepended, then with the
|
||||
current module and class name (if any) prepended. If you prefix the name with a
|
||||
dot, this order is reversed. For example, in the documentation of Python's
|
||||
:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
|
||||
while ``:func:`.open``` refers to :func:`codecs.open`.
|
||||
|
||||
A similar heuristic is used to determine whether the name is an attribute of
|
||||
the currently documented class.
|
||||
|
||||
|
||||
Cross-referencing C constructs
|
||||
------------------------------
|
||||
|
||||
The following roles create cross-references to C-language constructs if they
|
||||
are defined in the documentation:
|
||||
|
||||
.. role:: cdata
|
||||
|
||||
The name of a C-language variable.
|
||||
|
||||
.. role:: cfunc
|
||||
|
||||
The name of a C-language function. Should include trailing parentheses.
|
||||
|
||||
.. role:: cmacro
|
||||
|
||||
The name of a "simple" C macro, as defined above.
|
||||
|
||||
.. role:: ctype
|
||||
|
||||
The name of a C-language type.
|
||||
|
||||
|
||||
Cross-referencing other items of interest
|
||||
-----------------------------------------
|
||||
|
||||
The following roles do possibly create a cross-reference, but do not refer to
|
||||
objects:
|
||||
|
||||
.. role:: envvar
|
||||
|
||||
An environment variable. Index entries are generated. Also generates a link
|
||||
to the matching :dir:`envvar` directive, if it exists.
|
||||
|
||||
.. role:: token
|
||||
|
||||
The name of a grammar token (used to create links between
|
||||
:dir:`productionlist` directives).
|
||||
|
||||
.. role:: keyword
|
||||
|
||||
The name of a keyword in Python. This creates a link to a reference label
|
||||
with that name, if it exists.
|
||||
|
||||
.. role:: option
|
||||
|
||||
A command-line option to an executable program. The leading hyphen(s) must
|
||||
be included. This generates a link to a :dir:`cmdoption` directive, if it
|
||||
exists.
|
||||
|
||||
|
||||
The following role creates a cross-reference to the term in the glossary:
|
||||
|
||||
.. role:: term
|
||||
|
||||
Reference to a term in the glossary. The glossary is created using the
|
||||
``glossary`` directive containing a definition list with terms and
|
||||
definitions. It does not have to be in the same file as the ``term`` markup,
|
||||
for example the Python docs have one global glossary in the ``glossary.rst``
|
||||
file.
|
||||
|
||||
If you use a term that's not explained in a glossary, you'll get a warning
|
||||
during build.
|
||||
|
||||
|
||||
.. _ref-role:
|
||||
|
||||
Cross-referencing arbitrary locations
|
||||
@ -405,6 +272,48 @@ Note that there are no special roles for including hyperlinks as you can use
|
||||
the standard reST markup for that purpose.
|
||||
|
||||
|
||||
Cross-referencing other items of interest
|
||||
-----------------------------------------
|
||||
|
||||
The following roles do possibly create a cross-reference, but do not refer to
|
||||
objects:
|
||||
|
||||
.. role:: envvar
|
||||
|
||||
An environment variable. Index entries are generated. Also generates a link
|
||||
to the matching :dir:`envvar` directive, if it exists.
|
||||
|
||||
.. role:: token
|
||||
|
||||
The name of a grammar token (used to create links between
|
||||
:dir:`productionlist` directives).
|
||||
|
||||
.. role:: keyword
|
||||
|
||||
The name of a keyword in Python. This creates a link to a reference label
|
||||
with that name, if it exists.
|
||||
|
||||
.. role:: option
|
||||
|
||||
A command-line option to an executable program. The leading hyphen(s) must
|
||||
be included. This generates a link to a :dir:`option` directive, if it
|
||||
exists.
|
||||
|
||||
|
||||
The following role creates a cross-reference to the term in the glossary:
|
||||
|
||||
.. role:: term
|
||||
|
||||
Reference to a term in the glossary. The glossary is created using the
|
||||
``glossary`` directive containing a definition list with terms and
|
||||
definitions. It does not have to be in the same file as the ``term`` markup,
|
||||
for example the Python docs have one global glossary in the ``glossary.rst``
|
||||
file.
|
||||
|
||||
If you use a term that's not explained in a glossary, you'll get a warning
|
||||
during build.
|
||||
|
||||
|
||||
.. _default-substitutions:
|
||||
|
||||
Substitutions
|
||||
|
||||
@ -87,10 +87,10 @@ Including content based on tags
|
||||
Tables
|
||||
------
|
||||
|
||||
Use standard reStructuredText tables. They work fine in HTML output, however
|
||||
there are some gotchas when using tables in LaTeX: the column width is hard to
|
||||
determine correctly automatically. For this reason, the following directive
|
||||
exists:
|
||||
Use :ref:`standard reStructuredText tables <rst-tables>`. They work fine in
|
||||
HTML output, however there are some gotchas when using tables in LaTeX: the
|
||||
column width is hard to determine correctly automatically. For this reason, the
|
||||
following directive exists:
|
||||
|
||||
.. directive:: .. tabularcolumns:: column spec
|
||||
|
||||
|
||||
@ -231,7 +231,7 @@ derived forms), but provides enough to allow context-free grammars to be
|
||||
displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
|
||||
the definition of the symbol. There is this directive:
|
||||
|
||||
.. directive:: productionlist
|
||||
.. directive:: .. productionlist:: [name]
|
||||
|
||||
This directive is used to enclose a group of productions. Each production is
|
||||
given on a single line and consists of a name, separated by a colon from the
|
||||
@ -239,17 +239,19 @@ the definition of the symbol. There is this directive:
|
||||
continuation line must begin with a colon placed at the same column as in the
|
||||
first line.
|
||||
|
||||
The argument to :dir:`productionlist` serves to distinguish different sets of
|
||||
production lists that belong to different grammars.
|
||||
|
||||
Blank lines are not allowed within ``productionlist`` directive arguments.
|
||||
|
||||
The definition can contain token names which are marked as interpreted text
|
||||
(e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
|
||||
to the productions of these tokens.
|
||||
to the productions of these tokens. Outside of the production list, you can
|
||||
reference to token productions using :role:`token`.
|
||||
|
||||
Note that no further reST parsing is done in the production, so that you
|
||||
don't have to escape ``*`` or ``|`` characters.
|
||||
|
||||
.. XXX describe optional first parameter
|
||||
|
||||
The following is an example taken from the Python Reference Manual::
|
||||
|
||||
.. productionlist::
|
||||
|
||||
@ -140,6 +140,8 @@ That way, the second sentence in the above example's first paragraph would be
|
||||
rendered as "The next paragraph is a code sample:".
|
||||
|
||||
|
||||
.. _rst-tables:
|
||||
|
||||
Tables
|
||||
------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user