[core-workflow] Voting on possible subdomains for the devguide

[Brett Cannon]

On Tue, 11 Apr 2017 at 14:42 Ned Deily <nad at python.org> wrote:

> On Apr 11, 2017, at 12:50, Brett Cannon <brett at 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 docs.
>
> 1. I believe, the PEP docs are built and served from the main python.org
> server where the main Django-based 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 website
> infrastructure (e.g. dinsdale) several years ago.
>

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.


>
> 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 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). 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?). 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 and we don't move that over
to RTD, at least getting python.org/dev/peps and docs.python.org/devguide
to no longer be odd-ball infrastructure points is still a win in my book.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/core-workflow/attachments/20170411/8cf9e19a/attachment.html>