classification
Title: invalid reST markup in several documents
Type: Stage:
Components: Documentation Versions: Python 3.0, Python 3.1, Python 2.7, Python 2.6
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: akitada, georg.brandl, ggenellina
Priority: normal Keywords: patch

Created on 2009-01-02 20:15 by ggenellina, last changed 2009-01-04 10:24 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
invalid-doc-markup.diff ggenellina, 2009-01-02 20:15
suspicious.rar ggenellina, 2009-01-04 08:56
Messages (7)
msg78866 - (view) Author: Gabriel Genellina (ggenellina) Date: 2009-01-02 20:15
Several documents contain invalid reST markup that "leaks" into the 
html output (missing ``, incorrect indentation, etc.)
This patch fixes the obvious ones.
msg78870 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-01-02 20:25
Many thanks! Applied in r68171.

Did you find those yourself, or with some sort of tool?
msg78903 - (view) Author: Gabriel Genellina (ggenellina) Date: 2009-01-02 23:36
I did a search on the .html files using a regular expression, and 
manually filtered out the false positives.
The expression used was this "::[^=]|:[a-zA-Z][a-zA-Z0-9]+|`|\.\.\s*\w
+:"
I'll try to come up with a useable tool.
msg78960 - (view) Author: Akira Kitada (akitada) * Date: 2009-01-03 14:21
Could you also fix the indentation of "Queues" example code at
http://docs.python.org/library/multiprocessing.html#exchanging-objects-between-processes
?
msg78962 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-01-03 14:30
Done.
msg79040 - (view) Author: Gabriel Genellina (ggenellina) Date: 2009-01-04 07:19
This patch includes some (sort of) checker for suspicious constructs 
that resembles markup that has leaked into the final output.

It's a new Builder for Sphinx, and works with the docutils nodes, not 
the source files directly.

"doc-Makefile.diff" updates both make.bat and the Makefile, adding a 
new target "suspicious".

The "ignored.csv" file contains the rules to discard false positives.

"builder.diff" updates builder.py in Sphinx, adding a new builder 
implemented in suspicious.py; the source code has some comments 
explaining how it's used.

Execute `make suspicious`, a "suspicious.csv" file is created in build/
suspicious containing one line per issue found.

Currently, the only relevant message I get is about the :makevar: role 
usage in c-api/init.rst -- looks like docutils doesn't properly 
processes it.

There is something I don't like in the code -- suspicious.py is 
generic, lives inside the Sphinx directory, but knows not to process 
the "documenting" directory inside Python [there are too much false 
positives there -- most of the examples contain actual reST markup]. 
But I don't know enough of Sphinx to make it better :(
msg79042 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-01-04 10:24
Thanks very much! I've added this to the Python doc tools in r68290.
History
Date User Action Args
2009-01-04 10:24:59georg.brandlsetmessages: + msg79042
2009-01-04 08:56:11ggenellinasetfiles: + suspicious.rar
2009-01-04 07:19:52ggenellinasetmessages: + msg79040
2009-01-03 14:30:02georg.brandlsetmessages: + msg78962
2009-01-03 14:21:31akitadasetnosy: + akitada
messages: + msg78960
2009-01-02 23:36:49ggenellinasetmessages: + msg78903
2009-01-02 20:25:38georg.brandlsetstatus: open -> closed
resolution: accepted
messages: + msg78870
2009-01-02 20:15:18ggenellinacreate