Migration docutils 0.12 to 0.13

Jean Baptiste Favre <[email protected]>
Newsgroups gmane.text.docutils.user
Message-ID <[email protected]>
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

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
lmpx.com only provides a reader for public news (NNTP) servers. It is not affiliated with the servers or forums shown here and is not responsible for the content of articles, which is written by their respective authors.