<!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.extlinks – Markup to shorten external links — 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="sphinx.ext.viewcode – Add links to highlighted source code" href="viewcode.html" />
<link rel="prev" title="sphinx.ext.todo – Support for todo items" href="todo.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="viewcode.html" title="sphinx.ext.viewcode – Add links to highlighted source code"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="todo.html" title="sphinx.ext.todo – Support for todo items"
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="todo.html"
title="previous chapter"><tt class="docutils literal"><span class="pre">sphinx.ext.todo</span></tt> – Support for todo items</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="viewcode.html"
title="next chapter"><tt class="docutils literal"><span class="pre">sphinx.ext.viewcode</span></tt> – Add links to highlighted source code</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/ext/extlinks.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.extlinks">
<span id="sphinx-ext-extlinks-markup-to-shorten-external-links"></span><h1><a class="reference internal" href="#module-sphinx.ext.extlinks" title="sphinx.ext.extlinks: Allow inserting external links with common base URLs easily."><tt class="xref py py-mod docutils literal"><span class="pre">sphinx.ext.extlinks</span></tt></a> – Markup to shorten external links<a class="headerlink" href="#module-sphinx.ext.extlinks" title="Permalink to this headline">¶</a></h1>
<p><em>Module author: Georg Brandl</em></p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0.</span></p>
<p>This extension is meant to help with the common pattern of having many external
links that point to URLs on one and the same site, e.g. links to bug trackers,
version control web interfaces, or simply subpages in other websites. It does
so by providing aliases to base URLs, so that you only need to give the subpage
name when creating a link.</p>
<p>Let’s assume that you want to include many links to issues at the Sphinx
tracker, at <tt class="samp docutils literal"><span class="pre">http://bitbucket.org/birkenfeld/sphinx/issue/</span><em><span class="pre">num</span></em></tt>. Typing
this URL again and again is tedious, so you can use <a class="reference internal" href="#module-sphinx.ext.extlinks" title="sphinx.ext.extlinks: Allow inserting external links with common base URLs easily."><tt class="xref py py-mod docutils literal"><span class="pre">extlinks</span></tt></a>
to avoid repeating yourself.</p>
<p>The extension adds one new config value:</p>
<dl class="confval">
<dt id="confval-extlinks">
<tt class="descname">extlinks</tt><a class="headerlink" href="#confval-extlinks" title="Permalink to this definition">¶</a></dt>
<dd><p>This config value must be a dictionary of external sites, mapping unique
short alias names to a base URL and a <em>prefix</em>. For example, to create an
alias for the above mentioned issues, you would add</p>
<div class="highlight-python"><pre>extlinks = {'issue': ('https://bitbucket.org/birkenfeld/sphinx/issue/%s',
'issue ')}</pre>
</div>
<p>Now, you can use the alias name as a new role, e.g. <tt class="docutils literal"><span class="pre">:issue:`123`</span></tt>. This
then inserts a link to <a class="reference external" href="https://bitbucket.org/birkenfeld/sphinx/issue/123">https://bitbucket.org/birkenfeld/sphinx/issue/123</a>.
As you can see, the target given in the role is substituted in the base URL
in the place of <tt class="docutils literal"><span class="pre">%s</span></tt>.</p>
<p>The link <em>caption</em> depends on the second item in the tuple, the <em>prefix</em>:</p>
<ul class="simple">
<li>If the prefix is <tt class="docutils literal"><span class="pre">None</span></tt>, the link caption is the full URL.</li>
<li>If the prefix is the empty string, the link caption is the partial URL
given in the role content (<tt class="docutils literal"><span class="pre">123</span></tt> in this case.)</li>
<li>If the prefix is a non-empty string, the link caption is the partial URL,
prepended by the prefix – in the above example, the link caption would be
<tt class="docutils literal"><span class="pre">issue</span> <span class="pre">123</span></tt>.</li>
</ul>
<p>You can also use the usual “explicit title” syntax supported by other roles
that generate links, i.e. <tt class="docutils literal"><span class="pre">:issue:`this</span> <span class="pre">issue</span> <span class="pre"><123>`</span></tt>. In this case, the
<em>prefix</em> is not relevant.</p>
</dd></dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Since links are generated from the role in the reading stage, they appear as
ordinary links to e.g. the <tt class="docutils literal"><span class="pre">linkcheck</span></tt> builder.</p>
</div>
</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="viewcode.html" title="sphinx.ext.viewcode – Add links to highlighted source code"
>next</a> |</li>
<li class="right" >
<a href="todo.html" title="sphinx.ext.todo – Support for todo items"
>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
>
104
