ReStructuredText formatting does not work with sphinx.argparse

[jbloom]

sphinx-argparse allows extending the results of argparse directives as described here.

But when using alabaster, any formatting (for instance, putting text in bold) is lost.

[bitprophet]

Can you provide some examples (ideally including the outputted HTML) of this behavior in some other Sphinx theme (any where the formatting is preserved) vs alabaster? May make it clearer what's going on. I can't say offhand why this would be happening. Thanks! If we're lucky it'll just be a styling rule we can tweak...will have to see.

[jbloom]

I have attached a screenshot of how it looks in Alabaster.

In this image, the --alignspecs should be in literal text in the section where this is described, and the Barcoded subamplicon sequencing should be an RST link.

However, in answer to your other query, I went back and looked at some of my other documentation build using other Sphinx themes (e.g., http://jbloomlab.github.io/phydms/phydms_prog.html). I noticed that the formatting is also lost there! I am virtually positive that I used to get good formatting in earlier documentation builds with these other Sphinx themes, although I can't be positive because I don't version track the HTML builds...

So I guess this fact suggests that the problem might be an issue with either Sphinx or sphinx-argparse -- probably a new issue if my memory is correct that the problem used to not exist.

So I guess feel free to close this issue if you think the problem lies with sphinx, and I'll try raising it there instead.

[bitprophet]

Yea, that's why I asked, because I couldn't see an obvious way in which it's technically "our" fault.

That said, it could still very well be a (long-standing) deficiency in Sphinx's default theme/s' CSS stylesheets (one that we presumably share), so it's possible we can still fix it here.

Quickly peeped the docs you linked & their show-source (God bless that feature of Sphinx) and found a concrete example with the HTML in question (I'd meant the actual HTML, not the render of the HTML, originally :D).

Sphinx source:

.. argparse::
   :module: parsearguments
   :func: PhyDMSParser
   :prog: phydms

   alignment
    Should contain aligned DNA codon sequences.
    Stop codons are **not** allowed, except if a stop codon is the terminal character in all sequences, in which case they are automatically trimmed.

Resulting HTML:

<table class="docutils option-list" frame="void" rules="none">
<colgroup><col class="option">
<col class="description">
</colgroup><tbody valign="top">
<tr><td class="option-group">
<kbd>alignment</kbd></td>
<td><p class="first">Existing FASTA file with aligned codon sequences.</p>
<p>Should contain aligned DNA codon sequences.
Stop codons are not allowed, except if a stop codon is the terminal character in all sequences, in which case they are automatically trimmed.</p>

So, Sphinx (or sphinx-argparse?) is apparently stripping out some (at least inline-type) ReST syntax somewhere between the on-disk source & expression of the table.option-list - note how "stop codons are not allowed" has no tags whatsoever, when it should have some <strong> or whatnot.

I'd actually guess it's a bug in sphinx-argparse, since it is (presumably) what's responsible for hanging out in the middle of Sphinx's transformation sequence and changing how .. argparse:: directives get turned into render-oriented node-tree objects (in our case, they typically map 1:1 onto HTML tags, and clearly there is no node for the bolded word by the time the HTML render gets ahold of things.)

(I don't normally like passing the buck, but don't think there's anything I can do on this end after all, since there's no HTML tags for my CSS to style...)

ETA: I'm OK leaving this open until someone can verify my guess, though.

[iamjackg]

This was indeed an issue sphinx-argparse. It's being fixed in the next release!

See: alex-rudakov/sphinx-argparse#86