diff options
author | Georg Brandl <georg@python.org> | 2014-09-19 12:59:18 +0200 |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2014-09-19 12:59:18 +0200 |
commit | 6a5f1407d6f338f2d200ef013117f0d995c787cd (patch) | |
tree | 232ce929b08fdf98d9d5d229c27238fe67091a47 /doc | |
parent | 152c995c650694dfe317cf124c57c397a250d67a (diff) | |
download | sphinx-6a5f1407d6f338f2d200ef013117f0d995c787cd.tar.gz |
Added the `any` role that can be used to find a cross-reference of
*any* type in *any* domain. Custom domains should implement the new
`~Domain.resolve_any_xref` method to make this work properly.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/markup/inline.rst | 47 |
1 files changed, 45 insertions, 2 deletions
diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 0cc97f43..7d83e317 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -12,7 +12,9 @@ They are written as ``:rolename:`content```. The default role (```content```) has no special meaning by default. You are 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. + :confval:`default_role` config value to set it to a known role -- the + :rst:role:`any` role to find anything or the :rst:role:`py:obj` role to find + Python objects are very useful for this. See :ref:`domains` for roles added by domains. @@ -38,12 +40,53 @@ more versatile: * 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. + refer to ``Queue.Queue.get`` but only display ``get`` as the link text. This + does not work with all cross-reference roles, but is domain specific. 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. +.. _any-role: + +Cross-referencing anything +-------------------------- + +.. rst:role:: any + + .. versionadded:: 1.3 + + This convenience role tries to do its best to find a valid target for its + reference text. + + * First, it tries standard cross-reference targets that would be referenced + by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`. + + Custom objects added to the standard domain by extensions (see + :meth:`.add_object_type`) are also searched. + + * Then, it looks for objects (targets) in all loaded domains. It is up to + the domains how specific a match must be. For example, in the Python + domain a reference of ``:any:`Builder``` would match the + ``sphinx.builders.Builder`` class. + + If none or multiple targets are found, a warning will be emitted. In the + case of multiple targets, you can change "any" to a specific role. + + This role is a good candidate for setting :confval:`default_role`. If you + do, you can write cross-references without a lot of markup overhead. For + example, in this Python function documentation :: + + .. function:: install() + + This function installs a `handler` for every signal known by the + `signal` module. See the section `about-signals` for more information. + + there could be references to a glossary term (usually ``:term:`handler```), a + Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a + section (usually ``:ref:`about-signals```). + + Cross-referencing objects ------------------------- |