Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make the documentation build reproducibly #3408

Merged

Conversation

@lamby
Copy link
Contributor

lamby commented Oct 28, 2019

Whilst working on the Reproducible Builds effort we noticed that flask could not be built reproducibly.

This is because it includes an absolute build directory in the documentation as the json_module attribute points to a Python class/module which has a string representation including its path.

This commit skips this (inherited) member from the documentation.

(This was originally filed in Debian as #943674.)

Whilst working on the Reproducible Builds effort [0] we noticed that
flask could not be built reproducibly.

This is because it includes an absolute build directory in the
documentation as the "json_module" attribute points to a Python class/
module which has a string representation including its path.

This commit skips this (inherited) member from the documentation.

(This was originally filed in Debian as #943674 [1].)

 [0] https://reproducible-builds.org/
 [1] https://bugs.debian.org/943674
@davidism

This comment has been minimized.

Copy link
Member

davidism commented Oct 28, 2019

You can't exclude this, it's part of the documented api.

@davidism

This comment has been minimized.

Copy link
Member

davidism commented Oct 28, 2019

If you're concerned with overall reproducibility, you should probably contribute a general fix to stabilize reprs in Sphinx.

@lamby

This comment has been minimized.

Copy link
Contributor Author

lamby commented Oct 28, 2019

You can't exclude this, it's part of the documented api.

Don't quite follow what you mean by "can't" here, but assuming you might clarify this with "should" or similar it is simply excluding this member from this internal wrapper class from the documentation - the current entry has no associated text whatsover, just the "<module /path/to/foo.pyc>' or whatever.

@davidism

This comment has been minimized.

Copy link
Member

davidism commented Oct 28, 2019

That attribute is documented in Werkzeug, so if it's not showing up in Flask that's another thing that needs to be addressed in Sphinx. May be related to sphinx-doc/sphinx#6415.

The fact that non-reproducible internals such as module paths are output by Sphinx is a more general problem with Sphinx and should be addressed there rather than in individual docs. In this case, it would make more sense for that to be a reference to the flask.json module rather than a repr.

@davidism

This comment has been minimized.

Copy link
Member

davidism commented Oct 28, 2019

It seems like even adding custom documentation doesn't get through if the attribute is aliasing a module. So I guess the best answer is to exclude it for now, and hope that linked Sphinx issue can be addressed.

@davidism davidism merged commit 1234eb0 into pallets:master Oct 28, 2019
13 checks passed
13 checks passed
Tests Build #20191028.1 succeeded
Details
Tests (Flask DocsHtml) Flask DocsHtml succeeded
Details
Tests (Flask Pypy3Linux) Flask Pypy3Linux succeeded
Details
Tests (Flask Python27Linux) Flask Python27Linux succeeded
Details
Tests (Flask Python27Windows) Flask Python27Windows succeeded
Details
Tests (Flask Python35Linux) Flask Python35Linux succeeded
Details
Tests (Flask Python36Linux) Flask Python36Linux succeeded
Details
Tests (Flask Python37Linux) Flask Python37Linux succeeded
Details
Tests (Flask Python37Mac) Flask Python37Mac succeeded
Details
Tests (Flask Python37Windows) Flask Python37Windows succeeded
Details
Tests (Flask Style) Flask Style succeeded
Details
Tests (Flask VersionRange) Flask VersionRange succeeded
Details
Tests (FlaskOnNightly) FlaskOnNightly succeeded
Details
@davidism davidism added the docs label Oct 28, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.