Add sphinx support #1385
Add sphinx support #1385
Conversation
|
Hello, and thanks for your contribution! I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA). CLA MissingOur records indicate the following people have not signed the CLA: For legal reasons we need all the people listed to sign the CLA before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue. If you have recently signed the CLA, please wait at least one business day You can check yourself to see if the CLA has been received. Thanks again for the contribution, we look forward to reviewing it! |
|
Signed agreement |
|
Also of note is that I wasn't sure what minimum version of Python I had to support so I went off of travis, which targets 3.7, and used newer features like f-strings etc. If there is a more formal minimum please let me know and I'll make the needed changes. |
|
It’s nice to see your progress here! The CLA check is based on bugs.python.org accounts: do you have one there, with your github username in your profile? Please check the steps detailed in the link in the bot’s message #1385 (comment) The PEP pages repeat the PEP tile in the table of contents, which adds a level of nesting that’s not wanted. Could you address this? |
Thanks!
I signed 2 days ago - my latest push seems to have triggered the Kight to say Ni!
Will do |
|
I cannot review this PR, it's too big. Try maybe to split it into smaller parts, or try to only build a subset of PEPs. |
Hi Victor -- thanks for the comment! I don't have much experience with breaking up PRs, especially as everything is interdependent but will have a go. I think the main themes / sub-areas I'd identify would be:
If you have any suggestions on natural breakpoints they would be appreciated, otherwise I will have a go shortly. |
|
Hello, and thanks for your contribution! I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA). CLA MissingOur records indicate the following people have not signed the CLA: For legal reasons we need all the people listed to sign the CLA before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue. If you have recently signed the CLA, please wait at least one business day You can check yourself to see if the CLA has been received. Thanks again for the contribution, we look forward to reviewing it! |
- RFC2822 headers work - Contents page generated - Title autogeneration not working - PEP 0 not started
Also add pep_parser as I missed it
Hi Victor (@vstinner) - I have now broken the PR into smaller chunks, apologies for the delay. Please let me know if smaller logical units would be useful and I will do so. #1565 - core PR Thanks, |
Co-authored-by: Pradyun Gedam <3275593+pradyunsg@users.noreply.github.com>
|
Thanks for splitting them into logical blocks, but at least each one can't be merged independently as the CI fails, because they're still dependent on each other, so that may still be a review blocker. Is it all possible to split out individual chunks that could be merged independently, and so the CI passes? They might be small, but would help reduce the size a bit. I don't have merge rights, but perhaps a good approach would be to aim to have parallel deploys: the old, existing one, and also a new one to Read the Docs. Then once RTD has been verified, it could be set as the main location and the old one disabled. It would be really great to move forward with this, especially as it's difficult to build python.org locally for testing things like #1577. |
|
Hi Hugo, The CI fails partially as all the PRs are using the 'final' state travis recipe - if I reverted to the current (and added the To be honest I'm not sure what having parallel deploys would acheieve, or what that would look like. I could add the current build process back ( Also just for clarity - this currently builds to GitHub Pages not readthedocs, for flexibility. RE #1577, pygments is currently supported in this PR! Sorry for the request for clarity but I don't want to do a lot more work for the PR to continue to stall - I'm also really keen to move forwards on this. However if doing something would help reduce burden on reviewers then I'm really keen to understand that and get it done! Thanks, |
|
Parallel deploys may allow a quicker merge: the new deploy on GitHub Pages wouldn't yet be a live version, and further tweaks (in later, smaller PRs) can be made before committing to turning off the old deploy. But as I say, I don't have merge rights here, and completely understand you don't want to do a lot more work for nothing, so we're probably best off waiting for guidance from a maintainer. |
|
That makes sense - I think that would be a useful thing to do, but will wait for guidance before going ahead |
[potentially resolves #2]
This adds sphinx as a build process, potentially resolving issue #2. Note that there are a couple of hacks - on generating the title and contents elements for each PEP's HTML representation - I (personally) think that it would be clearer to have these directives in the source PEP files but I'm not sure if this would be allowed. (If it is I am of course happy to do this work!)
I haven't touched the bash.deploy script, and I endeavoured to ensure that the makefile still outputs a tarball of the files and the RSS file, retaining what was previously happening.
Sphinx generates two index files (contents and genindex) which I think are uncessary given PEP 0, but I think that if the relbars at the top and bottom are disabled then there will be minimal impact (I looked for a way to disable generation but couldn't find one).
Finally a few misc notes:
Thanks,
Adam