classification
Title: Missing: How to checkout the Doc sources
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: 12409 Superseder:
Assigned To: eric.araujo Nosy List: docs@python, eric.araujo, ezio.melotti, philip, python-dev, sandro.tosi
Priority: normal Keywords: patch

Created on 2011-06-26 06:29 by philip, last changed 2012-08-20 22:04 by sandro.tosi. This issue is now closed.

Files
File name Uploaded Description Edit
metadoc-where-are-the-sources.diff eric.araujo, 2012-01-16 16:17
Messages (18)
msg139147 - (view) Author: Philip Olson (philip) Date: 2011-06-26 06:29
I was unable to determine how to download the Python documentation source files (for building via Sphinx) but did figure out the following:

   hg clone http://hg.python.org/cpython
   cd cpython/Doc
   make html

Where to get the Doc sources deserves a mention here:

   http://docs.python.org/dev/documenting/building.html

I don't know this topic so won't propose a patch, but building.txt should mention where/how to get 'Doc' before the 'cd Doc' example.
msg139652 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-02 14:01
How about adding this near the top of documenting/building:

  The sources for the Python documentation are included in the
  Python repository, alongside code and tests.  Follow the
  instructions in the `Developpers' Guide`_ to get a copy of this
  repository.

  _Developpers's Guide: http://docs.python.org/devguide
msg139690 - (view) Author: Philip Olson (philip) Date: 2011-07-03 16:11
Thank you, that patch solves this bug report.

However, now I'm not sure which branches we should or must contribute documentation to. Python versions "2.7, 3.2, and 3.3" are now associated to this bug report, so are these the active documentation branches? How is this handled?
msg139768 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-04 13:52
We fix bugs in 3.2 and then forward-merge in what will become 3.3, using Mercurial.  Then we apply the same change for 2.7.  More info: http://docs.python.org/devguide

I will commit this change this week.
msg150697 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-01-05 21:56
Hi Éric, did you reconsider the text of the patch or this issue just passed under your radar?
msg150744 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-06 16:51
I merely forgot, thanks for the prod.  I’m taking your message as a +1 to the wording and will commit when the server I use for tunnels is back online.
msg150747 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-01-06 17:02
http://docs.python.org/dev/documenting/building.html also needs to be updated (it still mentions Subversion and probably obsolete versions of Sphinx and other packages).  If you are going to add the text proposed in your second message, you might want to drop a couple of "p"s from there.
msg150749 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-06 17:05
> http://docs.python.org/dev/documenting/building.html also needs to be updated (it
> still mentions Subversion and probably obsolete versions of Sphinx and other
> packages).
Well, the doc makefile still uses Subversion.  As for the versions, if the ones listed in the doc don’t match the ones used in the makefile, I’ll sync them.

> If you are going to add the text proposed in your second message, you might want
> to drop a couple of "p"s from there.
I don’t understand: "p"s?
msg150751 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-01-06 17:12
> Well, the doc makefile still uses Subversion. 
Indeed, I was thinking about getting a CPython checkout with the doc, not about the tools used to built it (maybe it could be clarified).

> I don’t understand: "p"s?
From "_Developpers's Guide: http://docs.python.org/devguide"
msg150752 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-06 17:16
> Indeed, I was thinking about getting a CPython checkout with the doc
Right.  I’ll edit my wording to mention Mercurial.

>> I don’t understand: "p"s?
>From "_Developpers's Guide: http://docs.python.org/devguide"
The curse of being French :)  I always want to write “developpers’ guide” when it’s “developer’s guide”.
msg151377 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-16 16:16
Please review.
msg151406 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-01-16 20:19
that looks ok to me.
msg151436 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-01-17 09:55
+The documentation sources are part of the main :ref:`CPython Mercurial
+repository <setup>`.

I think "documentation sources" is a bit vague.  If the goal is enable people to find those files, IMHO it would be better to state explicitly that there are bunch of rst files in the Doc/ directory that comes with cpython and that they are used to build the online documentation.
msg151471 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-17 16:35
> I think "documentation sources" is a bit vague.
I don’t know.  I probably wrote it under the assumption that the audience of this doc was developers, who already know that programmers don’t write HTML manually but generate it, and just need to know where to find the sources.  To a C programmer wanting to fix a bug, we just say “the sources for X are in Include and Modules”, and it’s enough.

Thinking about it, the assumption is probably bad.  Sometimes we have to explain to new contributors where to find a Python module in the repo and how to write a test, so it would probably be better to explain more.  Here’s my draft, feel free to improve my patch with it (there may be duplication) and commit the result when you two are in agreement while I’ll be offline.

  The documentation in HTML, PDF or epub format is generated from text files
  written using the :ref:`reStructuredText format <markup> and contained in
  the :ref:`CPython Mercurial repository <setup>`.
msg163892 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-06-25 05:11
Any comment on my last message?
msg163991 - (view) Author: Philip Olson (philip) Date: 2012-06-25 16:26
I think you should make the commit. 

Also, the aforementioned [old] Subversion reference for Sphinx is a real issue here. And I think the "Without make" section should link to http://sphinx.pocoo.org/
msg168706 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-20 22:02
New changeset e0d68c73e351 by Sandro Tosi in branch 'default':
Issue #12415: describe where the documentation files are (patch by Éric Araujo)
http://hg.python.org/devguide/rev/e0d68c73e351
msg168708 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-08-20 22:04
Éric: I've just committed your patch, with also the latest changes.

Philip: In order to be consistent with the way the documentation is compiled on the Python platform, the svn checkout must be used: else if you refer to the upstream website, a contributor can checkout an updated version that will generate a different result.
History
Date User Action Args
2012-08-20 22:04:15sandro.tosisetstatus: open -> closed
resolution: fixed
messages: + msg168708

stage: patch review -> resolved
2012-08-20 22:02:18python-devsetnosy: + python-dev
messages: + msg168706
2012-06-25 16:26:47philipsetmessages: + msg163991
2012-06-25 05:11:32eric.araujosetmessages: + msg163892
2012-01-18 10:07:53sandro.tosilinkissue13810 superseder
2012-01-17 16:35:07eric.araujosetmessages: + msg151471
2012-01-17 09:55:37ezio.melottisetmessages: + msg151436
2012-01-16 20:19:31sandro.tosisetmessages: + msg151406
2012-01-16 16:17:07eric.araujosetfiles: + metadoc-where-are-the-sources.diff
2012-01-16 16:16:47eric.araujosetmessages: + msg151377
2012-01-13 17:13:20eric.araujosetdependencies: + Moving "Documenting Python" to Devguide
2012-01-06 17:16:55eric.araujosetmessages: + msg150752
2012-01-06 17:12:49ezio.melottisetmessages: + msg150751
2012-01-06 17:05:17eric.araujosetmessages: + msg150749
2012-01-06 17:02:02ezio.melottisettype: enhancement

messages: + msg150747
nosy: + ezio.melotti
2012-01-06 16:51:45eric.araujosetmessages: + msg150744
2012-01-05 21:56:00sandro.tosisetmessages: + msg150697
2011-07-04 13:52:57eric.araujosetkeywords: + patch
assignee: docs@python -> eric.araujo
messages: + msg139768

stage: patch review
2011-07-03 16:11:00philipsetmessages: + msg139690
2011-07-02 14:01:16eric.araujosetnosy: + eric.araujo

messages: + msg139652
versions: + Python 2.7, Python 3.2, Python 3.3
2011-06-26 07:07:57sandro.tosisetnosy: + sandro.tosi
2011-06-26 06:29:37philipcreate