This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Dev Guide update procedure documentation in dev guide outdated
Type: Stage: resolved
Components: Devguide Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: chris.jerdonek, eric.araujo, ezio.melotti, georg.brandl, loewis, ned.deily, pitrou, python-dev
Priority: normal Keywords: patch

Created on 2012-07-10 00:40 by chris.jerdonek, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
issue-15311-1.patch chris.jerdonek, 2012-07-10 07:02
issue-15311-2.patch chris.jerdonek, 2012-08-02 20:08
Messages (18)
msg165138 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-10 00:40
The Dev Guide says that it is "managed using the same process as is used for the main Python documentation":

http://docs.python.org/devguide/docquality.html#helping-with-the-developer-s-guide

However, it looks the Dev Guide might not be on the same schedule of getting updated once a day as it says for the main Python documentation:

http://docs.python.org/devguide/docquality.html#helping-with-documentation

It would help to say something about the mechanism by which the Dev Guide gets updated if that mechanism is different from the main Python documentation.
msg165140 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-07-10 02:07
I think there's an hook the rebuilds the devguide whenever someone pushes something.
msg165156 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-10 03:54
This commit from 2 days ago--

http://hg.python.org/devguide/rev/d1958a94d0ff

doesn't seem to be reflected in the published version as of yet:

http://docs.python.org/devguide/docquality.html

So maybe there is just a problem with the hook.  If it does get rebuilt right away, that would be worth mentioning, too.
msg165158 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2012-07-10 04:35
The web update hook is broken at the moment:

http://article.gmane.org/gmane.comp.python.devel/134057
msg165170 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-10 07:02
Patch attached.

I also added a note about building the Dev Guide documentation.  Unlike the main Python documentation, `make html` for the Dev Guide doesn't seem to install Sphinx automatically.
msg166607 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-27 21:56
Hi Ned, you committed two of my Dev Guide patches in the recent past.  I was wondering if you would be willing to commit this one as well.  Thanks a lot.
msg166609 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2012-07-27 22:03
I believe you'll find that the "update" target in the Doc Makefile will install or update all the necessary doc tools including Sphinx.
msg166610 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-07-27 22:04
The Doc makefile does install Sphinx, just like it used to install the previous toolchain, but the devguide is a regular Sphinx project which requires you to have Sphinx installed.
msg166611 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2012-07-27 22:08
Sorry, of course!  The devguide is not the docset.
msg166613 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-07-27 22:15
New changeset 706b1fa362a4 by Ned Deily in branch 'default':
Issue #15311: Expand section on helping with the Developer's Guide
http://hg.python.org/devguide/rev/706b1fa362a4
msg166614 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2012-07-27 22:16
Thanks for the patch.
msg166615 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2012-07-27 22:19
The original issue ("Developer Guide doesn't get updated once a day") isn't fixed, though.
msg166616 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-27 22:26
Thanks, Ned!  Renaming the issue title to be more specific.
msg167221 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-02 14:04
Has this issue been resolved?  I saw that the following change is on the web site today:

http://hg.python.org/devguide/rev/851adff2d434

(though I didn't verify it immediately, just 6 hours after).
msg167231 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-08-02 15:19
I think MvL fixed it.
msg167234 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2012-08-02 15:30
I added an automated build process, yes. However, the current text is incorrect as it states that the build occurs immediately through a hook. 

This is not the case; instead, there is a cronjob that pulls changes. I refuse to report the frequency with which this happens, and advise against documenting the status quo, since that may again get outdated. It should be safe to say that changes should be published within a day.
msg167249 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-02 20:08
Attaching proposed wording along the lines Martin suggested.
msg167287 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-03 04:06
New changeset 864cd63db2bb by Ned Deily in branch 'default':
Closes #15311 - update devguide publication info.
http://hg.python.org/devguide/rev/864cd63db2bb
History
Date User Action Args
2022-04-11 14:57:32adminsetgithub: 59516
2012-08-03 04:06:19python-devsetstatus: open -> closed
resolution: fixed
messages: + msg167287

stage: resolved
2012-08-02 20:08:13chris.jerdoneksetfiles: + issue-15311-2.patch
keywords: + patch
messages: + msg167249
2012-08-02 15:31:14loewissettitle: Dev Guide update hook broken -> Dev Guide update procedure documentation in dev guide outdated
2012-08-02 15:30:44loewissetpriority: critical -> normal

messages: + msg167234
2012-08-02 15:19:19ezio.melottisetnosy: + loewis
messages: + msg167231
2012-08-02 14:04:29chris.jerdoneksetmessages: + msg167221
2012-07-27 22:26:01chris.jerdoneksetkeywords: - patch, easy

messages: + msg166616
title: Developer Guide doesn't get updated once a day -> Dev Guide update hook broken
2012-07-27 22:19:48pitrousetstatus: closed -> open
priority: normal -> critical
messages: + msg166615

resolution: fixed -> (no value)
stage: resolved -> (no value)
2012-07-27 22:16:34ned.deilysetstatus: open -> closed
resolution: fixed
messages: + msg166614

stage: patch review -> resolved
2012-07-27 22:15:49python-devsetnosy: + python-dev
messages: + msg166613
2012-07-27 22:08:20ned.deilysetmessages: + msg166611
2012-07-27 22:05:00eric.araujosetmessages: + msg166610
2012-07-27 22:03:37ned.deilysetmessages: + msg166609
2012-07-27 21:56:39chris.jerdoneksetmessages: + msg166607
2012-07-14 12:42:32eric.araujosetnosy: + eric.araujo
2012-07-10 07:04:17chris.jerdoneksetstage: patch review
2012-07-10 07:02:32chris.jerdoneksetfiles: + issue-15311-1.patch
keywords: + patch
messages: + msg165170
2012-07-10 04:35:17ned.deilysetnosy: + ned.deily

messages: + msg165158
versions: - Python 3.3
2012-07-10 03:54:42chris.jerdoneksetmessages: + msg165156
2012-07-10 02:07:22ezio.melottisetnosy: + georg.brandl, pitrou
messages: + msg165140
2012-07-10 00:40:20chris.jerdonekcreate