[Docutils-users] Migration docutils 0.12 to 0.13

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

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.

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:

  Exception occurred:
    File
"/usr/lib/python2.7/dist-packages/docutils/parsers/rst/states.py", line
530, in init_customizations
      """ % args, re.VERBOSE | re.UNICODE),
  KeyError: 'non_unescaped_whitespace_escape_before'

It doesn't seem to be the right way to achieve it.

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

Is there any way to achieve the migration in a compatible way with
docutils 0.12 *and* without rewriting the docuemntation ?

Cheers,
Jean Baptiste Favre

[1]: https://github.com/apache/trafficserver/tree/master/doc