John Snow <js...@redhat.com> writes: > A precise style guide and a package-wide overhaul is forthcoming pending > further discussion and consensus. At present, we are avoiding obvious > errors that cause sphinx documentation build problems. > > A preliminary style guide is loosely based on PEP 257 and Sphinx > Autodoc. It is chosen for interoperability with our existing Sphinx > framework, and because it has loose recognition in the Pycharm IDE. > > - Use Triple-double quotes ("""). > - Opening and closing quotes appear on their own lines for multi-line docs. > - A single-sentence summary should be the first line of the docstring. > - A blank line follows. > - Further prose, if needed, is written next and can be multiple paragraphs, > contain RST markup, etc. > - The :param x: desc, :returns: desc, and :raises z: desc info fields follow.
Mandatory when they apply? > - Additional examples, diagrams, or other metadata follows below. > > See also: > > https://www.python.org/dev/peps/pep-0257/ > https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists > Signed-off-by: John Snow <js...@redhat.com> > --- > scripts/qapi/gen.py | 6 ++++-- > scripts/qapi/parser.py | 1 + > 2 files changed, 5 insertions(+), 2 deletions(-) > > diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py > index ca66c82b5b8..dc7b94aa115 100644 > --- a/scripts/qapi/gen.py > +++ b/scripts/qapi/gen.py > @@ -154,9 +154,11 @@ def _bottom(self): > > @contextmanager > def ifcontext(ifcond, *args): > - """A 'with' statement context manager to wrap with start_if()/end_if() > + """ > + A with-statement context manager that wraps with `start_if()` / > `end_if()`. > > - *args: any number of QAPIGenCCode > + :param ifcond: A list of conditionals, passed to `start_if()`. > + :param args: any number of `QAPIGenCCode`. > > Example:: > > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py > index 9d1a3e2eea9..31bc2e6dca9 100644 > --- a/scripts/qapi/parser.py > +++ b/scripts/qapi/parser.py > @@ -381,6 +381,7 @@ def append(self, line): > > The way that the line is dealt with depends on which part of > the documentation we're parsing right now: > + > * The body section: ._append_line is ._append_body_line > * An argument section: ._append_line is ._append_args_line > * A features section: ._append_line is ._append_features_line I'm asking because you're not adding :param line: here. Same for several other functions in this file. In schema.py: class QAPISchemaMember: """ Represents object members, enum members and features """ Are the spaces next to """ okay?