Brett Cannon wrote:
On Tue, 11 Apr 2017 at 14:42 Ned Deily <n...@python.org
<mailto:n...@python.org>> wrote:
On Apr 11, 2017, at 12:50, Brett Cannon <br...@python.org
<mailto:br...@python.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 <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.
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 example,
https://docs.python.org/release/3.6.1/download.html 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 possibly for JavaScript. The HTML versions of
docs for releases still receiving maintenance fixes are
auto-updated each day using Sphinx (for example,
https://docs.python.org/release/3.6.1/index.html).
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 <http://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 <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
core-workflow@python.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
_______________________________________________
core-workflow mailing list
core-workflow@python.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
