From 0c2430beda789335d70a4db34c02b32ed65e23bb Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 26 Jan 2009 21:29:38 +0000 Subject: [PATCH] Copy over docs on advanced role features from Sphinx docs. --- Doc/documenting/markup.rst | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index b4b03d27a53..3ca8983ee1f 100644 --- a/Doc/documenting/markup.rst +++ b/Doc/documenting/markup.rst @@ -290,10 +290,22 @@ they should be marked simply with ``*var*``. For all other roles, you have to write ``:rolename:`content```. -.. note:: +There are some additional facilities that make cross-referencing roles more +versatile: - For all cross-referencing roles, if you prefix the content with ``!``, no - reference/hyperlink will be created. +* You may supply an explicit title and reference target, like in reST direct + hyperlinks: ``:role:`title ``` will refer to *target*, but the link + text will be *title*. + +* 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. + + 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. The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found: