Sphinx Documentation Generator's Option Parser

[Vincent Ladeuil]

>>>>> Richard Wilbur <richard.wilbur at gmail.com> writes:

    > 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 = \
    > re.compile(r'((?:/|-|--)?[-_a-zA-Z0-9.]+)(\s*.*)')

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

docutils... now /that/ rings a bell !

vila at saw:~/src/bzr/trunk 0 :) $ bzr diff -c 3546
=== modified file 'tools/rst2html.py'
--- tools/rst2html.py	2007-12-07 06:56:37 +0000
+++ tools/rst2html.py	2008-07-17 01:08:21 +0000
@@ -19,8 +19,7 @@
 import docutils
 from docutils.core import publish_cmdline, default_description
 
-
-if docutils.__version__ <= '0.4.1':
+if True: # this is still required in the distutils trunk as-at June 2008.
     from docutils.parsers.rst.states import Body
     # we have some option names that contain dot; which is not allowed by
     # python-docutils 0.4-4 -- so monkeypatch in a better pattern

which leads to:

import docutils
from docutils.core import publish_cmdline, default_description

if True: # this is still required in the distutils trunk as-at June 2008.
    from docutils.parsers.rst.states import Body
    # we have some option names that contain dot; which is not allowed by
    # python-docutils 0.4-4 -- so monkeypatch in a better pattern
    #
    # This is a bit gross to patch because all this is built up at load time.
    Body.pats['optname'] = r'[a-zA-Z0-9][a-zA-Z0-9._-]*'    
    Body.pats['longopt'] = r'(--|/)%(optname)s([ =]%(optarg)s)?' % Body.pats
    Body.pats['option'] = r'(%(shortopt)s|%(longopt)s)' % Body.pats
    Body.patterns['option_marker'] = r'%(option)s(, %(option)s)*(  +| ?$)' % Body.pats

Note:

    # This is a bit gross to patch because all this is built up at load time.

which may explain why your monkeypatch is not  enough.

Hope this helps,

     Vincent

P.S.: If that works, it may be worth engaging with docutils upstream to
  support '.' out of the box. This has been invalid since at least 2008
  so nobody can be using it without running into errors. I doubt anybody
  /relies/ on the triggered error ?