Sphinx Documentation Generator's Option Parser

Richard Wilbur richard.wilbur at gmail.com
Fri Jun 24 18:20:56 UTC 2016

Through my reading I found that I don't need to escape metacharacters
in character classes so the correct version is:

import sphinx.domains.std
import re

sphinx.domains.std.option_desc_re = \

But it turns out this doesn't help us at all because the real option
parser lives in docutils!

So when I make the following change, it works!!  Add '.' after '9' in
the 'alphanumplus' pattern which is used in the 'optname' pattern.

    pats['alphanumplus'] = '[a-zA-Z0-9._-]'

But when I add the following lines to plugins/en/conf.py instead of
changing docutils source code directly, no success--so far.

import docutils.parsers.rst.states

# Allow '.' (period character) in option names.
docutils.parsers.rst.states.Body.pats['alphanumplus'] = '[a-zA-Z0-9._-]'
docutils.parsers.rst.states.Body.pats['optname'] = \
'%(alphanum)s%(alphanumplus)s*' % docutils.parsers.rst.states.Body.pats

It looks like it comes down to a question of whether sphinx executes
conf.py as part of the sphinx application at run-time or not.  If so,
there may be a way to have the desired effect on the docutils parser
from our project configuration.  If not, we may need to write a sphinx
extension that does this.

Ideas?  Wisdom?


More information about the bazaar mailing list