John Snow <js...@redhat.com> writes: > On 9/17/20 3:14 PM, Eduardo Habkost wrote: >> On Thu, Sep 17, 2020 at 02:44:53PM -0400, John Snow wrote: >> [...] >>> Having said this, I have not found any tool to date that actually *checks* >>> these comments for consistency. The pycharm IDE interactively highlights >>> them when it senses that you have made a mistake, but that cannot be worked >>> into our CI process that I know of - it's a proprietary checker. >>> >>> So right now, they're just plaintext that I am writing to approximate the >>> Sphinx style until such time as I enable autodoc for the module and >>> fine-tune the actual formatting and so on.
You are deliberately trying to "approximate" Sphinx style, and ... >> After applying this series, I only had to make two small tweaks >> to make Sphinx + autodoc happy with the docstrings you wrote. >> With the following patch, "make sphinxdocs" will generate the >> QAPI Python module documentation at docs/devel/qapi.html. >> I had to explicitly skip qapi/doc.py because autodoc thinks the >> string constants are documentation strings. >> > > Awesome! ... actually almost nail it. Please mention your choice of style in the commit message. > I think I am going to delay explicitly pursuing writing a manual for > the QAPI parser for now, but it's good to know I am not too far > off. I'm going to target the mypy conversions first, because they can > be invasive and full of churn. > > When I get there, though ... I am thinking I should add this as > Devel/QAPI Parser. Doing "actually Sphinx style" instead of "an approximation of Sphinx style" would reduce churn later on. So, if it's not too distracting...
