python-sphinxcontrib.issuetracker 0.8-1 / usr / share / doc / python-sphinxcontrib.issuetracker / html / index.html

This file is indexed.

/usr/share/doc/python-sphinxcontrib.issuetracker/html/index.html is in python-sphinxcontrib.issuetracker 0.8-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
<!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>sphinxcontrib.issuetracker – Reference issues in issue trackers &mdash; sphinxcontrib-issuetracker v0.8 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/issuetracker.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.8',
        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="top" title="sphinxcontrib-issuetracker v0.8 documentation" href="#" />
    <link rel="next" title="Changelog" href="changes.html" /> 
  </head>
  <body>
    <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="changes.html" title="Changelog"
             accesskey="N">next</a> |</li>
        <li><a href="#">sphinxcontrib-issuetracker v0.8 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="module-sphinxcontrib.issuetracker">
<span id="sphinxcontrib-issuetracker-reference-issues-in-issue-trackers"></span><h1><a class="reference internal" href="#module-sphinxcontrib.issuetracker" title="sphinxcontrib.issuetracker: Parse issue references and link to the corresponding issues"><tt class="xref py py-mod docutils literal"><span class="pre">sphinxcontrib.issuetracker</span></tt></a> &#8211; Reference issues in issue trackers<a class="headerlink" href="#module-sphinxcontrib.issuetracker" title="Permalink to this headline"></a></h1>
<p>A <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> extension to turn textual issue ids like <tt class="docutils literal"><span class="pre">#10</span></tt> into real references
to these issues in an issue tracker.</p>
<p>The extension is available under the terms of the BSD license.</p>
<div class="section" id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline"></a></h2>
<p>This extension needs Sphinx 1.0 and Python 2.6 or newer.  Python 3 is not (yet)
supported.</p>
<p>Use <tt class="docutils literal"><span class="pre">pip</span></tt> to install this extension straight from the Python Package Index:</p>
<div class="highlight-python"><pre>pip install sphinx-contrib.issuetracker</pre>
</div>
</div>
<div class="section" id="operation">
<h2>Operation<a class="headerlink" href="#operation" title="Permalink to this headline"></a></h2>
<p>After configuring the <a class="reference internal" href="#confval-issuetracker"><tt class="xref std std-confval docutils literal"><span class="pre">tracker</span></tt></a> and the
<a class="reference internal" href="#confval-issuetracker_project"><tt class="xref std std-confval docutils literal"><span class="pre">project</span></tt></a>, this extension parses issue ids in
all documents and turns the issue id into a reference to the issue.  Issues are
searched in the configured tracker, issue ids which do not exist are ignored.
Issue ids in <tt class="docutils literal"><span class="pre">inline</span> <span class="pre">literals</span></tt> or literal blocks are also ignored to not
spoil code examples.</p>
<p>The extension queries the tracker for information about each issue.  This
information is used to mark closed issues.  Such issues are automatically
struck through in HTML output.</p>
</div>
<div class="section" id="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline"></a></h2>
<p>Add <tt class="docutils literal"><span class="pre">sphinxcontrib.issuetracker</span></tt> to the configuration value
<a class="reference external" href="http://sphinx.pocoo.org/config.html#confval-extensions" title="(in Sphinx v1.0.7)"><tt class="xref std std-confval docutils literal"><span class="pre">extensions</span></tt></a> to enable this extensions and configure the extension:</p>
<dl class="confval">
<dt id="confval-issuetracker">
<tt class="descname">issuetracker</tt><a class="headerlink" href="#confval-issuetracker" title="Permalink to this definition"></a></dt>
<dd><p>The issuetracker to use.  As of now, the following trackers are
supported:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">github</span></tt>: The issue tracker of <a class="reference external" href="https://github.com">https://github.com</a>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">bitbucket</span></tt>: The issue tracker of <a class="reference external" href="https://bitbucket.org">https://bitbucket.org</a>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">launchpad</span></tt>: The issue tracker of <a class="reference external" href="https://launchpad.net">https://launchpad.net</a>.  To use this
issue tracker, <a class="reference external" href="http://pypi.python.org/pypi/launchpadlib/">launchpadlib</a> must be installed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">google</span> <span class="pre">code</span></tt>: The issue tracker of <a class="reference external" href="http://code.google.com">http://code.google.com</a>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">debian</span></tt>: The Debian issue tracker at <a class="reference external" href="http://bugs.debian.org">http://bugs.debian.org</a>.  To use
this issue tracker, <a class="reference external" href="http://pypi.python.org/pypi/python-debianbts/">debianbts</a> and <a class="reference external" href="http://pypi.python.org/pypi/SOAPpy/">SOAPpy</a> must be installed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">jira</span></tt>: A <a class="reference external" href="http://www.atlassian.com/software/jira/">Jira</a> instance.  With this issue tracker
<a class="reference internal" href="#confval-issuetracker_url"><tt class="xref std std-confval docutils literal"><span class="pre">issuetracker_url</span></tt></a> must be set to the base url of the Jira
instance to use.  Otherwise a <a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.ValueError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a> is raised when
resolving the first issue reference.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.8.</span></p>
</li>
</ul>
</dd></dl>

<dl class="confval">
<dt id="confval-issuetracker_project">
<tt class="descname">issuetracker_project</tt><a class="headerlink" href="#confval-issuetracker_project" title="Permalink to this definition"></a></dt>
<dd><p>The project inside the issue tracker or the project, to which the issue
tracker belongs.  Defaults to the value of <a class="reference external" href="http://sphinx.pocoo.org/config.html#confval-project" title="(in Sphinx v1.0.7)"><tt class="xref std std-confval docutils literal"><span class="pre">project</span></tt></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In case of BitBucket and GitHub, the project name must include the name
of the user or organization, the project belongs to.  For instance, the
project name of <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> itself is not just <tt class="docutils literal"><span class="pre">sphinx</span></tt>, but
<tt class="docutils literal"><span class="pre">birkenfeld/sphinx</span></tt> instead.  If the user name is missing, a
<a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.ValueError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a> will be raised when an issue is to be
resolved the first time.</p>
</div>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.8: </span>Project names must include the user name now.</p>
</dd></dl>

<dl class="confval">
<dt id="confval-issuetracker_url">
<tt class="descname">issuetracker_url</tt><a class="headerlink" href="#confval-issuetracker_url" title="Permalink to this definition"></a></dt>
<dd><p>The base url of the issue tracker:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">issuetracker</span> <span class="o">=</span> <span class="s">&#39;jira&#39;</span>
<span class="n">issuetracker_url</span> <span class="o">=</span> <span class="s">&#39;https://studio.atlassian.com&#39;</span>
</pre></div>
</div>
<p>Required by all issue trackers which do not only have a single instance, but
many different instances on many different sites.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.8.</span></p>
</dd></dl>

<p>For instance, with the following configuration issue references in the
documentation would refer to the <a class="reference external" href="https://bitbucket.org/birkenfeld/sphinx/issues/">Sphinx issue tracker</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">issuetracker</span> <span class="o">=</span> <span class="s">&#39;bitbucket&#39;</span>
<span class="n">issuetracker_project</span> <span class="o">=</span> <span class="s">&#39;birkenfeld/sphinx&#39;</span>
</pre></div>
</div>
<p>By default the extension looks for issue references starting with a single
dash, like <tt class="docutils literal"><span class="pre">#10</span></tt>.  You can however change the pattern, which is used to
find issue references:</p>
<dl class="confval">
<dt id="confval-issuetracker_issue_pattern">
<tt class="descname">issuetracker_issue_pattern</tt><a class="headerlink" href="#confval-issuetracker_issue_pattern" title="Permalink to this definition"></a></dt>
<dd><p>A regular expression, which is used to find and parse issue references.
Defaults to <tt class="docutils literal"><span class="pre">r'#(\d+)'</span></tt>.  If changed to <tt class="docutils literal"><span class="pre">r'gh-(\d+)'</span></tt> for instance,
this extension would not longer recognize references like <tt class="docutils literal"><span class="pre">#10</span></tt>, but
instead parse references like <tt class="docutils literal"><span class="pre">gh-10</span></tt>.  The pattern must contain only a
single group, which matches the issue id.</p>
</dd></dl>

<p>Normally the issue id as found in the text will be used as reference text.
However, you can also use the title of the issue as issue text:</p>
<dl class="confval">
<dt id="confval-issuetracker_expandtitle">
<tt class="descname">issuetracker_expandtitle</tt><a class="headerlink" href="#confval-issuetracker_expandtitle" title="Permalink to this definition"></a></dt>
<dd><p>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, use the issue title instead of the issue id as reference text.
If an issue has no title, the issue id is used instead, just like if this
configuration key was <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p>
<p>Defaults to <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.8.</span></p>
</dd></dl>

</div>
<div class="section" id="customization">
<h2>Customization<a class="headerlink" href="#customization" title="Permalink to this headline"></a></h2>
<p>If you use an issue tracker that is not supported by this extension, then set
<a class="reference internal" href="#confval-issuetracker"><tt class="xref std std-confval docutils literal"><span class="pre">issuetracker</span></tt></a> to <tt class="xref docutils literal"><span class="pre">None</span></tt> or leave it unset, and connect your own
callback to the event <a class="reference internal" href="#event-issuetracker-resolve-issue"><tt class="xref std std-event docutils literal"><span class="pre">issuetracker-resolve-issue</span></tt></a>:</p>
<dl class="event">
<dt id="event-issuetracker-resolve-issue">
<tt class="descname">issuetracker-resolve-issue</tt><big>(</big><em>app</em>, <em>tracker_config</em>, <em>issue_id</em><big>)</big><a class="headerlink" href="#event-issuetracker-resolve-issue" title="Permalink to this definition"></a></dt>
<dd><p>Emitted if a issue reference is to be resolved.</p>
<p><tt class="docutils literal"><span class="pre">app</span></tt> is the Sphinx application object.  <tt class="docutils literal"><span class="pre">tracker_config</span></tt> is the
issuetracker configuration as <a class="reference internal" href="#sphinxcontrib.issuetracker.TrackerConfig" title="sphinxcontrib.issuetracker.TrackerConfig"><tt class="xref py py-class docutils literal"><span class="pre">TrackerConfig</span></tt></a> object.  <tt class="docutils literal"><span class="pre">issue_id</span></tt>
is the issue id as string.</p>
<p>A callback should return an <a class="reference internal" href="#sphinxcontrib.issuetracker.Issue" title="sphinxcontrib.issuetracker.Issue"><tt class="xref py py-class docutils literal"><span class="pre">Issue</span></tt></a> object containing the resolved
issue, or <tt class="xref docutils literal"><span class="pre">None</span></tt> if it could not resolve the issue.  In the latter case
other resolvers connected to the event may be invoked by Sphinx.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 0.8: </span>Replaced <tt class="docutils literal"><span class="pre">project</span></tt> argument with <tt class="docutils literal"><span class="pre">tracker_config</span></tt>, changed return
value from dictionary to <a class="reference internal" href="#sphinxcontrib.issuetracker.Issue" title="sphinxcontrib.issuetracker.Issue"><tt class="xref py py-class docutils literal"><span class="pre">Issue</span></tt></a></p>
</dd></dl>

<dl class="class">
<dt id="sphinxcontrib.issuetracker.TrackerConfig">
<em class="property">class </em><tt class="descclassname">sphinxcontrib.issuetracker.</tt><tt class="descname">TrackerConfig</tt><a class="headerlink" href="#sphinxcontrib.issuetracker.TrackerConfig" title="Permalink to this definition"></a></dt>
<dd><p>Issue tracker configuration.</p>
<p>This class provides configuration for trackers, and is passed as
<tt class="docutils literal"><span class="pre">tracker_config</span></tt> arguments to callbacks of
<a class="reference internal" href="#event-issuetracker-resolve-issue"><tt class="xref std std-event docutils literal"><span class="pre">issuetracker-resolve-issue</span></tt></a>.</p>
<dl class="attribute">
<dt id="sphinxcontrib.issuetracker.TrackerConfig.project">
<tt class="descname">project</tt><a class="headerlink" href="#sphinxcontrib.issuetracker.TrackerConfig.project" title="Permalink to this definition"></a></dt>
<dd><p>The project name as string</p>
</dd></dl>

<dl class="attribute">
<dt id="sphinxcontrib.issuetracker.TrackerConfig.url">
<tt class="descname">url</tt><a class="headerlink" href="#sphinxcontrib.issuetracker.TrackerConfig.url" title="Permalink to this definition"></a></dt>
<dd><p>The url of the issue tracker as string <em>without</em> any trailing slash, or
<tt class="xref docutils literal"><span class="pre">None</span></tt>, if there is no url configured for this tracker.  See
<a class="reference internal" href="#confval-issuetracker_url"><tt class="xref std std-confval docutils literal"><span class="pre">issuetracker_url</span></tt></a>.</p>
</dd></dl>

<p class="versionadded">
<span class="versionmodified">New in version 0.8.</span></p>
</dd></dl>

<dl class="class">
<dt id="sphinxcontrib.issuetracker.Issue">
<em class="property">class </em><tt class="descclassname">sphinxcontrib.issuetracker.</tt><tt class="descname">Issue</tt><a class="headerlink" href="#sphinxcontrib.issuetracker.Issue" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference external" href="http://docs.python.org/library/collections.html#collections.namedtuple" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">namedtuple()</span></tt></a> providing issue information.</p>
<dl class="attribute">
<dt id="sphinxcontrib.issuetracker.Issue.id">
<tt class="descname">id</tt><a class="headerlink" href="#sphinxcontrib.issuetracker.Issue.id" title="Permalink to this definition"></a></dt>
<dd><p>The issue id as string</p>
<p>If you are writing your own custom callback for
<a class="reference internal" href="#event-issuetracker-resolve-issue"><tt class="xref std std-event docutils literal"><span class="pre">issuetracker-resolve-issue</span></tt></a>, set this attribute to the
<tt class="docutils literal"><span class="pre">issue_id</span></tt> that was given as argument.</p>
</dd></dl>

<dl class="attribute">
<dt id="sphinxcontrib.issuetracker.Issue.url">
<tt class="descname">url</tt><a class="headerlink" href="#sphinxcontrib.issuetracker.Issue.url" title="Permalink to this definition"></a></dt>
<dd><p>An URL providing information about this issue.</p>
<p>This URL is used as hyperlink target in the generated documentation.
Thus it should point to a webpage or something similar that provides
human-readable information about an issue.</p>
</dd></dl>

<dl class="attribute">
<dt id="sphinxcontrib.issuetracker.Issue.closed">
<tt class="descname">closed</tt><a class="headerlink" href="#sphinxcontrib.issuetracker.Issue.closed" title="Permalink to this definition"></a></dt>
<dd><p><tt class="xref docutils literal"><span class="pre">True</span></tt>, if the issue is closed, <tt class="xref docutils literal"><span class="pre">False</span></tt> otherwise.</p>
</dd></dl>

<p class="versionadded">
<span class="versionmodified">New in version 0.8.</span></p>
</dd></dl>

</div>
<div class="section" id="contribution-and-development">
<h2>Contribution and Development<a class="headerlink" href="#contribution-and-development" title="Permalink to this headline"></a></h2>
<p>Please report bugs and missing functionality (e.g. a tracker not being
supported) to the <a class="reference external" href="https://bitbucket.org/birkenfeld/sphinx-contrib/issues/">issue tracker</a>.</p>
<p>The source code of this extension is available in the <a class="reference external" href="https://bitbucket.org/birkenfeld/sphinx-contrib">sphinx-contrib</a>
repository.  Feel free to clone this repository and add your changes to this
extension.  Patches and pull requests are always welcome!</p>
<div class="toctree-wrapper compound">
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="#">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#"><tt class="docutils literal"><span class="pre">sphinxcontrib.issuetracker</span></tt> &#8211; Reference issues in issue trackers</a><ul>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#operation">Operation</a></li>
<li><a class="reference internal" href="#configuration">Configuration</a></li>
<li><a class="reference internal" href="#customization">Customization</a></li>
<li><a class="reference internal" href="#contribution-and-development">Contribution and Development</a><ul>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Next topic</h4>
  <p class="topless"><a href="changes.html"
                        title="next chapter">Changelog</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/index.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" size="18" />
      <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="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="changes.html" title="Changelog"
             >next</a> |</li>
        <li><a href="#">sphinxcontrib-issuetracker v0.8 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2010, 2011, Sebastian Wiesner.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
    </div>
  </body>
</html>

APT Browse - Built by Thomas Orozco.