Source: sphinxcontrib-programoutput
Version: 0.16-1
Severity: normal
Tags: patch
User: [email protected]
Usertags: buildpath timezone username usrmerge
X-Debbugs-Cc: [email protected]
sphinxcontrib-programoutput builds non-reproducible documentation. The
documentation contains the current username, the absolute path to grep
(which can vary depending on merged-/usr status or whether a local
/usr/local/bin/grep exists), and the date on the grep executable (which
is presented differently depending on the timezone).
Additionally, a lot of the examples use `python`, which typically doesn't
exist in a build chroot, making them less useful as examples and
introducing the current build path via error messages.
The attached patch avoids these sources of non-reproducibility.
smcv
>From ef6355cb5d4e5376bdd5e24cd38198c0d83ca6ae Mon Sep 17 00:00:00 2001
From: Simon McVittie <[email protected]>
Date: Sat, 4 Sep 2021 18:36:14 +0100
Subject: [PATCH] Make the documentation build reproducibly
These patches avoid the username, the absolute path to grep and the
build path leaking into documentation and making it non-reproducible,
as well as making some examples in the documentation more useful.
---
...t-variable-less-likely-to-vary-betwe.patch | 38 +++++++
...ell-command-whose-output-is-less-lik.patch | 35 ++++++
...ython3-instead-of-python-in-examples.patch | 107 ++++++++++++++++++
debian/patches/series | 3 +
debian/rules | 4 +
5 files changed, 187 insertions(+)
create mode 100644 debian/patches/doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch
create mode 100644 debian/patches/doc-Use-an-example-shell-command-whose-output-is-less-lik.patch
create mode 100644 debian/patches/doc-Use-python3-instead-of-python-in-examples.patch
diff --git a/debian/patches/doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch b/debian/patches/doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch
new file mode 100644
index 0000000..e4515cc
--- /dev/null
+++ b/debian/patches/doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch
@@ -0,0 +1,38 @@
+From: Simon McVittie <[email protected]>
+Date: Sat, 4 Sep 2021 18:33:37 +0100
+Subject: doc: Use an environment variable less likely to vary between builds
+
+SHELL is less user-specific than USER, and can easily be forced to a
+known value for reproducible builds.
+
+Signed-off-by: Simon McVittie <[email protected]>
+---
+ doc/index.rst | 8 ++++----
+ 1 file changed, 4 insertions(+), 4 deletions(-)
+
+diff --git a/doc/index.rst b/doc/index.rst
+index 8175499..7bffe9c 100644
+--- a/doc/index.rst
++++ b/doc/index.rst
+@@ -114,17 +114,17 @@ Normally the command is splitted according to the POSIX shell syntax (see
+ :py:mod:`shlex`), and executed directly. Thus special shell features like
+ expansion of environment variables will not work::
+
+- .. command-output:: echo "$USER"
++ .. command-output:: echo "$SHELL"
+
+-.. command-output:: echo "$USER"
++.. command-output:: echo "$SHELL"
+
+ To enable these features, enable the ``shell`` option. With this option, the
+ command is literally passed to the system shell::
+
+- .. command-output:: echo "$USER"
++ .. command-output:: echo "$SHELL"
+ :shell:
+
+-.. command-output:: echo "$USER"
++.. command-output:: echo "$SHELL"
+ :shell:
+
+ Other shell features like process expansion consequently work, too::
diff --git a/debian/patches/doc-Use-an-example-shell-command-whose-output-is-less-lik.patch b/debian/patches/doc-Use-an-example-shell-command-whose-output-is-less-lik.patch
new file mode 100644
index 0000000..9cef3e7
--- /dev/null
+++ b/debian/patches/doc-Use-an-example-shell-command-whose-output-is-less-lik.patch
@@ -0,0 +1,35 @@
+From: Simon McVittie <[email protected]>
+Date: Sat, 4 Sep 2021 18:29:53 +0100
+Subject: doc: Use an example shell command whose output is less likely to
+ vary
+
+The path returned by $(which grep) might change depending on whether
+the system is merged-/usr or whether it has a local /usr/local/bin/grep,
+and the result of running ls can depend on factors such as the time zone.
+
+Using a different command here also helps to illustrate that shell
+syntax such as "&&" is accepted here, and using "command -v" avoids
+deprecation warnings from debianutils which(1).
+
+Signed-off-by: Simon McVittie <[email protected]>
+---
+ doc/index.rst | 4 ++--
+ 1 file changed, 2 insertions(+), 2 deletions(-)
+
+diff --git a/doc/index.rst b/doc/index.rst
+index 6b5a0cc..8175499 100644
+--- a/doc/index.rst
++++ b/doc/index.rst
+@@ -129,10 +129,10 @@ command is literally passed to the system shell::
+
+ Other shell features like process expansion consequently work, too::
+
+- .. command-output:: ls -l $(which grep)
++ .. command-output:: test -x $(command -v grep) && echo yes
+ :shell:
+
+-.. command-output:: ls -l $(which grep)
++.. command-output:: test -x $(command -v grep) && echo yes
+ :shell:
+
+ Remember to use ``shell`` carefully to avoid unintented interpretation of shell
diff --git a/debian/patches/doc-Use-python3-instead-of-python-in-examples.patch b/debian/patches/doc-Use-python3-instead-of-python-in-examples.patch
new file mode 100644
index 0000000..d28f70b
--- /dev/null
+++ b/debian/patches/doc-Use-python3-instead-of-python-in-examples.patch
@@ -0,0 +1,107 @@
+From: Simon McVittie <[email protected]>
+Date: Sat, 4 Sep 2021 18:21:58 +0100
+Subject: doc: Use python3 instead of python in examples
+
+This makes the examples more illustrative, by running a command that
+actually exists. It also avoids embedding the full path to the build
+directory in the generated documentation, which is bad for reproducible
+builds.
+
+Signed-off-by: Simon McVittie <[email protected]>
+---
+ doc/index.rst | 26 +++++++++++++-------------
+ 1 file changed, 13 insertions(+), 13 deletions(-)
+
+diff --git a/doc/index.rst b/doc/index.rst
+index 8710bbe..6b5a0cc 100644
+--- a/doc/index.rst
++++ b/doc/index.rst
+@@ -35,13 +35,13 @@ Usage
+ To include the output of a command into your document, use the
+ :dir:`program-output` directive provided by this extension::
+
+- .. program-output:: python -V
++ .. program-output:: python3 -V
+
+-The whole output of ``python -V``, including any messages on standard error, is
++The whole output of ``python3 -V``, including any messages on standard error, is
+ inserted into the current document, formatted as literal text without any
+ syntax highlighting:
+
+-.. program-output:: python -V
++.. program-output:: python3 -V
+
+ You can omit the content of the standard error stream with the ``nostderr``
+ option.
+@@ -61,12 +61,12 @@ single ellipsis ``...`` is inserted.
+
+ If used with a single number, all lines after the specified line are omitted::
+
+- .. program-output:: python --help
++ .. program-output:: python3 --help
+ :ellipsis: 2
+
+ The above omits all lines after the second one:
+
+-.. program-output:: python --help
++.. program-output:: python3 --help
+ :ellipsis: 2
+
+ Negative numbers count from the last line backwards, thus replacing ``2`` with
+@@ -76,12 +76,12 @@ If used with two comma-separated line numbers, all lines in between the
+ specified lines are omitted. Again, a negative number counts from the last
+ line backwards::
+
+- .. program-output:: python --help
++ .. program-output:: python3 --help
+ :ellipsis: 2,-2
+
+ The above omits all lines except the first two and the last two lines:
+
+-.. program-output:: python --help
++.. program-output:: python3 --help
+ :ellipsis: 2,-2
+
+
+@@ -91,19 +91,19 @@ Mimicing shell input
+ You can mimic shell input with the :dir:`command-output` directive [#alias]_.
+ This directive inserts the command along with its output into the document::
+
+- .. command-output:: python -V
++ .. command-output:: python3 -V
+
+-.. command-output:: python -V
++.. command-output:: python3 -V
+
+ The appearance of this output can be configured with
+ :confval:`programoutput_prompt_template`. When used in conjunction with
+ ``ellipsis``, the command itself and any additional text is *never* omitted.
+ ``ellipsis`` always refers to the *immediate output* of the command::
+
+- .. command-output:: python --help
++ .. command-output:: python3 --help
+ :ellipsis: 2
+
+-.. command-output:: python --help
++.. command-output:: python3 --help
+ :ellipsis: 2
+
+
+@@ -150,7 +150,7 @@ indicate an error. In some cases however, it may be reasonable to demonstrate
+ failed programs. To avoid a (superfluous) warning in such a case, you can
+ specify the expected return code of a command with the ``returncode`` option::
+
+- .. command-output:: python -c 'import sys; sys.exit(1)'
++ .. command-output:: python3 -c 'import sys; sys.exit(1)'
+ :returncode: 1
+
+ The above command returns the exit code 1 (as given to :py:func:`sys.exit()`),
+@@ -235,7 +235,7 @@ This extension understands the following configuration options:
+ :dir:`command-output`. Defaults to ``$ {command}\n{output}`` which renders
+ as follows:
+
+- .. command-output:: python -V
++ .. command-output:: python3 -V
+
+ The following keys are provided to the format string:
+
diff --git a/debian/patches/series b/debian/patches/series
index 338f448..1c85ee6 100644
--- a/debian/patches/series
+++ b/debian/patches/series
@@ -1,3 +1,6 @@
remove-failing-tests-when-LANG-equal-C.patch
+doc-Use-python3-instead-of-python-in-examples.patch
+doc-Use-an-example-shell-command-whose-output-is-less-lik.patch
+doc-Use-an-environment-variable-less-likely-to-vary-betwe.patch
#fix-tests-for-sphinx-1.8.patch
#use-py3-in-tests.patch
diff --git a/debian/rules b/debian/rules
index df341b6..9173080 100755
--- a/debian/rules
+++ b/debian/rules
@@ -3,6 +3,10 @@
UPSTREAM_GIT := https://github.com/NextThought/sphinxcontrib-programoutput
include /usr/share/openstack-pkg-tools/pkgos.make
+# Used in an example in generated documentation. Force it to a known value
+# to get reproducible builds
+export SHELL = /bin/sh
+
%:
dh $@ --buildsystem=python_distutils --with python3,sphinxdoc
--
2.33.0
