Differences between revisions 4 and 8 (spanning 4 versions)
Revision 4 as of 2015-01-26 18:18:29
Size: 722
Editor: ?ReinerHerrmann
Comment: fixed link to affected packages
Revision 8 as of 2018-08-28 01:23:42
Size: 1836
Comment: document info page and PDF unreproducibility and link to bug
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
 * writing object memory references,
 * writing an unsorted index file in json format,
 * 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.
Line 12: Line 18:
= Work in Progress = Example diff with and without network access:
Line 14: Line 20:
An initial patch for the Sphinx issue is attached to this Wiki page.
It will produce sorted searchindex.js and objects.inv files.

A solution for the embedded memory addresses is still missing.
{{{
-<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 21: Line 27:
None yet. For unsorted stuff, patch submitted as Bug:776443.
Line 23: Line 29:
= Patch =
[[attachment:sphinx.diff]]
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.

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.

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 info pages, patch forwarded upstream in 907352 (not yet applied in Debian).

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

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.