Add intersphinx extension.

2 files changed, 68 insertions, 0 deletions

diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst
new file mode 100644
index 00000000..befae2c0
--- /dev/null
+++ b/doc/ext/intersphinx.rst
@@ -0,0 +1,67 @@
+:mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation
+======================================================================
+
+.. module:: sphinx.ext.intersphinx
+   :synopsis: Link to other Sphinx documentation.
+
+.. index:: pair: automatic; linking
+
+.. versionadded:: 0.5
+
+This extension can generate automatic links to the documentation of Python
+objects in other projects.  This works as follows:
+
+* Each Sphinx HTML build creates a file named :file:`objects.inv` that
+  contains a mapping from Python identifiers to URIs relative to the HTML set's
+  root.
+
+* Projects using the Intersphinx extension can specify the location of such
+  mapping files in the :confval:`intersphinx_mapping` config value.  The mapping
+  will then be used to resolve otherwise missing references to Python objects
+  into links to the other documentation.
+
+* By default, the mapping file is assumed to be at the same location as the rest
+  of the documentation; however, the location of the mapping file can also be
+  specified individually, e.g. if the docs should be buildable without Internet
+  access.
+
+To use intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your
+:confval:`extensions` config value, and use these new config values to activate
+linking:
+
+.. confval:: intersphinx_mapping
+
+   A dictionary mapping URIs to either ``None`` or an URI.  The keys are the
+   base URI of the foreign Sphinx documentation sets and can be local paths or
+   HTTP URIs.  The values indicate where the inventory file can be found: they
+   can be ``None`` (at the same location as the base URI) or another local or
+   HTTP URI.
+
+   Relative local paths in the keys are taken as relative to the base of the
+   built documentation, while relative local paths in the values are taken as
+   relative to the source directory.
+
+   An example, to add links to modules and objects in the Python standard
+   library documentation::
+
+      intersphinx_mapping = {'http://docs.python.org/dev': None}
+
+   This will download the corresponding :file:`objects.inv` file from the
+   Internet and generate links to the pages under the given URI.  The downloaded
+   inventory is cached in the Sphinx environment, so it must be redownloaded
+   whenever you do a full rebuild. 
+
+   A second example, showing the meaning of a non-``None`` value::
+
+      intersphinx_mapping = {'http://docs.python.org/dev': 'python-inv.txt'}
+
+   This will read the inventory from :file:`python.inv` in the source
+   directory, but still generate links to the pages under
+   ``http://docs.python.org/dev``.  It is up to you to update the inventory file
+   as new objects are added to the Python documentation.
+
+.. confval:: intersphinx_cache_limit
+
+   The maximum number of days to cache remote inventories.  The default is
+   ``5``, meaning five days.  Set this to a negative value to cache inventories
+   for unlimited time.
diff --git a/doc/extensions.rst b/doc/extensions.rst
index 5eaf1ab3..fbb90fe9 100644
--- a/doc/extensions.rst
+++ b/doc/extensions.rst
@@ -34,6 +34,7 @@ These extensions are built in and can be activated by respective entries in the
 
    ext/autodoc
    ext/doctest
+   ext/intersphinx
    ext/refcounting
    ext/ifconfig
    ext/coverage