Looks like this module is under development. I'd suggest looking at the github repository, and maybe raising an issue.
https://github.com/ribozz/sphinx-argparse
In sphinarg/ext.py
, the description
is formatted with docutils.nodes.paragraph
. Same with the epilog
. usage
on the other hand usesnodes.literal_block
.
================
After playing around with docutils
I suspect the description is entered into the doctree
as
<paragraph>
Fancy *argparse* description
...
This is an attempt to use fancier formatting....
</paragraph>
which ends up in the html
as
<p>
Fancy *argparse* description
...
</p>
It retains all the original whitespace, but the browser renders it as single wrapped paragraph block.
To preserve whitespace, and to act on things like emphasis and bullets, it needs to be passed through a reader and/or parser. Then its portion of the doctree
will look more like:
<paragraph>Fancy <emphasis>argparse</emphasis> description</paragraph>...
<paragraph>This is an attempt to use fancier formatting. ....</paragraph>
I can do this in a standalone script with:
docutils.core.publish_doctree(description)
but I don't how it could be done in sphinx-argparse
.
In effect, sphinx-argparse
treats the description as a simple paragraph, in the same spirit as the default HelpFormatter
.