[Reproducible-builds] Bug#833820: sphinx: Avoid evaulating default function arguments when including them in the documentation

[Petter Reinholdtsen]

Source: sphinx
Version: 1.3.6-2
Severity: wishlist
User: reproducible-builds at lists.alioth.debian.org
Usertags: toolchain
X-Debbugs-Cc: reproducible-builds at lists.alioth.debian.org

Hi.  The documentation generated by sphinx expands default python
arguments instead of reproducing the values listed in the source.  This
is related to the reproducability issues reported in
<URL: https://bugs.debian.org/795976 > and
<URL: https://bugs.debian.org/822197 >, but seem to be a different issue
from those solved there.

I discovered this from
<URL: https://tests.reproducible-builds.org/debian/rb-pkg/unstable/amd64/txtorcon.html >
which report this difference in the generated documentation
(txtorcon-state.txt):

@@ -385,15 +385,15 @@
       Returns:
          Deferred which callbacks with this Circuit instance
 
       ONLY after Tor has confirmed it is gone (not simply that the
       CLOSECIRCUIT command has been queued). This could be a while if
       you included IfUnused.
 
-   age(now=datetime.datetime(2016, 8, 5, 7, 33, 8, 845335))
+   age(now=datetime.datetime(2017, 9, 7, 13, 58, 10, 541674))
 
       Returns an integer which is the difference in seconds from 'now'
       to when this circuit was created.
 
       Returns None if there is no created-time.
 
    update(args)

This documentation is generated from this function definition in
txtorcon/circuit.py in the source:

    def age(self, now=datetime.datetime.utcnow()):
        """
        Returns an integer which is the difference in seconds from
        'now' to when this circuit was created.

        Returns None if there is no created-time.
        """

Notice how the now argument is supposed to be a dynamic function call to
datetime.datetime.utcnow(), and not a fixed timestamp as the
documentation could lead you to believe.

Please change sphinx to correctly report the arguments used by this age
function.  It would have the side effect of making the txtorcon build
reproducable.

-- 
Happy hacking
Petter Reinholdtsen