[issue12409] Moving Documenting Python to Devguide
Éric Araujo mer...@netwok.org added the comment: Glad my action plan worked :) There are now obsolete entries in the Doc/tools/sphinxext/susp-ignored.csv file: All lines starting with “documenting” can be removed. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Roundup Robot devn...@psf.upfronthosting.co.za added the comment: New changeset 7167c04780ed by Sandro Tosi in branch '2.7': Issue: #12409: remove obsolete susp-entries http://hg.python.org/cpython/rev/7167c04780ed New changeset 153e32333aaa by Sandro Tosi in branch '3.2': Issue: #12409: remove obsolete susp-entries http://hg.python.org/cpython/rev/153e32333aaa New changeset a6bf08666da2 by Sandro Tosi in branch 'default': Issue: #12409: merge with 3.2 http://hg.python.org/cpython/rev/a6bf08666da2 -- nosy: +python-dev ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Sandro Tosi sandro.t...@gmail.com added the comment: Éric, thanks for spotting it: removed. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Sandro Tosi sandro.t...@gmail.com added the comment: On Sat, Jan 14, 2012 at 04:36, Éric Araujo rep...@bugs.python.org wrote: Éric Araujo mer...@netwok.org added the comment: I just replied to your python-dev email. I think you can update 2.7 to use Sphinx 1.0 as soon as you’re down to a handful of warnings. thanks! I've just updated 2.7 to sphinx 1.0 - yay When the migration is done, you can add the documenting doc to the devguide and send a message to pydev to tell people to not commit changes to Doc/documenting in CPython clones anymore. In the same email you can ask who to ask for setting up redirects (BTW, will redirecting paths to fragments work? e.g. docs.py.o/documenting/style to devguide/documenting#style-and-blah). When the redirects are up you’ll be able to rm Doc/documenting. I just did that with: http://mail.python.org/pipermail/python-dev/2012-January/115520.html Then we’ll open other reports to talk about the unrelated I mentioned and to see how to stop downloading Sphinx from svn once per clone :) Ah yes, sure! Cheers, Sandro -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Sandro Tosi sandro.t...@gmail.com added the comment: Documenting Python has been: - moved to devguide; http://hg.python.org/devguide/rev/5d4a90e568ed - removed from 2.7, 3.2 and default; http://hg.python.org/cpython/rev/8975f7d0fbf7 http://hg.python.org/cpython/rev/70c46599fb0e http://hg.python.org/cpython/rev/900c01e643a7 Thanks everyone! -- resolution: - fixed stage: patch review - committed/rejected status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Georg Brandl ge...@python.org added the comment: We'll probably have to redirect all /documenting in Apache anyway. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Éric Araujo mer...@netwok.org added the comment: About the devguide patch: a) The part about C roles and directives should probably mention version specifics (:cmacro: for 2.7, :c:macro: for 3.x) — unless you make this bug dependent on updating Sphinx to 1.0 for 2.7 and then all versions use new-style :c:. b) You probably want to use ref:documenting instead of :doc:documenting (we always use ref) Not related to your patch, but it made me think about them so I’m just putting it out there for comments: Not sure we should keep the reST basics or just redirect to docutils and Sphinx docs. Likewise, maybe it’s time to stop mentioning the old Latex-based docs. (A nit: there are a few instances of `markup` that should be :file:`etc` or ``code``.) About the cpython patch: You could just have said “rm Doc/documenting” :) Georg, will you be the one to set up the docs.python.org redirects? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Sandro Tosi sandro.t...@gmail.com added the comment: Hi Éric, thanks for the review. On Fri, Jan 13, 2012 at 18:13, Éric Araujo rep...@bugs.python.org wrote: Éric Araujo mer...@netwok.org added the comment: About the devguide patch: a) The part about C roles and directives should probably mention version specifics (:cmacro: for 2.7, :c:macro: for 3.x) — unless you make this bug dependent on updating Sphinx to 1.0 for 2.7 and then all versions use new-style :c:. yeah, I'd love to not write both rules/directives formats to later revert this addition, so ok, let's make this bug depending on the migration to sphinx 1.0 of the 2.7 version. I've sent a follow-up of that task to python-dev some days ago, and comments (and help!) would be welcome there too. b) You probably want to use ref:documenting instead of :doc:documenting (we always use ref) ah ok, I just used the same role that was there; updated to use :ref: - fixed that (just pushed on my repo, not updated patch yet) Not related to your patch, but it made me think about them so I’m just putting it out there for comments: Not sure we should keep the reST basics or just redirect to docutils and Sphinx docs. as a matter of personal taste, I like small lists of commonly used commands/roles/directives/whatever in the doc, with additional links as needed, this give a quick idea (that's usually enough) on what to do but also the possibility for further digging (if one wants it). Likewise, maybe it’s time to stop mentioning the old Latex-based docs. we can do that, but maybe at a later step? so now just put the doc in the canonical place, later let's refactor it, removing dead parts and so on? i'm fine anyhow (A nit: there are a few instances of `markup` that should be :file:`etc` or ``code``.) I'll fix them in the mean time. About the cpython patch: You could just have said “rm Doc/documenting” :) eheh, well but a tiny tiny part remains :) if we go for a redirect to the devguide, I'm all for removing all that section from the doc; I left it there in case someone still refers directly to documenting/ or so (but indeed, all the sub-pages are no more reachable). Georg, will you be the one to set up the docs.python.org redirects? I can provide the configuration, but I don't have access to the machine, so some admins must be there as well. Cheers, Sandro -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Éric Araujo mer...@netwok.org added the comment: I just replied to your python-dev email. I think you can update 2.7 to use Sphinx 1.0 as soon as you’re down to a handful of warnings. When the migration is done, you can add the documenting doc to the devguide and send a message to pydev to tell people to not commit changes to Doc/documenting in CPython clones anymore. In the same email you can ask who to ask for setting up redirects (BTW, will redirecting paths to fragments work? e.g. docs.py.o/documenting/style to devguide/documenting#style-and-blah). When the redirects are up you’ll be able to rm Doc/documenting. Then we’ll open other reports to talk about the unrelated I mentioned and to see how to stop downloading Sphinx from svn once per clone :) -- versions: +Python 2.7, Python 3.2, Python 3.3 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Éric Araujo mer...@netwok.org added the comment: Could you provide a single patch or publish your version somewhere to help reviews? For the CPython docs, I think just removing the whole of Doc/documenting would be okay, or if we expect that people will go to that URI we may leave a placeholder page with only links. Georg? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Sandro Tosi sandro.t...@gmail.com added the comment: Sure, sorry I didn't make it before; here attached the 2 patches, one against devguide, the other to default cpython repo. -- keywords: +patch Added file: http://bugs.python.org/file24218/doc2devguide-devguide.patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Changes by Sandro Tosi sandro.t...@gmail.com: Added file: http://bugs.python.org/file24219/doc2devguide-cpython.patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Changes by Tshepang Lekhonkhobe tshep...@gmail.com: -- nosy: +tshepang ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Sandro Tosi sandro.t...@gmail.com added the comment: Hi, i'm at last back with some work to show; I've integrated all the Documenting python doc into devguide, and the commits are in this sandbox: http://hg.python.org/sandbox/morph-devguide/shortlog/a92d431ef749 (`documenting` branch). I took the files from default branch and merged all of them in a single page. It might be a bit log, but it has the advantage (at least for me) that there you can find all the info you need for documenting python, a ctrl+f works and you don't need to follow tons of links to find what you're looking for. then I've removed all the info from default branch (here: http://hg.python.org/sandbox/morph/shortlog/e9a4276b19d4 in default-documenting branch) which left only documenting/index.rst as mainly a reference to the devguide. I don't know what would be the best way to handle this transition on the python doc side, maybe converting that to a simple Doc/documenting.rst as it's now index.rst? but what text to left? Comments are very welcome! -- stage: needs patch - patch review ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Changes by Adam Woodbeck adam.woodb...@gmail.com: -- nosy: +adam.woodbeck ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Georg Brandl ge...@python.org added the comment: +1, and as Eric says, we can do it without changing versions of Sphinx used. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Brett Cannon br...@python.org added the comment: +1 -- Added file: http://bugs.python.org/file23005/unnamed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___+1br ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Changes by Sandro Tosi sandro.t...@gmail.com: Removed file: http://bugs.python.org/file23005/unnamed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Sandro Tosi sandro.t...@gmail.com added the comment: @Fred: thanks about it :) @Éric: I just want to have clear in mind what you mean; my original proposal was to move completely, the whole section Documenting python to devguide since it contains building instructions and how's the markup works for python. Is your proposal different and so, as I can read, to just move the building part to devguide and the rest of it be left in python documentation with links to sphinx upstream documentation? But one aspect I think it needs to be done as a prerequisite to this migration is: standardizing the sphinx/tools versions used to build the doc. devguide is version-agnostic, so we can talk about (without convoluted sentences) only about one way to build the doc. This was raised several times, even recently, on python-dev so I'm going to resurrect that thread so we can discuss there the pros/cons and then see from the outcome how we can move forward. -- stage: - needs patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Éric Araujo mer...@netwok.org added the comment: My comment was ambiguous, let me rephrase it: I am in favor of moving cpython/Doc/documenting to the devguide. Then, in the devguide, I would like to remove all the doc that’s just duplicating the upstream Sphinx docs, keeping only links and Python-specific parts. But one aspect I think it needs to be done as a prerequisite to this migration is: standardizing the sphinx/tools versions used to build the doc. If this gets rejected, we can move the Documenting tree to the devguide anyway, we’ll just have to add a few paragraphs for 2.7 differences. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Éric Araujo mer...@netwok.org added the comment: From IRC: fdrake After last being pressed on this, I got to thinking about it more. Back in the day, that's all the doc there was about the tool-chain. With Sphinx standing as a successful independent project, the tool documentation need no longer be part of any of the python.org docs; what's left probably can be moved. fdrake (Yes, I'm withdrawing my objection.) So, I am in favor of moving the Python-specific parts of Doc/documenting (if any) to the devguide and just link to the upstream Sphinx docs (which are a subset of our Doc/documenting) for the markup and suchlike. -- resolution: rejected - status: closed - open ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Ezio Melotti ezio.melo...@gmail.com added the comment: +1 -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Éric Araujo mer...@netwok.org added the comment: I don’t understand Fred’s replies. The scope of this document is much larger than Python's documentation, but extends to all projects written in Python that use Sphinx as their documentation tool. Really? docs.python.org/documenting is much smaller that sphinx.pocoo.org, and only seems to cover documenting Python, not any Python project. With that, it makes sense to keep it as part of the documentation for users of Python. I don’t follow. You’re saying that since the document also covers other projects than Python, it makes sense to include it in the Python docs? IMO, the criterion for the devguide is to have version-independent documents in one place instead of needlessly including them with CPython and having to sync across versions. For the Documenting Python docs, if they contain version-specific instructions, or if they contain instructions needed in a CPython tarball, then they’re in the right place, otherwise they could move to the devguide. -- nosy: +eric.araujo ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
New submission from Sandro Tosi sandro.t...@gmail.com: Hi! We have the devguide now, and it should be the place where to look for references and docs about contributing to Python, that means also for the documentation. In the official Python doc we have a section Documenting Python (http://docs.python.org/py3k/documenting/index.html) and I think it should be merged into the devguide - what's your opinion on that? -- assignee: docs@python components: Documentation messages: 139062 nosy: brett.cannon, docs@python, ezio.melotti, georg.brandl, sandro.tosi priority: normal severity: normal status: open title: Moving Documenting Python to Devguide ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Fred L. Drake, Jr. fdr...@acm.org added the comment: -1 Hi! We have the devguide now, and it should be the place where to look for references and docs about contributing to Python, that means also for the documentation. For information specific to the Python documentation itself, but not relevant to users documenting their own projects, yes. In the official Python doc we have a section Documenting Python (http://docs.python.org/py3k/documenting/index.html) and I think it should be merged into the devguide - what's your opinion on that? The scope of this document is much larger than Python's documentation, but extends to all projects written in Python that use Sphinx as their documentation tool. With that, it makes sense to keep it as part of the documentation for users of Python. -- nosy: +fdrake ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Sandro Tosi sandro.t...@gmail.com added the comment: Hi Fred, thanks for your input! Let's see what others think, but I think that at the very least, the Building the documentation section (that seams very specific to python) should be moved into the devguide. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue12409] Moving Documenting Python to Devguide
Raymond Hettinger raymond.hettin...@gmail.com added the comment: I agree with Fred. -- nosy: +rhettinger resolution: - rejected status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue12409 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
