Due to popular demand, added a ``:doc:`` role which directly

links to another document without the need of creating a
label to which a ``:ref:`` could link to.

1 files changed, 20 insertions, 1 deletions

diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index fc5d08df..5776c35e 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -223,7 +223,26 @@ to labels:
 Using :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.
-  
+
+
+Cross-referencing documents
+---------------------------
+
+.. versionadded:: 0.6
+
+There is also a way to directly link to documents:
+
+.. role:: doc
+
+   Link to the specified document; the document name can be specified in
+   absolute or relative fashion.  For example, if the reference
+   ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link
+   refers to ``sketches/parrot``.  If the reference is ``:doc:`/people``` or
+   ``:doc:`../people```, the link refers to ``people``.
+
+   If no explicit link text is given (like usual: ``:doc:`Monty Python members
+   </people>```), the link caption will be the title of the given document.
+
 
 Other semantic markup
 ---------------------