Differences between revisions 6 and 7
Revision 6 as of 2015-01-28 02:54:43
Size: 497
Editor: lamby
Comment:
Revision 7 as of 2017-10-12 20:02:11
Size: 1526
Editor: TheAnarcat
Comment: document the intersphinx mapping issue
Deletions are marked like this. Additions are marked like this.
Line 7: Line 7:
 * linking against remote documentation repositories with the intersphinx module
Line 14: Line 15:
Example diff with and without network access:

{{{
-<li><strong>to_addr</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.6)"><em>str</em></a>) – the email to use as “to” (defaults to
+<li><strong>to_addr</strong> (<em>str</em>) – the email to use as “to” (defaults to
}}}
Line 16: Line 24:
Patch submitted as Bug:776443. For unsorted stuff, patch submitted as Bug:776443.

For the external links, see Bug:877895 for the full discussion.

Workaround: use the "multiple target" feature introduced in Sphinx 1.3 in the [[http://www.sphinx-doc.org/en/stable/ext/intersphinx.html#confval-intersphinx_mapping|intersphinx_mapping]] configuration, like such:

{{{
intersphinx_mapping = {
    'python': ('https://docs.python.org/3/',
               ('/usr/share/doc/python3-doc/html/objects.inv', None)),
}
}}}

Make sure you add the right `build-dep` for the docs packages referenced (in the above case, DebianPackage:python3-doc.

python-sphinx creates unreproducible documentation by:

  • embedding object memory addresses,
  • producing unsorted files:
    • searchindex.js
    • objects.inv
  • linking against remote documentation repositories with the intersphinx module

Known affected packages

Detection

Example debbindiff output with memory references and an unsorted index file

Example diff with and without network access:

-<li><strong>to_addr</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.6)"><em>str</em></a>) – the email to use as “to” (defaults to
+<li><strong>to_addr</strong> (<em>str</em>) – the email to use as “to” (defaults to

Solution

For unsorted stuff, patch submitted as 776443.

For the external links, see 877895 for the full discussion.

Workaround: use the "multiple target" feature introduced in Sphinx 1.3 in the intersphinx_mapping configuration, like such:

intersphinx_mapping = {
    'python': ('https://docs.python.org/3/',
               ('/usr/share/doc/python3-doc/html/objects.inv', None)),
}

Make sure you add the right build-dep for the docs packages referenced (in the above case, python3-doc.