Re: [Docutils-users] python setup.py check --restructuredtext --strict --metadata fails for valid document with syntax highlighting

[David G. <go...@py...>]

[CC'ing to Docutils-users. Please "reply-all", not just to me.]

On Tue, Dec 16, 2014 at 10:12 AM, Marc Abramowitz <msa...@gm...> wrote:
> First off, thanks David, for taking the time to respond!
>
>> "code-block" is not a standard Docutils reST directive
>
> Apologies. I'm not too familiar with docutils proper so I may have confused
> docutils with Sphinx. But does the following not mean that "code-block" is
> an alias for "code"?
>
> *
> https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/parsers/rst/languages/en.py

You're right, my apologies. I forgot to look there for aliases, and
forgot that "code-block" is standard. Please ignore that part.

>> It makes assumptions that may not always be true
>
> Yeah, this is my first time touching docutils so I am not surprised. I'm
> willing to work on it though. Do you think that if you were specific about
> what those assumptions are that the patch could be made to be acceptable?

It would have to be *really* specific. E.g., Docutils would have to
check that it was called by distutils only.

The problem in your patch is, you're introducing a dependency on the
stock RST parser, and client code might be using an alternate parser
(modified, or different) or none. I don't want to screw 3rd-party code
that uses Docutils, just to fix Python's bug. This smells kludgey.

I don't understand why the issue is happening. Maybe it is a Docutils
bug, I don't know.

> Or
> is there nothing that can be done on the docutils side, because...
>
>> If the bug is in Python's distutils, that's where the fix should be
>
> Yes, I agree in principle and I mentioned in the sourceforge ticket that
> this might be more of a distutils problem. The thing is that even if we
> correct the problem in distutils (which I think is present at least as far
> back as Python 2.7 and as recent as Python 3.4), it won't be available to
> users until Python 3.5 is released and it will only be available to Python 3
> users; Python 2 folks will be out of luck. So while I agree that fixing the
> problem in distutils might be the more correct approach, I'm also thinking
> about "practicality beats purity".
>
> That said, I did submit a patch to CPython at
> http://bugs.python.org/issue23063 and I'll try to push that through, but
> like I said, it will only be for Python 3.5 I think. Whereas if we can do
> something in docutils, then folks can easily upgrade docutils and be able to
> validate more of their RST documents.

Maybe somebody else can investigate. I don't have much time for
Docutils these days.

David Goodger



> On Tue, Dec 16, 2014 at 7:13 AM, David Goodger <go...@py...> wrote:
>>
>> On Mon, Dec 15, 2014 at 2:46 PM, Marc Abramowitz <msa...@gm...>
>> wrote:
>> > 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.
>> >
>> > I filed a ticket for this (with a patch included):
>> >
>> > https://sourceforge.net/p/docutils/bugs/270/
>>
>> "code-block" is not a standard Docutils reST directive, so I don't see
>> how the document could be valid. "code-block" should always break.
>> Maybe it's a Sphinx extension, and your environment has that
>> installed. Did you try with just the "code" directive?
>>
>> -1 on the patch. It makes assumptions that may not always be true. If
>> the bug is in Python's distutils, that's where the fix should be. But
>> first, make sure your document is truly valid.
>>
>> --
>> David Goodger <http://python.net/~goodger>