[issue8904] quick example how to fix docs
New submission from anatoly techtonik <techtonik@gmail.com>: It would be helpful to have examples how to patch docs in some place like http://docs.python.org/bugs.html For example, in CHM version of 2.6.5 manual open() anchor points to reference/datamodel.html#index-844 and to tutorial/inputoutput.html#index-1080 but not to library/functions.html#open ---------- assignee: docs@python components: Documentation messages: 107127 nosy: docs@python, techtonik priority: normal severity: normal status: open title: quick example how to fix docs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8904> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Would the addition of a link to http://www.python.org/dev/patches/ address your request? ---------- nosy: +merwok _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8904> _______________________________________
anatoly techtonik <techtonik@gmail.com> added the comment: On Mon, Jun 7, 2010 at 1:26 AM, Éric Araujo <report@bugs.python.org> wrote:
Would the addition of a link to http://www.python.org/dev/patches/ address your request?
No. It is not quick. It short only for an experienced developer. The example (or documentation HowTo) should be user based with explanation how to checkout, compile and test the changes. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8904> _______________________________________
Brian Curtin <curtin@acm.org> added the comment: I think what you are suggesting is outside of the scope of that document -- it appears that the page intends to be quick and strictly focused on reporting bugs, not fixing them. ---------- nosy: +brian.curtin status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8904> _______________________________________
Tal Einat <taleinat@users.sourceforge.net> added the comment: AFAIK submitting patches in general is covered well enough in several places. What I'm missing specifically regarding patches for documentation is instructions on how to preview them before submitting them. Editing reST is easy, but making sure you've done it correctly without knowing how to run it through Sphinx is impossible. I spent quite some time and couldn't figure this one out, and ended up submitting a doc patch without previewing it. To be specific, http://www.python.org/dev/contributing/ points to http://docs.python.org/dev/documenting/index.html which has quite a bit of information on reST but no information on Sphinx, despite the main page clearly stating: "This document describes the style guide for our documentation, the custom reStructuredText markup introduced to support Python documentation and how it should be used, as well as the Sphinx build system." Finally, a simple how-to with concrete, technical steps on how to write, preview and submit a doc patch would really help, especially for those who have never before submitted a patch. A simple video example (e.g. on ShowMeDo) would be fantastic, but even just updated detailed textual instructions would be a great step forward. ---------- nosy: +taleinat status: pending -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8904> _______________________________________
Georg Brandl <georg@python.org> added the comment: Hmm, I thought the Doc/README covered this? ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8904> _______________________________________
Tal Einat <taleinat@users.sourceforge.net> added the comment: Apparently so. Those instructions are thorough and to the point, just what I was looking for. Adding a mention of this somewhere obvious, such as the links I mentioned earlier, would be very helpful (this would have save me 30 minutes of futile searching). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8904> _______________________________________
Georg Brandl <georg@python.org> added the comment: Agreed. Added a "building" section to Documenting Python in r81393, will port to the other branches. ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8904> _______________________________________
participants (5)
-
anatoly techtonik -
Brian Curtin
-
Georg Brandl
-
Tal Einat
-
Éric Araujo