Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

invalid reST markup in several documents #49061

Closed
ggenellina mannequin opened this issue Jan 2, 2009 · 7 comments
Closed

invalid reST markup in several documents #49061

ggenellina mannequin opened this issue Jan 2, 2009 · 7 comments
Assignees
@birkenfeld
Labels
docs Documentation in the Doc dir

Comments

@ggenellina
Copy link
Mannequin

ggenellina mannequin commented Jan 2, 2009

BPO 4811
Nosy @birkenfeld, @akitada
Files
  • invalid-doc-markup.diff
  • suspicious.rar
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2009-01-02.20:25:38.713>
created_at = <Date 2009-01-02.20:15:18.770>
labels = ['docs']
title = 'invalid reST markup in several documents'
updated_at = <Date 2009-01-04.10:24:59.162>
user = 'https://bugs.python.org/ggenellina'

    bugs.python.org fields:

    activity = <Date 2009-01-04.10:24:59.162>
actor = 'georg.brandl'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2009-01-02.20:25:38.713>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2009-01-02.20:15:18.770>
creator = 'ggenellina'
dependencies = []
files = ['12543', '12579']
hgrepos = []
issue_num = 4811
keywords = ['patch']
message_count = 7.0
messages = ['78866', '78870', '78903', '78960', '78962', '79040', '79042']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'ggenellina', 'akitada']
pr_nums = []
priority = 'normal'
resolution = 'accepted'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue4811'
versions = ['Python 2.6', 'Python 3.0', 'Python 3.1', 'Python 2.7']
    @ggenellina
    Copy link
    Mannequin Author

    ggenellina mannequin commented Jan 2, 2009

    Several documents contain invalid reST markup that "leaks" into the
    html output (missing ``, incorrect indentation, etc.)
    This patch fixes the obvious ones.

    @ggenellina ggenellina mannequin assigned birkenfeld Jan 2, 2009
    @ggenellina ggenellina mannequin added the docs Documentation in the Doc dir label Jan 2, 2009
    @birkenfeld
    Copy link
    Member

    Many thanks! Applied in r68171.

    Did you find those yourself, or with some sort of tool?

    @ggenellina
    Copy link
    Mannequin Author

    ggenellina mannequin commented Jan 2, 2009

    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.

    @akitada
    Copy link
    Mannequin

    akitada mannequin commented Jan 3, 2009

    Could you also fix the indentation of "Queues" example code at
    http://docs.python.org/library/multiprocessing.html#exchanging-objects-between-processes
    ?

    @birkenfeld
    Copy link
    Member

    Done.

    @ggenellina
    Copy link
    Mannequin Author

    ggenellina mannequin commented Jan 4, 2009

    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 :(

    @birkenfeld
    Copy link
    Member

    Thanks very much! I've added this to the Python doc tools in r68290.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees

    @birkenfeld birkenfeld

    Labels
    docs Documentation in the Doc dir
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    1 participant
    @birkenfeld