<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>sphinx.ext.intersphinx – Link to other projects’ documentation — Sphinx 1.1.3 documentation</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.1.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Sphinx 1.1.3 documentation"
href="../_static/opensearch.xml"/>
<link rel="top" title="Sphinx 1.1.3 documentation" href="../index.html" />
<link rel="up" title="Sphinx Extensions" href="../extensions.html" />
<link rel="next" title="Math support in Sphinx" href="math.html" />
<link rel="prev" title="sphinx.ext.doctest – Test snippets in the documentation" href="doctest.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<img src="../_static/sphinx.png" alt="Sphinx logo" />
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="math.html" title="Math support in Sphinx"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="doctest.html" title="sphinx.ext.doctest – Test snippets in the documentation"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../extensions.html" accesskey="U">Sphinx Extensions</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="doctest.html"
title="previous chapter"><tt class="docutils literal"><span class="pre">sphinx.ext.doctest</span></tt> – Test snippets in the documentation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="math.html"
title="next chapter">Math support in Sphinx</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/ext/intersphinx.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-sphinx.ext.intersphinx">
<span id="sphinx-ext-intersphinx-link-to-other-projects-documentation"></span><h1><a class="reference internal" href="#module-sphinx.ext.intersphinx" title="sphinx.ext.intersphinx: Link to other Sphinx documentation."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.intersphinx</span></tt></a> – Link to other projects’ documentation<a class="headerlink" href="#module-sphinx.ext.intersphinx" title="Permalink to this headline">¶</a></h1>
<p class="versionadded" id="index-0">
<span class="versionmodified">New in version 0.5.</span></p>
<p>This extension can generate automatic links to the documentation of objects in
other projects.</p>
<p>Usage is simple: whenever Sphinx encounters a cross-reference that has no
matching target in the current documentation set, it looks for targets in the
documentation sets configured in <a class="reference internal" href="#confval-intersphinx_mapping"><tt class="xref std std-confval docutils literal"><span class="pre">intersphinx_mapping</span></tt></a>. A reference
like <tt class="docutils literal"><span class="pre">:py:class:`zipfile.ZipFile`</span></tt> can then link to the Python documentation
for the ZipFile class, without you having to specify where it is located
exactly.</p>
<p>When using the “new” format (see below), you can even force lookup in a foreign
set by prefixing the link target appropriately. A link like <tt class="docutils literal"><span class="pre">:ref:`comparison</span>
<span class="pre">manual</span> <span class="pre"><python:comparisons>`</span></tt> will then link to the label “comparisons” in the
doc set “python”, if it exists.</p>
<p>Behind the scenes, this works as follows:</p>
<ul class="simple">
<li>Each Sphinx HTML build creates a file named <tt class="file docutils literal"><span class="pre">objects.inv</span></tt> that contains
a mapping from object names to URIs relative to the HTML set’s root.</li>
<li>Projects using the Intersphinx extension can specify the location of such
mapping files in the <a class="reference internal" href="#confval-intersphinx_mapping"><tt class="xref std std-confval docutils literal"><span class="pre">intersphinx_mapping</span></tt></a> config value. The mapping
will then be used to resolve otherwise missing references to objects into
links to the other documentation.</li>
<li>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.</li>
</ul>
<p>To use intersphinx linking, add <tt class="docutils literal"><span class="pre">'sphinx.ext.intersphinx'</span></tt> to your
<a class="reference internal" href="../config.html#confval-extensions"><tt class="xref std std-confval docutils literal"><span class="pre">extensions</span></tt></a> config value, and use these new config values to activate
linking:</p>
<dl class="confval">
<dt id="confval-intersphinx_mapping">
<tt class="descname">intersphinx_mapping</tt><a class="headerlink" href="#confval-intersphinx_mapping" title="Permalink to this definition">¶</a></dt>
<dd><p>This config value contains the locations and names of other projects that
should be linked to in this documentation.</p>
<p>Relative local paths for target locations are taken as relative to the base
of the built documentation, while relative local paths for inventory
locations are taken as relative to the source directory.</p>
<p>When fetching remote inventory files, proxy settings will be read from
the <tt class="docutils literal"><span class="pre">$HTTP_PROXY</span></tt> environment variable.</p>
<p><strong>Old format for this config value</strong></p>
<p>This is the format used before Sphinx 1.0. It is still recognized.</p>
<p>A dictionary mapping URIs to either <tt class="docutils literal"><span class="pre">None</span></tt> 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 <tt class="docutils literal"><span class="pre">None</span></tt> (at the same location as the base URI) or another local or
HTTP URI.</p>
<p><strong>New format for this config value</strong></p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
<p>A dictionary mapping unique identifiers to a tuple <tt class="docutils literal"><span class="pre">(target,</span> <span class="pre">inventory)</span></tt>.
Each <tt class="docutils literal"><span class="pre">target</span></tt> is the base URI of a foreign Sphinx documentation set and can
be a local path or an HTTP URI. The <tt class="docutils literal"><span class="pre">inventory</span></tt> indicates where the
inventory file can be found: it can be <tt class="docutils literal"><span class="pre">None</span></tt> (at the same location as
the base URI) or another local or HTTP URI.</p>
<p>The unique identifier can be used to prefix cross-reference targets, so that
it is clear which intersphinx set the target belongs to. A link like
<tt class="docutils literal"><span class="pre">:ref:`comparison</span> <span class="pre">manual</span> <span class="pre"><python:comparisons>`</span></tt> will link to the label
“comparisons” in the doc set “python”, if it exists.</p>
<p><strong>Example</strong></p>
<p>To add links to modules and objects in the Python standard library
documentation, use:</p>
<div class="highlight-python"><pre>intersphinx_mapping = {'python': ('http://docs.python.org/3.2', None)}</pre>
</div>
<p>This will download the corresponding <tt class="file docutils literal"><span class="pre">objects.inv</span></tt> 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.</p>
<p>A second example, showing the meaning of a non-<tt class="docutils literal"><span class="pre">None</span></tt> value of the second
tuple item:</p>
<div class="highlight-python"><pre>intersphinx_mapping = {'python': ('http://docs.python.org/3.2',
'python-inv.txt')}</pre>
</div>
<p>This will read the inventory from <tt class="file docutils literal"><span class="pre">python-inv.txt</span></tt> in the source
directory, but still generate links to the pages under
<tt class="docutils literal"><span class="pre">http://docs.python.org/3.2</span></tt>. It is up to you to update the inventory file as
new objects are added to the Python documentation.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-intersphinx_cache_limit">
<tt class="descname">intersphinx_cache_limit</tt><a class="headerlink" href="#confval-intersphinx_cache_limit" title="Permalink to this definition">¶</a></dt>
<dd><p>The maximum number of days to cache remote inventories. The default is
<tt class="docutils literal"><span class="pre">5</span></tt>, meaning five days. Set this to a negative value to cache inventories
for unlimited time.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="math.html" title="Math support in Sphinx"
>next</a> |</li>
<li class="right" >
<a href="doctest.html" title="sphinx.ext.doctest – Test snippets in the documentation"
>previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="../extensions.html" >Sphinx Extensions</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011, Georg Brandl.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
distrib
>
Mageia
>
4
>
i586
>
media
>
core-release
>
by-pkgid
>
c95717a2237548a7bdaddf39c85b0f0f
>
files
>
108
