[issue12415] Missing: How to checkout the Doc sources
New submission from Philip Olson <philip@roshambo.org>: 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. ---------- assignee: docs@python components: Documentation messages: 139147 nosy: docs@python, philip priority: normal severity: normal status: open title: Missing: How to checkout the Doc sources _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Changes by Sandro Tosi <sandro.tosi@gmail.com>: ---------- nosy: +sandro.tosi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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 ---------- nosy: +eric.araujo versions: +Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Philip Olson <philip@roshambo.org> added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- assignee: docs@python -> eric.araujo keywords: +patch stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Sandro Tosi <sandro.tosi@gmail.com> added the comment: Hi Éric, did you reconsider the text of the patch or this issue just passed under your radar? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: 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. ---------- nosy: +ezio.melotti type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment:
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?
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment:
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"
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment:
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”.
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- dependencies: +Moving "Documenting Python" to Devguide _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Please review. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: Added file: http://bugs.python.org/file24249/metadoc-where-are-the-sources.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Sandro Tosi <sandro.tosi@gmail.com> added the comment: that looks ok to me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: +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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment:
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>`. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Any comment on my last message? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Philip Olson <philip@roshambo.org> added the comment: 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/ ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
Sandro Tosi added the comment: É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. ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________
participants (5)
-
Ezio Melotti -
Philip Olson
-
Roundup Robot
-
Sandro Tosi
-
Éric Araujo