bpo-30607: Use external python-doc-theme by theacodes · Pull Request #2017 · python/cpython (original) (raw)
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 andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Conversation32 Commits2 Checks0 Files changed
Conversation
This file contains hidden or 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
[ Show hidden characters]({{ revealButtonHref }})
Hello, and thanks for your contribution!
I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA).
Unfortunately our records indicate you have not signed the CLA. For legal reasons we need you to sign this before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.
Thanks again to your contribution and we look forward to looking at it!
(I just signed the CLA, I'll nag the bot tomorrow when hopefully it'll have been reviewed.)
Just an FYI @jonparrott I just added the CLA bot to the theme repo.
| @@ -37,7 +37,8 @@ matrix: |
|---|
| - cd Doc |
| # Sphinx is pinned so that new versions that introduce new warnings won't suddenly cause build failures. |
| # (Updating the version is fine as long as no warnings are raised by doing so.) |
| - python -m pip install sphinx~=1.6.1 |
| # The theme used by the docs is stored seperately, so we need to install that as well. |
| - python -m pip install sphinx~=1.6.1 git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will there need to be a change made to the docs.python.org build step for the docs to pull the theme in?
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also need to review how this change might affect installer builds and release builds which build copies of the docs. Assigned myself to review.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@brettcannon probably, but I don't know where that build step is.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@zware yes, we'll just need to add the theme package to the requirements.txt there. I'll send a PR.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually before I do that- @ncoghlan you mentioned that you didn't think we should publish the theme to PyPI, but it's seeming like it's going to be a lot more convenient to do that if we're gonna use it here. WDYT?
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@jonparrott The main problem I see with it is that PyPI doesn't have great "teams" support, so it adds an awkward extra set of permissions to manage in an already awkward update process.
Whereas if we're installing the theme directly from git, then the CPython docs maintainers should already have all the access they need to update it - they'll just be modifying a different repo, rather than having to worry about also tagging that repo and making a new PyPI release.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ncoghlan great point. I like it, I just wanted to understand why. I can add this to the comments here and in the build scripts. :)
theacodes pushed a commit to theacodes/docsbuild-scripts that referenced this pull request
I'm happy to rebase this and keep it current, but this kind of died of lack of attention.
Thanks @zware, I'll attempt to rebase this (& reconcile any theme changes) over the weekend.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See my comments on python/python-docs-theme#5 about unnecessarily adding a docs build dependency on Git. Also, the PR needs to be rebased and retested to accommodate the changes made to support multiple languages. At that time, the full docs build should be tested ("make dist"). The step needed to install the theme package (presumably now from PyPI rather than from Github) should be added to the Makefile's "venv" recipe ("make venv") which currently installs the complete Docs build toolchain (now blurb, sphinx, and dependencies).
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.
Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.
Alright, this is rebased and ready to review & merge. Thanks @ned-deily and @zware.
Gentle ping on this - I'd like to get it merged & hopefully do so before the branch gets stale. :)
Thanks for addressing my review comment; distributing via PyPI looks much cleaner to me.
@JulienPalard if you have the time and interest, I would appreciate your review of this, especially if there any implications for the translated docs. Otherwise, we can deal with fixes during the 3.8 feature dev cycle (this change is not appropriate for 3.7 or earlier systems). One other thing - the daily docs build system may need a change to install python-docs-theme.
is that what I did in python/docsbuild-scripts#12?
Ah, yes. That should be updated to require the new package rather than getting from Github.
theacodes pushed a commit to theacodes/docsbuild-scripts that referenced this pull request
JulienPalard pushed a commit to python/docsbuild-scripts that referenced this pull request
Thanks @JulienPalard. Anything else we need to do to get this merged? :)
Mariatta added a commit to python/devguide that referenced this pull request
Tested locally, things looking good.
We can merge devguide PR python/devguide#333 once this has been merged.
Thanks, Mariatta!
Does anything else need to be done here? Let's merge?
Thanks Jon and everyone else who worked on this. Let's see how it works for 3.8. (I don't think this should be backported.)
Reviewers
