[docs] [issue8904] quick example how to fix docs

[Tal Einat]

Tal Einat <taleinat at 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 at bugs.python.org>
<http://bugs.python.org/issue8904>
_______________________________________