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

python setup.py check --restructuredtext --strict --metadata fails with warning: check: Could not finish the parsing. if the RST document uses code or code-block directives. [SF:bugs:270] #343

Closed
chrisjsewell opened this issue Aug 9, 2020 · 0 comments
Closed

python setup.py check --restructuredtext --strict --metadata fails with warning: check: Could not finish the parsing. if the RST document uses code or code-block directives. [SF:bugs:270] #343

chrisjsewell opened this issue Aug 9, 2020 · 0 comments
Labels
bugs closed-fixed priority-3

Comments

@chrisjsewell
Copy link
Owner

author: msabramo
created: 2014-12-15 19:39:10.826000
assigned: None
SF_url: https://sourceforge.net/p/docutils/bugs/270

python setup.py check --restructuredtext --strict --metadata fails with:

warning: check: Could not finish the parsing.

if the RST document uses code or code-block directives.

This is annoying because the document is valid, but it appears to be invalid
and confuses people. For example, see
ionelmc/pytest-benchmark#4 (comment)

How to reproduce this bug

Clone a repo that has a README.rst with code-block directives in it. E.g.:

$ git clone [email protected]:ionelmc/pytest-benchmark.git
$ cd pytest-benchmark
$ git checkout ab0b08f6fccb06a7909905a8409f8faa8b01e0d8

Observe that it has "code-blocks" in it:

   $ grep 'code-block' README.rst
   .. code-block:: python
   .. code-block:: python

Observe that RST document is valid, according to rst2html.py:

   $ rst2html.py --halt=1 README.rst > README.html && echo "RST was OK."
   RST was OK.

   $ head -n 3 README.html
   <?xml version="1.0" encoding="utf-8" ?>
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

Observe that python setup.py check --restructuredtext --strict --metadata fails:

$ python setup.py check --restructuredtext --strict --metadata
running check
warning: check: Could not finish the parsing.

error: Please correct your package.

$ echo $?
1

What was expected: python setup.py check --restructuredtext --strict --metadata should succeed with no warnings, just as rst2html.py did, because
README.rst is a valid RST document.

What actually happened: python setup.py check --restructuredtext --strict --metadata prints a warning and an error and fails, unlike rst2html.py

The error is coming from here:
https://github.com/python/cpython/blob/master/Lib/distutils/command/check.py#L142

It's happening because of this line:
https://github.com/python/cpython/blob/master/Lib/distutils/command/check.py#L125

:::python
settings = frontend.OptionParser().get_default_values()

If this is changed to:

:::python
settings = frontend.OptionParser(components=(Parser,)).get_default_values()

then things work much better (this is how tools/quicktest.py does it for example)

so this might actually be a bug in distutils, but changing CPython (and maybe PyPy) is a more laborious and slow process, so I'm thinking it might be nice to work around this in docutils, if isn't too much of a burden. Docutils is on a much shorter release cycle than CPython, so changing docutils is a way to get this fix out to users much faster.

Here's a patch to docutils that solves the problem for me:

diff --git a/docutils/frontend.py.2014-12-15-070721 b/docutils/frontend.py
index f837c62..7427e15 100644
--- a/docutils/frontend.py.2014-12-15-070721
+++ b/docutils/frontend.py
@@ -41,6 +41,7 @@ import docutils
 import docutils.utils
 import docutils.nodes
 from docutils.utils.error_reporting import locale_encoding, ErrorOutput, ErrorString
+from docutils.parsers import Parser


 def store_multiple(option, opt, value, parser, *args, **kwargs):
@@ -561,7 +562,20 @@ class OptionParser(optparse.OptionParser, docutils.SettingsSpec):
             self.version = self.version_template
         # Make an instance copy (it will be modified):
         self.relative_path_settings = list(self.relative_path_settings)
+        from docutils.parsers.rst import Parser
         self.components = (self,) + tuple(components)
+
+        # distutils.command.check does:
+        # settings = frontend.OptionParser().get_default_values()
+        # and as a result is missing important defaults like
+        # `syntax_highlight`, causing
+        # `python setup.py check --restructuredtext --strict --metadata` to
+        # fail with `warning: check: Could not finish the parsing.` if the RST
+        # document uses `code` or `code-block` directives.
+        if len(self.components) == 1:
+            from docutils.parsers.rst import Parser
+            self.components += (Parser,)
+
         self.populate_from_components(self.components)
         self.set_defaults_from_dict(defaults or {})
         if read_config_files and not self.defaults['_disable_config']:

commenter: msabramo
posted: 2014-12-15 19:44:13.491000
title: #270 python setup.py check --restructuredtext --strict --metadata fails with warning: check: Could not finish the parsing. if the RST document uses code or code-block directives.

attachments:

Attaching bug_270.patch, a patch to docutils that fixes this issue ...

commenter: msabramo
posted: 2014-12-16 22:16:48.029000
title: #270 python setup.py check --restructuredtext --strict --metadata fails with warning: check: Could not finish the parsing. if the RST document uses code or code-block directives.

attachments:

After some discussion on the mailing list with David Goodger, I am revising this a bit. He wanted it to check that it was being called by docutils before messing with anything.

commenter: msabramo
posted: 2014-12-17 06:33:23.387000
title: #270 python setup.py check --restructuredtext --strict --metadata fails with warning: check: Could not finish the parsing. if the RST document uses code or code-block directives.

I also created a Python issue (and patch) for this:

http://bugs.python.org/issue23063

but it would be nice still to add a workaround to docutils, so that folks don't need Python 3.5 for this to work.

commenter: msabramo
posted: 2014-12-17 06:48:15.816000
title: #270 python setup.py check --restructuredtext --strict --metadata fails with warning: check: Could not finish the parsing. if the RST document uses code or code-block directives.

I also created a branch and pull request on GitHub for this, in case folks find that easier to read and pull from:

msabramo/docutils#1

commenter: milde
posted: 2015-02-16 22:54:20.626000
title: #270 python setup.py check --restructuredtext --strict --metadata fails with warning: check: Could not finish the parsing. if the RST document uses code or code-block directives.

  • status: open --> closed-fixed

commenter: milde
posted: 2015-02-16 22:54:21.433000
title: #270 python setup.py check --restructuredtext --strict --metadata fails with warning: check: Could not finish the parsing. if the RST document uses code or code-block directives.

It seems like this is fixed upstream now (no need to wait for 3.5):
http://bugs.python.org/msg234051

Thank you for the report(s), analysis, patch, and patience.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bugs closed-fixed priority-3
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@chrisjsewell