DebianPts: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
 * generating unsorted section IDs and anchors in texinfo output (affects info pages)
   * PDF output generated by Sphinx is similarly unreproducible.


[[https://reproducible.debian.net/issues/randomness_in_documentation_generated_by_sphinx_issue.html|Known affected packages]]

= Detection =

[[attachment:kombu_3.0.21-2.debbindiff.html|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 Bug:776443.

For info pages, patch forwarded upstream in Bug:907352 (not yet applied in Debian).

For PDFs, TODO: info page bug may contain a hint for a solution.

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.