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.

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
 -------------------------