How to interpret "description" as restructured text in sphinx argparse or autoprogram?

Question

I have been using sphinx argparse and sphinx autoprogramm modules to scrape command-line descriptors from python script using the argparse module. The output is generally fine but the "description" part of the script is being parsed as a single paragraph of text. Is there some way of throwing this through a reST interpreter or something like that so it at least preserves the whitespace bewteen paragraphs?

Answer 1

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.