diff options
Diffstat (limited to 'doc/markup/inline.rst')
| -rw-r--r-- | doc/markup/inline.rst | 48 |
1 files changed, 46 insertions, 2 deletions
diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 5dbd638e..9f8a01a5 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -224,7 +224,50 @@ 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. + + +Referencing downloadable files +------------------------------ + +.. versionadded:: 0.6 + +.. role:: download + + This role lets you link to files within your source tree that are not reST + documents that can be viewed, but files that can be downloaded. + + When you use this role, the referenced file is automatically marked for + inclusion in the output when building (obviously, for HTML output only). + All downloadable files are put into the ``_downloads`` subdirectory of the + output directory; duplicate filenames are handled. + + An example:: + + See :download:`this example script <../example.py>`. + + The given filename is relative to the directory the current source file is + contained in. The ``../example.py`` file will be copied to the output + directory, and a suitable link generated to it. + Other semantic markup --------------------- @@ -330,7 +373,7 @@ in a different style: curly braces to indicate a "variable" part, as in ``:file:``. If you don't need the "variable part" indication, use the standard - ````code```` instead. + ````code```` instead. The following roles generate external links: @@ -351,6 +394,7 @@ The following roles generate external links: Note that there are no special roles for including hyperlinks as you can use the standard reST markup for that purpose. + .. _default-substitutions: Substitutions |