John Snow <jsnow@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...