[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings
From: |
Markus Armbruster |
Subject: |
Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings |
Date: |
Thu, 24 Sep 2020 17:06:41 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
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...
- Re: [PATCH 10/37] qapi/common.py: delint with pylint, (continued)
- [PATCH 12/37] qapi/common.py: check with pylint, John Snow, 2020/09/15
- [PATCH 11/37] qapi/common.py: Replace one-letter 'c' variable, John Snow, 2020/09/15
- [PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/15
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, Markus Armbruster, 2020/09/17
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/17
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, Eduardo Habkost, 2020/09/17
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/17
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings,
Markus Armbruster <=
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/24
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, Markus Armbruster, 2020/09/25
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/25
[PATCH 13/37] qapi/common.py: add notational type hints, John Snow, 2020/09/15
[PATCH 15/37] qapi/common.py: split build_params into new file, John Snow, 2020/09/15