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

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

On Sun, Jan 1, 2017 at 1:59 PM, Guenter Milde <mi...@us...> wrote:
> On 2016-12-31, Jean Baptiste Favre wrote:
>> Hello,
>> I'm facing an issue with Trafficserver documentation [1] which doesn't
>> build with docutils 0.13.1
>
>> Error comes from a custom Inliner class which is defined in doc/conf.py
>> of Trafficserver project(starting line 163).
>> This allow to transform text like "(TS-XXXX)" in a link to
>> trafficserver's Jira
>
>> This custom Inliner used to work with docutils 0.12. It fails on 0.13.1
>> with following error:
>
>>   Exception occurred:
>>     File "conf.py", line 185, in __init__
>>       start_string_prefix=self.start_string_prefix,
>>   AttributeError: Inliner instance has no attribute 'start_string_prefix'
>
>> Since docutils 0.13, start_string_prefix isn't statically defined. We
>> have to call init_customiations for that.
>
> Yes, this changed with the implementation of the long expected feature
>
>   - Apply [ 103 ] Recognize inline markups without word boundaries.
>
> and the new configuration setting "character_level_inline_markup".

This is another example of an API change coming back to bite us.

>> First problem: one  must pass settings param when calling
>> init_customizations, but I can't find any format or structure for it.
>
>> Second problem: I tried a workaround, creating a InlinerSettings class
>> with minimal properties so that init_customizations could pass:
>
>>   class InlinerSettings:
>>     character_level_inline_markup=None
>>     pep_references=None
>>     rfc_references=None
>
>> But, then, I faced another error:
>
> ...
>
> "settings" is a an object returned from the option parser (optparse module).
>
> There are others facing similar problems, e.g. Python distutils.
> There, I learned the trick is to use
>
>   settings = frontend.OptionParser(components=(Parser,)).get_default_values()
>
>   -- https://hg.python.org/cpython/rev/db09d760b965

I think in this case, this is a red herring (a false issue). It's not
the cause of the problem.

>> Third problem: since the above tries didn't worked, I'd a look on custom
>> directives and roles.
>> But, it does not seems to be allowed to define a role with a custom regex.
>> This would means I have to rewrite all "(TS-XXXX)" expression into ":TS:
>> XXXX".
>
> This is the "minimal-invasive" approach, it would be work now but might save
> issues later, as it depends less on Docutils internals.
>
>> Is there any way to achieve the migration in a compatible way with
>> docutils 0.12 *and* without rewriting the docuemntation ?
>
> If the above example does not lead to a solution, you could also consider to
> copy the definition of start_string_prefix ...
> from states.py (importing utils.punctuation_chars first)

Or we could fix our mistake. I think that's better.

David Goodger
<http://python.net/~goodger>