Bug#901307: sphinx-gallery: please make the build mostly reproducible

[Chris Lamb]

Hi Sandro,

>> Friendly ping on this?
>
> this was supposed to be fixed when i uploaded that version. Anyhow,
> i've just uploaded 0.10.0 to unstable, can you check that version
> out?

There are a large number of distinct issues here which will require
different solutions, not all of them involving upstream.


## 1. Memory usage

sphinx-gallery includes memory usage in generated documentation. This
can be quite easily fixed with the following patch, which is likely
very amenable to upstream given that it's merely an extension of
varying the configuration based on the presence of SOURCE_DATE_EPOCH:

    --- sphinx-gallery-0.8.2.orig/doc/conf.py
    +++ sphinx-gallery-0.8.2/doc/conf.py
    @@ -335,8 +335,10 @@ try:
     except ImportError:
         pass

    +show_memory = True
     min_reported_time = 0
     if 'SOURCE_DATE_EPOCH' in os.environ:
    +    show_memory = False
         min_reported_time = sys.maxint if sys.version_info[0] == 2 else sys.maxsize

     sphinx_gallery_conf = {
    @@ -362,7 +364,7 @@ sphinx_gallery_conf = {
                    'notebooks_dir': 'notebooks',
                    'use_jupyter_lab': True,
                    },
    -    'show_memory': True,
    +    'show_memory': show_memory,
         'junit': os.path.join('sphinx-gallery', 'junit-results.xml'),
         # capture raw HTML or, if not present, __repr__ of last expression in
         # each code block


##. 2. Execution times

Secondly, there are several instances of "total execution time for
<filename>" being included in the output. I'm not quite sure how to
fix this as simply doing something like:

    --- sphinx-gallery-0.8.2.orig/sphinx_gallery/gen_gallery.py
    +++ sphinx-gallery-0.8.2/sphinx_gallery/gen_gallery.py
    @@ -538,6 +538,9 @@ def write_computation_times(gallery_conf
         with codecs.open(os.path.join(target_dir, 'sg_execution_times.rst'), 'w',
                          encoding='utf-8') as fid:
             fid.write(SPHX_GLR_COMP_TIMES.format(new_ref))
    +        if 'SOURCE_DATE_EPOCH' in os.environ:
    +            fid.write('Not included.');
    +            return
             fid.write('**{0}** total execution time for **{1}** files:\n\n'
                       .format(_sec_to_readable(total_time), target_dir_clean))
             lines, lens = _format_for_writing(costs, target_dir_clean)

... results in a kinda weird "sg_execution_times" manual page with no
content and is linked to elsewhere in the documentation. Not sure how
to either a) do a conditional paragraph in Sphinx documentation or,
preferably, b) what to include in this 'null' page beyond a more
verbose version of "Not included."


### 3. sys.argv included in example

Literal contents of sys.argv included in example which then ends up in
the documentation. This therefore includes the full build path.

    --- sphinx-gallery-0.8.2.orig/examples/plot_7_sys_argv.py
    +++ sphinx-gallery-0.8.2/examples/plot_7_sys_argv.py
    @@ -13,10 +13,11 @@ This behavior can be changed by using th
     """

     import argparse
    +import os
     import sys

     parser = argparse.ArgumentParser(description='Toy parser')
     parser.add_argument('--option', default='default',
                         help='a dummy optional argument')
    -print('sys.argv:', sys.argv)
    +print('sys.argv:', [x.replace(os.path.dirname(os.getcwd()), "/path/to") for x in sys.argv])
     print('parsed args:', parser.parse_args())


### 4. Package contains Python bytecode (.pyc)

This probably shouldn't be happening from a Debian packaging PoV:

  /usr/share/doc/python-sphinx-gallery-doc/examples/__pycache__/local_module.cpython-39.pyc


### 5. junit-results.xml includes timing info

This file includes timing info:

  /usr/share/doc/python-sphinx-gallery-doc/html/sphinx-gallery/junit-results.xml

The value of distributing this file seems negligible (if not zero), so
it's likely this can simply be dropped from the package.


### 6. Memory references in MathJax output

eg. "[<Line3D object at 0xabcdef00]"

    --- sphinx-gallery-0.8.2.orig/examples/plot_3_capture_repr.py
    +++ sphinx-gallery-0.8.2/examples/plot_3_capture_repr.py
    @@ -86,7 +86,7 @@ statsmodels.iolib.table.SimpleTable(np.z

     import matplotlib.pyplot as plt

    -plt.plot([1,2,3])
    +[type(x) for x in plt.plot([1,2,3])]

     #%%
     # To avoid capturing the text representation, you can assign the last Matplotlib


Okay, need to do work on something else for a bit, and that's probably
enough for now...


Regards,

-- 
      ,''`.
     : :'  :     Chris Lamb
     `. `'`      lamby at debian.org 🍥 chris-lamb.co.uk
       `-