[Python-modules-team] Bug#877637: python3-sphinx: Unreproducible (html) output using py3/ext.autodoc/dict attributes

[Stephan Suerken]

Package: python3-sphinx
Version: 1.6.4-1
Severity: normal

Dear Maintainer,

in python3, PYTHONHASHSEED's default value has become "random" at some
point. It seems this make projects using ext.autodoc prone to generate
unreproducible documentation (order the dicts are iterated vary).

   * What led up to the situation?
   * What exactly did you do (or not do) that was effective (or
     ineffective)?

sphinx documentation with 'ext.autodoc' extension enabled and, in code,
classes having attributes like so:

---
class X(object):
        Y = {"a": "aah",
             "b": "beh",
             "c": "zeh",
             "d": "deh"}
---

   * What was the outcome of this action?

Randomly different HTML output.

   * What outcome did you expect instead?

The very same HTML output.

Please see the little script attached, which produces a minimal
setup with this behaviour.

PYTHONHASHSEED=0 set explicitly works around the problem.

Is this a known problem, or even unfixable? If so, is there a commonly
accepted workaround (I humbly searched but found little
on the subject)?

Thx!

S

-- System Information:
Debian Release: buster/sid
  APT prefers unstable
  APT policy: (500, 'unstable'), (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.12.0-0.bpo.2-amd64 (SMP w/4 CPU cores)
Locale: LANG=de_DE.UTF-8, LC_CTYPE=de_DE.UTF-8 (charmap=UTF-8), LANGUAGE=de_DE.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: sysvinit (via /sbin/init)

Versions of packages python3-sphinx depends on:
ii  python3            3.5.3-3
ii  python3-alabaster  0.7.8-1
ii  python3-babel      2.4.0+dfsg.1-2
ii  python3-docutils   0.14+dfsg-1
ii  python3-imagesize  0.7.1-1
ii  python3-jinja2     2.9.6-1
ii  python3-pygments   2.2.0+dfsg-1
ii  python3-requests   2.18.1-1
ii  python3-six        1.11.0-1
ii  sphinx-common      1.6.4-1

Versions of packages python3-sphinx recommends:
ii  python3-pil  4.2.1-1

Versions of packages python3-sphinx suggests:
pn  dvipng                     <none>
pn  imagemagick-6.q16          <none>
pn  latexmk                    <none>
ii  libjs-mathjax              2.7.0-2
pn  python3-sphinx-rtd-theme   <none>
pn  sphinx-doc                 <none>
pn  texlive-fonts-recommended  <none>
pn  texlive-generic-extra      <none>
pn  texlive-latex-extra        <none>
pn  texlive-latex-recommended  <none>

-- no debconf information
-------------- next part --------------
#!/bin/bash -e

read -p "Generate test project in cwd??" DUMMY

mkdir -p src/
cat >src/module.py <<EOF
class X(object):
        Y = {"a": "aah",
             "b": "beh",
             "c": "zeh",
             "d": "deh"}
EOF

cat >conf.py <<EOF
extensions = ['sphinx.ext.autodoc']
autodoc_member_order = 'bysource'
EOF

cat >contents.rst <<EOF
dummy
=====
EOF

/usr/share/sphinx/scripts/python3/sphinx-apidoc --force --output-dir . ./src/

export PYTHONPATH=$(pwd)/src
#export PYTHONHASHSEED=random  # py3 default; unreproducible
#export PYTHONHASHSEED=0       # fixed seed; reproducible

for i in 1 2; do
	rm -rf _build/html html${i}/
	/usr/share/sphinx/scripts/python3/sphinx-build . _build/html/
	cp -a _build/html html${i}
done

diff -u -r -x '*.pickle' -x '.doctrees/*' html1 html2
echo "OK (same HTML output)"