Sphinx Documentation Generator's Option Parser

Richard Wilbur richard.wilbur at gmail.com
Wed Jun 22 23:18:48 UTC 2016

Anybody have experience creating documentation with Sphinx?  I am
trying to clean up errors and warnings in the bzr documentation build
and Sphinx has trouble with some of our constructs.

The 'storage formats' list (which appears in several places, I'm
presently doing battle with it in the colo plugin documentation) has
entries which name (as an option) and describe each possible storage
format.[*]  Sphinx recognizes most of these as options, but when one
of the names includes the period character, '.', Sphinx changes its
mind about that one and decides there is an error in the indentation
scheme because it no longer considers it an option.


These fail.  But if I change just the '.' period into a character such as '_',


they work fine!

Does anyone have experience working around this issue with the Sphinx
option name parser?

Maybe I need to override the Sphinx option name parser for this
documentation?  Anybody have experience doing that?


[*]  The code refers to the options in
lp:bzr-colo:commands.py:L151,L263 where it instantiates
option.RegistryOption('format', lazy_registry=('bzrlib.bzrdir',
'format_registry'), title="Storage Format", )

More information about the bazaar mailing list