Fix doc generation rendering byte literals with Python 3 #7556
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This doesn't fix the DeprecationWarning, but means we'll now generate HTML5 along with bringing other small upgrades and fixes. See release notes at http://docutils.sourceforge.net/RELEASE-NOTES.html.
Use our preferred .format() style, invert conditionals for early return, and improve spacing.
jsirois
approved these changes
Apr 14, 2019
stuhood
pushed a commit
that referenced
this pull request
Apr 15, 2019
### Problem When running `./pants markdown src::` or `./build-support/bin/publish_docs.sh -o` with Python 3, the top of the generated page would have `b'\n\n\n\n` included at the top. Will close #7546. ### Solution In `markdown_to_html.py`, call `.decode('utf-8')` on the result of `pkg_resources.resource_string()`, as it was returning bytes. Also make several refactors to the doc related code: - Upgrade `docutils` to modern 1.14 so that we generate HTML5. See release notes: http://docutils.sourceforge.net/RELEASE-NOTES.html. - Use `"{}".format()` over `"{1}".format()` to comply with our style. - Invert some conditionals for an early return, resulting in less indentation. - Improve spacing of lines and remove unnecessary parentheses. - Use a new line for the block of `if` statements always. - Don't use `codecs.open()` in favor of builtin `open()`, as this is far more modern and idiomatic. ### Result `./build-support/bin/publish_docs.sh -o` produces a site without byte string literals at the top of the file. `PY=python2 ./build-support/bin/publish_docs.sh -o` works as expected.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Problem
When running
./pants markdown src::or./build-support/bin/publish_docs.sh -owith Python 3, the top of the generated page would haveb'\n\n\n\nincluded at the top.Will close #7546.
Solution
In
markdown_to_html.py, call.decode('utf-8')on the result ofpkg_resources.resource_string(), as it was returning bytes.Also make several refactors to the doc related code:
docutilsto modern 1.14 so that we generate HTML5. See release notes: http://docutils.sourceforge.net/RELEASE-NOTES.html."{}".format()over"{1}".format()to comply with our style.ifstatements always.codecs.open()in favor of builtinopen(), as this is far more modern and idiomatic.Result
./build-support/bin/publish_docs.sh -oproduces a site without byte string literals at the top of the file.PY=python2 ./build-support/bin/publish_docs.sh -oworks as expected.