On Sun, 02 May 2010 00:44:22 +0200, =?ISO-8859-1?Q?=22Martin_v=2E_L=F6wis=22?= email@example.com wrote:
R. David Murray wrote:
On Sat, 01 May 2010 16:18:19 +0100, Paul Moore firstname.lastname@example.org wrote:
On 1 May 2010 15:28, R. David Murray email@example.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