| 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) *  |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
Date: 2012-01-16 16:16 |
| Please review. |
|
|
| msg151406 - (view) |
Author: Sandro Tosi (sandro.tosi) * |
Date: 2012-01-16 20:19 |
| that looks ok to me. |
|
|
| msg151436 - (view) |
Author: Ezio Melotti (ezio.melotti) * |
Date: 2012-01-17 09:55 |
| +The documentation sources are part of the main :ref:`CPython Mercurial +repository `. 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) * |
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 and contained in the :ref:`CPython Mercurial repository `. |
|
|
| msg163892 - (view) |
Author: Éric Araujo (eric.araujo) * |
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)  |
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) * |
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. |
|
|