Skip to content

invalid reST markup in several documents #49061

Closed
Closed
invalid reST markup in several documents#49061
Assignees
birkenfeld
Labels
docsDocumentation in the Doc dir

Description

@ggenellina
ggenellina
mannequin
opened on 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']

    Activity

    1. ggenellina commented on Jan 2, 2009

      @ggenellina
      ggenellinamannequin
      on Jan 2, 2009
      MannequinAuthor

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

    2. ggenellina
      assigned
      birkenfeld
      on Jan 2, 2009
    3. ggenellina
      added
      docsDocumentation in the Doc dir
      on Jan 2, 2009

    4. birkenfeld commented on Jan 2, 2009

      @birkenfeld
      birkenfeld
      on Jan 2, 2009
      Member

      Many thanks! Applied in r68171.

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

    5. birkenfeld
      closed this as completedon Jan 2, 2009

    6. ggenellina commented on Jan 2, 2009

      @ggenellina
      ggenellinamannequin
      on Jan 2, 2009
      MannequinAuthor

      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.

    7. akitada commented on Jan 3, 2009

      @akitada
      akitadamannequin
      on Jan 3, 2009
      Mannequin

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

    8. birkenfeld commented on Jan 3, 2009

      @birkenfeld
      birkenfeld
      on Jan 3, 2009
      Member

      Done.

    9. ggenellina commented on Jan 4, 2009

      @ggenellina
      ggenellinamannequin
      on Jan 4, 2009
      MannequinAuthor

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

    10. birkenfeld commented on Jan 4, 2009

      @birkenfeld
      birkenfeld
      on Jan 4, 2009
      Member

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

    11. ezio-melotti
      transferred this issue fromon Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    Labels

    docsDocumentation in the Doc dir

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions