[Python-modules-team] Bug#877895: intersphinx plugin makes packages unreproducible

[Antoine Beaupré]

On 2017-10-09 01:00:47, Dmitry Shachnev wrote:
> Hi Antoine!
>
> On Fri, Oct 06, 2017 at 08:59:55PM -0400, Antoine Beaupré wrote:
>> I believe that those docs package already do provide docs index, e.g.:
>>
>> /usr/share/doc/python-configparser/html/objects.inv
>>
>> it's just a matter of fixing sphinx to make that work then... i wonder
>> if interlinks supports file:// paths?
>
> Intersphinx supports local files (the file:// prefix is unneeded). But you
> need to explicitly point it to them.

Right.

> In your package (feed2exec), doc/conf.py currently has:
>
>   intersphinx_mapping = {
>       'click': ('http://click.pocoo.org/', None),
>       'jinja': ('http://jinja.pocoo.org/docs/', None),
>       'python': ('https://docs.python.org/3/', None),
>   }
>
> You need to patch this to point to Debian packaged paths. See codesearch [1]
> for examples on how others are doing it.
>
> [1]: https://codesearch.debian.net/search?q=html%2Fobjects%5C.inv+path%3Adebian%2Fpatches%2F.*

That's neat! Unfortunately, none of my dependencies (but stdlib) provide
-doc pacakges: click, feedparser, html2text, requests and unidecode all
come up blank.

So for now, I have removed the other entries and kept only "python", as
the other entries weren't used anyways. Furthermore, I am using the
followinc construct:

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

This allows the mapping tool to first use the local objects.inv and
*then* fallback on the network if missing, which should make builds more
reproducible... the final patch is something like this:

commit 7360de4e6be0a545bdcdd6254a232afe4521e917
Author: Antoine Beaupré <anarcat at debian.org>
Date:   Thu Oct 12 15:52:58 2017 -0400

    make build reproducible by using local doc objects
    
    see #877895

diff --git a/debian/control b/debian/control
index 28c6a16..49ca39a 100644
--- a/debian/control
+++ b/debian/control
@@ -5,6 +5,7 @@ Maintainer: Antoine Beaupré <anarcat at debian.org>
 Build-Depends: debhelper (>= 10)
              , dh-python
              , python3
+             , python3-doc
              , python3-setuptools
              , python3-setuptools-scm
              , python3-sphinx
diff --git a/doc/conf.py b/doc/conf.py
index b904779..21e01de 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -115,7 +115,6 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'click': ('http://click.pocoo.org/', None),
-    'jinja': ('http://jinja.pocoo.org/docs/', None),
-    'python': ('https://docs.python.org/3/', None),
+    'python': ('https://docs.python.org/3/',
+               ('/usr/share/doc/python3-doc/html/objects.inv', None)),
 }

now i guess i need to file bugs for all my build-deps to make sure they
ship -doc packages... sigh...

i am not sure what the next step here is. should we just document this
as a known issue with reproducible builds and teach people how to fix
this somehow?

or is there anything else needed in sphinx?

thanks!

a.

-- 
Le péché est né avant la vertu, comme le moteur avant le frein.
                         - Jean-Paul Sartre