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

Tue Apr 11 18:29:32 EDT 2017

Brett Cannon wrote:
>
>
> On Tue, 11 Apr 2017 at 14:42 Ned Deily <nad at python.org 
> <mailto:nad at python.org>> wrote:
>
>     On Apr 11, 2017, at 12:50, Brett Cannon <brett at python.org
>     <mailto: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 <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 at 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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/core-workflow/attachments/20170411/c5d5711e/attachment-0001.html>