929 document reproducible builds

README.rst

@@ -36,6 +36,13 @@ You can run pydoctor on your project like this::
 
 For more info, `Read The Docs <https://pydoctor.readthedocs.io/>`_.
 
+Reproducible builds
+-------------------
+
+If you need deterministic output for packaging or reproducible releases,
+see the documentation page `Reproducible builds <docs/source/reproducible-builds.rst>`_
+for instructions on using `SOURCE_DATE_EPOCH` or the `--buildtime` option.
+
 Markup
 ~~~~~~
 

docs/source/contrib.rst

@@ -91,6 +91,15 @@ Read more about reviewing:
 - `How to be a good reviewer <https://twistedmatrix.com/trac/wiki/ReviewProcess#Howtobeagoodreviewer>`_.
 - `Leave well enough alone <https://mail.python.org/archives/list/twisted@python.org/thread/53LZTRNRYLZJ4QLEF3YPAE53CWSL6LXD/>`_.
 
+Reproducible builds
+-------------------
+
+If you want reproducible output from `pydoctor` builds (for example in
+release packaging), see the dedicated documentation page:
+
+`Reproducible builds <reproducible-builds.html>`_.
+
+
 Releasing and publishing a new package
 --------------------------------------
 

docs/source/reproducible-builds.rst

@@ -0,0 +1,52 @@
+Reproducible builds
+====================
+
+Pydoctor supports the `SOURCE_DATE_EPOCH` environment variable and a
+`--buildtime` option to allow reproducible output when building
+documentation.
+
+What SOURCE_DATE_EPOCH does
+---------------------------
+
+`SOURCE_DATE_EPOCH` is a standard used by many projects and build
+systems to make builds reproducible. It should contain an integer
+Unix timestamp (seconds since the epoch). When `SOURCE_DATE_EPOCH` is
+set in the environment before running `pydoctor`, pydoctor will use
+that time (in UTC) as the build time instead of the current time.
+
+Example:
+
+.. code-block:: bash
+
+    export SOURCE_DATE_EPOCH=1600000000
+    pydoctor --html-output=docs/api src/mylib
+
+Using the `--buildtime` option
+------------------------------
+
+If you prefer to set the build time on the command line you can use
+`--buildtime` with the format ``YYYY-mm-dd HH:MM:SS``. For example::
+
+    pydoctor --buildtime="2020-09-13 12:26:40" --html-output=docs/api src/mylib
+
+To suppress printing or embedding the build time, pass one of the
+following values to `--buildtime`: ``no``, ``false``, ``off`` or
+``0``. For example::
+
+    pydoctor --buildtime=no --html-output=docs/api src/mylib
+
+Details
+-------
+
+- The exact format accepted by `--buildtime` is ``%Y-%m-%d %H:%M:%S``.
+- When both `SOURCE_DATE_EPOCH` and `--buildtime` are provided, the
+  environment variable takes precedence (this follows common
+  conventions for reproducible build environments).
+- When a build time is set (and not suppressed), it is used in
+  templates that render the generated documentation (for example the
+  generated footer).
+
+References
+----------
+
+- `SOURCE_DATE_EPOCH specification <https://reproducible-builds.org/specs/source-date-epoch/>`_

tox.ini

@@ -49,6 +49,12 @@ commands =
     pytest -vv {posargs: pydoctor}
 
 
+[testenv:test-parallel]
+description = Run tests with multiprocessing without report
+extras =
+    test
+commands =
+    pytest -vv -n auto {posargs: pydoctor}
 
 [testenv:twisted-apidoc]
 deps =