Re: [Docutils-users] Migration docutils 0.12 to 0.13

[Jean B. F. <web...@jb...>]

Hello David,

On 03/01/2017 01:15, David Goodger wrote:
> On Mon, Jan 2, 2017 at 5:03 PM, Jean Baptiste Favre
> <web...@jb...> wrote:
>> Still have the same error.
>> The full traceback is attached, sorry to have forgotten it before.
>>
>> My subclass is as follow:
>>
>> from docutils import nodes
>> from docutils.parsers.rst import states
>> from docutils.utils import unescape
>>
>> # Customize parser.inliner in the only way that Sphinx supports.
>> # docutils.parsers.rst.Parser takes an instance of states.Inliner or a
>> # subclass but Sphinx initializes it from
>> # SphinxStandaloneReader.set_parser('restructuredtext') which is called
>> # from Publisher.set_components() and initializes the parser without
>> # arguments.
>>
>> BaseInliner = states.Inliner
>> class Inliner(BaseInliner):
>>
>>   def init_customizations(self, settings):
>>     BaseInliner.init_customizations(self, settings)
>>
>>     issue_pattern = re.compile(u'''
>>       {start_string_prefix}
>>       TS-\d+
>>       {end_string_suffix}'''.format(
>>         start_string_prefix=self.start_string_prefix,
>>         end_string_suffix=self.end_string_suffix),
>>       re.VERBOSE | re.UNICODE)
>>
>>     self.implicit_dispatch.append((issue_pattern, self.issue_reference))
>>
>>   def issue_reference(self, match, lineno):
>>     text = match.group(0)
>>
>>     rawsource = unescape(text, True)
>>     text = unescape(text, False)
>>
>>     refuri = 'https://issues.apache.org/jira/browse/' + text
>>
>>     return [nodes.reference(rawsource, text, refuri=refuri)]
>>
>> states.Inliner = Inliner
> 
> That last line is the culprit. You're monkey-patching Docutils. Don't
> do that. If something in Docutils breaks as a result, you can't
> reasonably complain. If it worked before, it was just accidental.

To make everything clear, I'm *not* the original author of this code,
but I completely agree with you :)

I'm "just" trying to fix trafficserver build against docutils 0.13.1 so
that trafficserver package isn't removed from Debian archive (stable
freeze is coming).
Right now, I only have 2 week left to make the build works in Debian.

> I distilled the issue down, see the attached x.py & y.py. Put them on
> your PYTHONPATH so y.py can import x.py. Run y.py. Note the output.
> Now edit y.py and uncomment the commented line (the monkey patch). Now
> run y.py again, and note the difference in the output. The monkey
> patch messes up the namespace hierarchy, so x.A.run doesn't have
> access to x.attr_x anymore.
> 
> Wasn't there another version of this code that worked in a different way?

I tried many things which never worked.

I finally get the build working with method level monkey patch as well
as your own patch Inliner8009.patch.

But, since a successful build requires docutils to be updated, I'll
suggest to trafficserver devs to change the way it works and use the
classic docutils role way, which will be more stable.

> Maybe you can monkey patch at the method level instead of the class
> level. I.e. inject your methods into the existing Docutils Inliner
> class, instead of replacing the class with your subclass. See z.py.
> Caveat: monkey patching is dangerous. Even if this works now, I can't
> guarantee that it will always work.
> You're trying to do this through Sphinx, which isn't configurable, as
> the comment in https://github.com/apache/trafficserver/blob/master/doc/conf.py
> describes:
> 
> # Customize parser.inliner in the only way that Sphinx supports.
> # docutils.parsers.rst.Parser takes an instance of states.Inliner or a
> # subclass but Sphinx initializes it from
> # SphinxStandaloneReader.set_parser('restructuredtext') which is called
> # from Publisher.set_components() and initializes the parser without
> # arguments.
> 
> Perhaps you should complain to Sphinx, and ask them to enable
> configurability. If your code was using Docutils directly this
> wouldn't be an issue (or would be less of an issue).

Which shouldn't be needed if trafficserver switch to classic docutils roles.

Thanks for your help and patience, I've learned a lot !

Cheers,
Jean Baptiste Favre