diff --git a/CHANGES b/CHANGES index 4e6cfdd3f..9823d3e9e 100644 --- a/CHANGES +++ b/CHANGES @@ -15,6 +15,11 @@ Bugs fixed * #1340: Can't search alphabetical words on the HTML quick search generated with language='ja'. +Documentation +------------- + +* #1325: Added a "Intersphinx" tutorial section. (:file:`doc/tutorial.rst`) + Release 1.2 (released Dec 10, 2013) =================================== diff --git a/doc/tutorial.rst b/doc/tutorial.rst index 9fea11dbe..8e949d4c5 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' ` 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