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

Fix doc generation rendering byte literals with Python 3 #7556

Merged
merged 4 commits into from Apr 14, 2019

Conversation

Projects
None yet
3 participants
@Eric-Arellano
Copy link
Contributor

commented Apr 14, 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.

Eric-Arellano added some commits Apr 14, 2019

Upgrade docutils to modern 1.14
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.
Refactor sitegen
Use our preferred .format() style, invert conditionals for early return, and improve spacing.

@Eric-Arellano Eric-Arellano merged commit 302dea6 into pantsbuild:master Apr 14, 2019

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@Eric-Arellano Eric-Arellano deleted the Eric-Arellano:fix-publishing-py3 branch Apr 14, 2019

@stuhood stuhood added this to the 1.15.x milestone Apr 15, 2019

stuhood added a commit that referenced this pull request Apr 15, 2019

Fix doc generation rendering byte literals with Python 3 (#7556)
### 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
You can’t perform that action at this time.