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

[Guenter M. <mi...@us...>]

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".


> 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


> 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)

Günter