Brett Cannon wrote:
On Apr 11, 2017, at 12:50, Brett Cannon <firstname.lastname@example.org> 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 docs.
1. I believe, the PEP docs are built and served from the main python.org server where the main
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 website infrastructure (e.g. dinsdale)
several years ago.
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.
2, The second server is used to serve the download files for releases,
like source tar balls, binary installers (Win/Mac), and the pre-built
documentation formats (PDF, HTML, epub, etc) for each release (for
has download links like https://docs.python.org/ftp/python/doc/3.6.1/python-3.6.1-docs-pdf-letter.zip).
These files are built and managed by the release managers for each
release and do not get updated.
3. The third server is used to serve the most recent HTML version of
docs for *all* Python releases going back to 1.4. Docs prior to 2.6 (?)
were not produced with Sphinx, so are effectively static HTML except
receiving maintenance fixes are auto-updated each day using Sphinx (for
So, to actually reduce the number of servers in the PSF infrastructure,
solutions for all of these docs need to be found. Since the main python.org server is not going
away, I'm not sure what is gained by spending a lot of time on trying to
eliminate the other two, which I suspect are very low-maintenance and
could probably be combined. In other words, I guess I don't see how we
gain much, if anything, in trying to move things to RTD.
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
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
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
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.
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
This list is governed by the PSF Code of Conduct: https://www.python.org/psf/codeofconduct