Yeah; though using a common install and build script, pinned dependencies and running the production build up till the final deploy step on PRs (as well as the preview one) ensures things don’t suddenly break in production (unless something’s wrong with the final production deploy step itself, which in many/most cases would not be caught by a preview anyway). But it does avoid potential corner cases and simplify a maintenance, so certainly still a plus for RTD (or using Netlify or other providers for both preview and production deploys; I’ve only really used it for the former but its designed to be used for both).
2 Likes
I have to disagree with this assessment. The devguide is entirely about the development process of the language, sure, but that includes the PEP process, CPython as the reference implementation, etc. (and that was its intended purpose when I created it). If the details of how this all works doesn’t fit into the README and we don’t think maintaining a PEP about how the PEPs are built, then the devguide is a fine place for it to end up.
2 Likes
Right, and I would defer to your judgement, but I’m curious why the technical/implementation details of the main website build, deploy and hosting infra go in a separate guide, while the technical/implementation details of the PEP sub-website build, deploy and hosting infra would go in the devguide. It would seem this should at least be consistent, should it not?
Also, at present, a high-level overview of the overall PEP system is in the devguide; the PEP process and other PEP reader, writer, editor and reviewer-facing details are in PEP 1, PEP 12, etc., and a high-level proposal for the infra change in PEP 676. This contrasts with maintainer/webmaster-facing docs of the implementation details of the current low-level build, check and deployment infrastructure, which is distinct from either and would be expected to be more mutable, informal and only of interest to a handful of PEP repo/website maintainers.
As such, while the devguide might still be the desired location, I do think it it is worth at least considering whether the tight coupling and narrow focus of the content to the PEP repo and its maintainers might justify co-locating it there, either as just source files rendered by GitHub (like the Readme, Contributing guide, etc), or rendered and deployed to the PEPs subdomain (or another platform).
Discourse (this website) has a dark mode (configured in user preferences). I don’t know if the colours were configured by a Python admin, or are Discourse’s defaults.
It seems that there is strong consensus for adding a statement about PR previews, so I’ll add that in the next round of updates to the PEP.
There also seem to be a few options for the location of the documentation – I think a sensible way forwards here would be to write up said documentation and go from there (the amount will likely influence the final destination). Wherever it does end up, it would be prudent to back-link – if our putative potential contributor to the system is looking in the dev guide, the PEPs repo, etc, he should be able to find (a link to) the documentation easily from any such place.
I’ll get on with both of these, and the style changes for dark-mode PEPs (perfect for late-night techical review…!). Expect to hear an update within the next few days.
A
3 Likes
FWIW, I’ve been using furo which to my eye has nice light and dark modes, e.g. here.
At the very least, there should be a (non-published) readme in the top-level git tree. That can contain the full documentation or a link to wherever the documentation ends up living. A docs/ subdirectory in the PEP git tree would be fine, IMHO.
1 Like
I wasn’t asked? 
But rendering PEPs is a bit different than the website as its done by core devs constantly to not only make PEPs easier to read offline but to make sure there aren’t syntax errors. Same goes for building the docs. That doesn’t mean hosting needs to be covered in the same place, though.
1 Like
But this is also why I suggested the README first.
Fair point 
That’s a great point (I do that all the time too as a regular contributor, in both build systems for now, when writing and editing PEPs). I was thinking @AA-Turner was referring more to the parts related to maintainer-facing documentation of the build, deploy and hosting implementation rather than a contributor-facing guide, but maybe I misunderstood?
In any case, for that sort of content, given the main audience following general GitHub convention, I usually look for those sort of contributor-facing instructions in the Contributing Guide for the project in the project root (which I believe the PEPs repo has), that GitHub prominently exposes in various places around the UI for potential contributors. What do you think about putting those there, with a direct link (and perhaps even a short summary) on the PEPs page of the Python developer guide, and then including the maintainer-facing docs elsewhere (e.g. another root file, docs dir, etc)?
Yeah…perhaps I’m doth protesting too much too early, since this will all depend on how extensive the docs are and what’s in them.
Hence my failed attempt to try to wrap up this thread! It is a useful conversation to have but honestly until I write things up it is hard to predict how much text there’ll be.
Updating documentation will touch lots of things – the developer’s guide, the pythondotorg documentation, the README in the peps repo, perhaps PEP 1 / PEP 12. For now, a very brief description of using the Sphinx build system locally sits at the bottom of the peps repository README, but this will change. (Also, there’s a mild chicken-and-egg scenario with not wanting to confuse by referring to a proposed change before PEP 676 is accepted, but approval may be conditional on documentation!)
I will get these things done, but unfortunately (from a free time perspective) my real life also exists!
A
3 Likes
For what its worth, while I don’t have nearly your deep expertise about the particulars of the new build system (and it seems a number of the details, like CIs, previews, deployment and hosting, are still not fully finalized), let me know if there’s anything thing that I can help with, since writing, updating and maintaining documentation and their Sphinx-based build, CI, deployment and hosting systems is one of my main jobs with the Spyder project. And I’m well familiar with limited time and unlimited demands on it, but having this work merged would be a huge boon to my efforts on PEP 639, so I’m particularly invested in seeing this through expeditiously.
2 Likes
Sorry for the delay, I was a little under the weather.
PEP 676: 'dark mode', documentation, spec update, implementation update by AA-Turner · Pull Request #2239 · python/peps · GitHub proposes everything I think I said I’d do. If I missed anything, please do let me know.
(I included the documentation on that PR out of laziness rather than anything else – it isn’t a large set of documents so I think would be fine for the dev guide in terms of size – but maybe better to get to a mergeable state first and then have the debate about location (again!))
A
Thanks Cam – a review on the documentation I’ve proposed would be most helpful if at all possible, although I’m aware I write with a particular style!
A
1 Like
Thanks; it took a while to go through it thoroughly, but review submitted. Mostly just a bunch of little punctuation, grammar, typos, etc.; I tried to avoid rewriting except in a handful of spots where clarity would see a tangible benefit.
Dark mode support has now been merged! You can see a preview at PEP 8 – Style Guide for Python Code | peps.python.org – if your device requests a dark colour scheme it should render automatically, otherwise there is a toggle button in the top right-hand corner.
The documentation has also been reviewed and (for now) can be read at Building PEPs Locally | peps.python.org and An Overview of the PEP Rendering System | peps.python.org
This is only two pages, so could be added to the devguide – would appreciate views from @brettcannon and others on what would make the most sense.
A
5 Likes
I don’t think it hurts too much to have it as a dropdown.
I’ll also look into this and see what looks best (or is the cleanest). Likely will include on the same PR as above.
A
1 Like
While I respect and admire the level of detail that’s going into this, I think the style discussion is drowning out the big picture.
What’s currently keeping the PEP from being submitted?
I hope it is not style, which is important but can be adjusted later. The current preview is already an amazing improvement.
10 Likes
My comment replying to Petr got moved when the typography discussion was split, so re-posting the pertinent parts.
A
A decision on the documentation, mainly, see:
That is more to tie up loose ends though, and isn’t a blocker to the PEP itself.
2 Likes
Well, I think the PEP is ready to be submitted to the Steering Council? 
The docs location is probably fine, and as you say it isn’t a blocker, and they can be easily moved.
Plus it might take a little while for the SC to get through their backlog, so better to join the queue, and there’s also time to move the docs during that time if requested.
4 Likes