[Python-Dev] Frequency of the dev docs autobuild

[R. David Murray]

On Sun, 02 May 2010 00:44:22 +0200, =?ISO-8859-1?Q?=22Martin_v=2E_L=F6wis=22?= <martin at v.loewis.de> wrote:
> R. David Murray wrote:
> > On Sat, 01 May 2010 16:18:19 +0100, Paul Moore <p.f.moore at gmail.com> wrote:
> >> On 1 May 2010 15:28, R. David Murray <rdmurray at bitdance.com> wrote:
> >>> Unless I'm missing something, I don't see any docs there about the
> >>> automated build process and when and where it runs.
> >> I assume Georg was referring to "Development versions of the Python
> >> documentation are available on-line and updated daily".
> > 
> > Yes, most likely.  I think I am asking for more documentation than you
> > were :)
> 
> Then I think you have to propose specific wording. It runs on
> www.python.org (why would you expect it to run elsewhere???),

I had in fact overlooked the indicated sentence when reading the page.

It's not that I expect it to run somewhere else, but that it did indeed
used to run somewhere else (if I'm reading the build.sh script correctly),
so I think it is worth making it explicit.  Also note that it isn't
obvious (without resolving the host names) that docs.python.org and
www.python.org are the same machine.

> and what about "daily" do you consider imprecise? Do you really need
> exact hour, minute, and second? What for?

I wasn't asking for more precision than daily (I just hadn't seen it), but
now that I think about it it would indeed be nice to know when the cron
job starts, so that we know that if the checkin didn't happen before then,
it won't show up in the online docs until the next day.  I don't think
this is particularly *important* to know, it would just be nice to know.

Is it only the development versions that get updated, or do our updates
to the next bug fix release also get posted daily (and those are the docs
web site visitors normally see, I believe)?  I was under the impression
that it was the latter, but that Georg had also changed things so that
a reference to a particular dot release got the snapshot of the docs
that were shipped with that dot release.  This impression seems to be
confirmed by examination of the various pages involved.

To answer your question about what wording I'd like, I think that it would
be worthwhile to say somewhere (not necessarily on that page...maybe in
the doc README.txt?...but it could be ont that page...) that the docs are
auto-built by a cron job on the server hosting docs.python.org running
'make dist' in the doc directory of a freshly updated checkout and
then....doing something with the resulting files?  Or maybe the apache
URLs point right at the dist directory in that autobuild checkout?
Anyway, exactly how it all works is what I would like to see documented.

Background: one of my tasks for one of my customers is helping them try to
make it so that an outsider coming in could learn everything they needed
to know to operate the system from the available docs...a goal that they
are nowhere near achieving, but which I think is a worthwhile goal for
which to strive.

--
R. David Murray                                      www.bitdance.com