Brett Cannon wrote:
On Tue, 11 Apr 2017 at 14:42 Ned Deily <firstname.lastname@example.org mailto:email@example.com> wrote:
On Apr 11, 2017, at 12:50, Brett Cannon <firstname.lastname@example.org <mailto:email@example.com>> wrote: > With part of the goal of moving to GitHub being to minimize how much infrastructure we have to run, one of the long-term goals I have is to use Read the Docs to host Python's documentation. But to get there we have to move any "special" docs over first. That means relocating the devguide (it also means relocating the PEPs, but that's another issue and is blocked first and foremost by https://github.com/python/peps/issues/4). From a current infrastructure POV, there are several different issues here. IIUC, currently we have at least three server instances involved in python.org <http://python.org> docs. 1. I believe, the PEP docs are built and served from the main python.org <http://python.org> server where the main Django-based python.org <http://python.org> website is based. AFAIK, no one is proposing to replace that server. I'm not sure why the PEP docs are served there and not on the "docs" server (server 3 below); probably just an artifact of the gradual migration from the old python.org <http://python.org> website infrastructure (e.g. dinsdale) several years ago.
python.org http://python.org doesn't fall under python-dev's purview so I'm not proposing to do anything here except get the PEPs taken out.
Big +1 on moving the PEPs.
From my perspective there are a few reasons for thinking about moving. One is that low-maintenance isn't no-maintenance. Anything that helps take some load off the infrastructure team is a good thing in my opinion (especially when the PEPs and devguides are "unique snowflakes" in all of this as they are not built like the rest of docs.python.org http://docs.python.org).
I agree. ReadTheDocs has some effective hooks and badges for operations/build status. It's straightforward to administer. It also has the added benefit that it is where many Python users go to search for documentation.
Two, getting changes to these machines isn't always easy or fast. As I pointed out to Elvis, we don't have Pygments installed so we can get source highlighting in PEPs and the PR to fix it has been sitting there for quite a while. And because the infrastructure is custom not many people even know where to make changes to change things like what dependencies are installed are on the machines (I mean how many people even knew there are three machines before this email?).
I also think this is a win since it is much easier to create a consistent build environment using readthedoc.yml and environment.yml files. I'm also in favor of RTD over Jekyll or hosting on GitHub since Eric has been a key evangelist for Python for a long time and the code for RTD is a Python/Django base. (As an aside, I agree with Guido that we should provide some level of financial support towards RTD sustainability).
Three, updates to any of these docs only happens a couple of times a day instead of instantly. Obviously not always a big deal, but for the PEPs it can be annoying when you want to email out the link to the rendered version and you can't simply because the cron job has not run yet.
So even if we can't get rid of docs.python.org http://docs.python.org and we don't move that over to RTD, at least getting python.org/dev/peps http://python.org/dev/peps and docs.python.org/devguide http://docs.python.org/devguide to no longer be odd-ball infrastructure points is still a win in my book.
While RTD may or may not be right for docs.python.org, I think it's worth looking at least mirroring the CPython docs on RTD. An added benefit for hosting on RTD is that there is lots of documentation around for using Sphinx/RTD which provides an opportunity for attracting more contributors to documentation and community management.
core-workflow mailing list firstname.lastname@example.org https://mail.python.org/mailman/listinfo/core-workflow This list is governed by the PSF Code of Conduct: https://www.python.org/psf/codeofconduct