[core-workflow] Where to host documentation? (was: Voting on possible subdomains for the devguide)

[Brett Cannon]

On Tue, 11 Apr 2017 at 12:29 Elvis Pranskevichus <elprans at gmail.com> wrote:

> On Tuesday, April 11, 2017 3:11:10 PM EDT Brett Cannon wrote:
> > > GH Pages support custom domain redirects [1].  "setup" in this case
> > > is putting together scripts to automate sphinx runs and the git push
> > > of the compiled output to the appropriate repo/branch.
> >
> > So we would have to either set up another repo or commit the rendered
> > files to the repo?
>
> Either a separate repo, or commit to the gh-pages branch.
>
> > >   If there's
> > >
> > > interest in pursuing this option, I can help with setting things up.
> >
> > I assume we would lose the widget Read the Docs provides which is
> > handy for getting to the GitHub page for editing the content? I guess
> > we lose anything else that
> > https://docs.readthedocs.io/en/latest/features.html lists.
>
> https://gist.github.com/mgedmin/6052926
>
> > I'm just trying to think of what we gain/lose if we switch to GH Pages
> > over RTFD as I don't want to end up with three different
> > documentation hosting solutions sort of like we have now where we
> > build the devguide, PEPs, and the docs themselves in special ways
> > that all happen to be hosted on PSF infrastructure (e.g. getting
> > Pygments installed for the PEPs has stalled out and it would be good
> > that any solution we choose be flexible enough to handle this kind of
> > situation:
> > https://github.com/python/peps/pull/229/files/70c6c1d010c1d50a375430c4
> > ba6ae3e4f439306c#r107471836 ).
>
> The idea is that the doc build is done as part of CI and the product is
> uploaded as static content (GH pages is an option, but it might be
> anything capable of serving static content).
>

One place where this might actually show itself to be useful is with the
PEPs. That build toolchain generates HTML files directly and doesn't even
use Sphinx (at least not yet). I have opened
https://github.com/python/peps/issues/241 to discuss the idea.


>
> One of the reasons why we went with GH Pages for asyncpg is that at the
> time RTFD did not support Python 3.5 syntax and we wanted to use
> autodoc.  Could this be an issue when building Python documentation?
> Can the master branch Docs/ be built by Sphinx running on Python 3.4?
>

There's no version requirement for the docs as we don't use the autodoc
extension. And I think Read the Docs uses a newer image now as I was
buliding the docs for gidgethub using autodoc and that uses 3.5 syntax.

And how would versions be handles for GH Pages? E.g. how would
docs.python.org handle viewing the e.g. 2.7 data? I guess you're just
really careful to upload to subdirectories in the gh-pages branch?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/core-workflow/attachments/20170411/42a1abda/attachment.html>