bpo-30607: Use external python-doc-theme #2017

theacodes · 2017-06-09T04:19:27Z

I have uploaded a build of these docs at http://temp.theadora.io/cpython/index.html

https://bugs.python.org/issue30607

the-knights-who-say-ni · 2017-06-09T04:19:29Z

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!

theacodes · 2017-06-09T04:20:13Z

(I just signed the CLA, I'll nag the bot tomorrow when hopefully it'll have been reviewed.)

brettcannon · 2017-06-09T18:52:46Z

Just an FYI @jonparrott I just added the CLA bot to the theme repo.

brettcannon · 2017-06-09T18:54:39Z

.travis.yml

@@ -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


Will there need to be a change made to the docs.python.org build step for the docs to pull the theme in?

Also need to review how this change might affect installer builds and release builds which build copies of the docs. Assigned myself to review.

@brettcannon probably, but I don't know where that build step is.

@jonparrott See https://github.com/python/docsbuild-scripts

@zware yes, we'll just need to add the theme package to the requirements.txt there. I'll send a PR.

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?

@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.

@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. :)

Additionally update all existing dependencies in requirements.txt, as the common theme requires sphinx >= 1.6.0. Context: * python/cpython#2017 * https://bugs.python.org/issue30607

theacodes · 2017-06-13T04:43:22Z

CLA signed. :)

I've also created python/docsbuild-scripts#12

theacodes · 2018-01-19T17:27:21Z

I'm happy to rebase this and keep it current, but this kind of died of lack of attention.

zware · 2018-01-19T17:33:22Z

With python/docsbuild-scripts#12 merged, I don't think there's anything blocking this now.

theacodes · 2018-01-19T17:34:49Z

Thanks @zware, I'll attempt to rebase this (& reconcile any theme changes) over the weekend.

ned-deily

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).

bedevere-bot · 2018-01-22T23:46:01Z

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.

theacodes · 2018-01-25T21:55:37Z

Alright, this is rebased and ready to review & merge. Thanks @ned-deily and @zware.

ncoghlan · 2018-01-27T04:57:29Z

Note that https://pypi.python.org/pypi/python-docs-theme/ is now 0.0.1, and there's only one version, so we can postpone questions of whether or not we want to pin versions on different CPython branches or not.

theacodes · 2018-02-02T05:31:32Z

Gentle ping on this - I'd like to get it merged & hopefully do so before the branch gets stale. :)

ned-deily · 2018-02-09T04:47:10Z

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.

theacodes · 2018-02-09T20:27:05Z

One other thing - the daily docs build system may need a change to install python-docs-theme.

@ned-deily is that what I did in python/docsbuild-scripts#12?

ned-deily · 2018-02-10T03:20:05Z

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.

Context: python/cpython#2017 (comment)

theacodes · 2018-02-12T16:31:48Z

@ned-deily PR created: python/docsbuild-scripts#41 (I don't think that blocks this)

Context: python/cpython#2017 (comment)

JulienPalard · 2018-02-12T20:50:36Z

Merged python/docsbuild-scripts#41 after testing it locally.

theacodes · 2018-02-12T20:51:08Z

Thanks @JulienPalard. Anything else we need to do to get this merged? :)

Only merge once python/cpython#2017 has been merged.

Mariatta · 2018-03-01T19:20:51Z

Tested locally, things looking good.
We can merge devguide PR python/devguide#333 once this has been merged.

theacodes · 2018-03-01T19:22:23Z

Thanks, Mariatta!

Does anything else need to be done here? Let's merge?

ned-deily · 2018-03-01T21:05:55Z

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.)

theacodes · 2018-03-01T21:22:19Z

Yay!

…

On Thu, Mar 1, 2018, 1:06 PM Ned Deily ***@***.***> wrote: 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.) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2017 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUc0L6MqoS7GVIS7ANP1mC-5e9NtNiks5taGLGgaJpZM4N04vU> .

the-knights-who-say-ni added the CLA not signed label Jun 9, 2017

brettcannon reviewed Jun 9, 2017

View reviewed changes

ned-deily self-assigned this Jun 9, 2017

the-knights-who-say-ni added CLA signed and removed CLA not signed labels Jun 13, 2017

theacodes mentioned this pull request Jun 13, 2017

Add common docs theme as a dependency python/docsbuild-scripts#12

Merged

Mariatta added needs rebase and removed needs rebase labels Oct 9, 2017

ned-deily requested changes Jan 22, 2018

View reviewed changes

bedevere-bot added the awaiting changes label Jan 22, 2018

bpo-30607: Use external python-doc-theme

9d0b0c1

theacodes force-pushed the use-common-docs-theme branch from 2f2e0f1 to 9d0b0c1 Compare January 25, 2018 21:54

Add news entry

79d1985

ned-deily requested a review from JulienPalard February 9, 2018 04:40

ned-deily removed their assignment Feb 9, 2018

ned-deily approved these changes Feb 9, 2018

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting changes labels Feb 9, 2018

theacodes pushed a commit to theacodes/docsbuild-scripts that referenced this pull request Feb 12, 2018

Pull common docs theme from PyPI

f9b1112

Context: python/cpython#2017 (comment)

theacodes mentioned this pull request Feb 12, 2018

Pull common docs theme from PyPI python/docsbuild-scripts#41

Merged

JulienPalard pushed a commit to python/docsbuild-scripts that referenced this pull request Feb 12, 2018

Pull common docs theme from PyPI

bd00712

Context: python/cpython#2017 (comment)

Mariatta added a commit to python/devguide that referenced this pull request Mar 1, 2018

Reference python-docs-theme when building docs without make

3b4014f

Only merge once python/cpython#2017 has been merged.

Mariatta mentioned this pull request Mar 1, 2018

[don't merge yet] Reference python-docs-theme when building docs without make python/devguide#333

Closed

Mariatta approved these changes Mar 1, 2018

View reviewed changes

ned-deily merged commit bf63e8d into python:master Mar 1, 2018

bedevere-bot removed the awaiting merge label Mar 1, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-30607: Use external python-doc-theme #2017

bpo-30607: Use external python-doc-theme #2017

theacodes commented Jun 9, 2017 •

edited by bedevere-bot

Loading

the-knights-who-say-ni commented Jun 9, 2017

theacodes commented Jun 9, 2017

brettcannon commented Jun 9, 2017

brettcannon Jun 9, 2017

ned-deily Jun 9, 2017

theacodes Jun 9, 2017

zware Jun 9, 2017

theacodes Jun 9, 2017

theacodes Jun 9, 2017

ncoghlan Jun 10, 2017

theacodes Jun 13, 2017

theacodes commented Jun 13, 2017

theacodes commented Jan 19, 2018

zware commented Jan 19, 2018

theacodes commented Jan 19, 2018

ned-deily left a comment

bedevere-bot commented Jan 22, 2018

theacodes commented Jan 25, 2018

ncoghlan commented Jan 27, 2018

theacodes commented Feb 2, 2018

ned-deily commented Feb 9, 2018

theacodes commented Feb 9, 2018 •

edited

Loading

ned-deily commented Feb 10, 2018

theacodes commented Feb 12, 2018

JulienPalard commented Feb 12, 2018 •

edited

Loading

theacodes commented Feb 12, 2018

Mariatta commented Mar 1, 2018

theacodes commented Mar 1, 2018

ned-deily commented Mar 1, 2018

theacodes commented Mar 1, 2018 via email

bpo-30607: Use external python-doc-theme #2017

bpo-30607: Use external python-doc-theme #2017

Conversation

theacodes commented Jun 9, 2017 • edited by bedevere-bot Loading

the-knights-who-say-ni commented Jun 9, 2017

theacodes commented Jun 9, 2017

brettcannon commented Jun 9, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

theacodes commented Jun 13, 2017

theacodes commented Jan 19, 2018

zware commented Jan 19, 2018

theacodes commented Jan 19, 2018

ned-deily left a comment

Choose a reason for hiding this comment

bedevere-bot commented Jan 22, 2018

theacodes commented Jan 25, 2018

ncoghlan commented Jan 27, 2018

theacodes commented Feb 2, 2018

ned-deily commented Feb 9, 2018

theacodes commented Feb 9, 2018 • edited Loading

ned-deily commented Feb 10, 2018

theacodes commented Feb 12, 2018

JulienPalard commented Feb 12, 2018 • edited Loading

theacodes commented Feb 12, 2018

Mariatta commented Mar 1, 2018

theacodes commented Mar 1, 2018

ned-deily commented Mar 1, 2018

theacodes commented Mar 1, 2018 via email

theacodes commented Jun 9, 2017 •

edited by bedevere-bot

Loading

theacodes commented Feb 9, 2018 •

edited

Loading

JulienPalard commented Feb 12, 2018 •

edited

Loading