diff options
Diffstat (limited to 'doc/tutorial.rst')
| -rw-r--r-- | doc/tutorial.rst | 31 |
1 files changed, 30 insertions, 1 deletions
diff --git a/doc/tutorial.rst b/doc/tutorial.rst index 9fea11db..8e949d4c 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -248,11 +248,40 @@ Therefore, you must add the appropriate path to :py:data:`sys.path` in your |more| See :mod:`sphinx.ext.autodoc` for the complete description of the features of autodoc. +Intersphinx +----------- + +Many Sphinx documents including the `Python documentation`_ are published on the +internet. When you want to make links to such documents from your +documentation, you can do it with :mod:`sphinx.ext.intersphinx`. + +.. _Python documentation: http://docs.python.org/3 + +In order to use intersphinx, you need to activate it in :file:`conf.py` by +putting the string ``'sphinx.ext.intersphinx'`` into the :confval:`extensions` +list and set up the :confval:`intersphinx_mapping` config value. + +For example, to link to ``io.open()`` in the Python library manual, you need to +setup your :confval:`intersphinx_mapping` like:: + + intersphinx_mapping = {'python': ('http://docs.python.org/3', None)} + +And now, you can write a cross-reference like ``:py:func:`io.open```. Any +cross-reference that has no matching target in the current documentation set, +will be looked up in the documentation sets configured in +:confval:`intersphinx_mapping` (this needs access to the URL in order to +download the list of valid targets). Intersphinx also works for some other +:ref:`domains' <domains>` roles including ``:ref:``, however it doesn't work for +``:doc:`` as that is non-domain role. + +|more| See :mod:`sphinx.ext.intersphinx` for the complete description of the +features of intersphinx. + More topics to be covered ------------------------- -- Other extensions (math, intersphinx, viewcode, doctest) +- Other extensions (math, viewcode, doctest) - Static files - Selecting a theme - Templating |