| Message ID | 20200930043150.1454766-5-jsnow@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: static typing conversion, pt1 | expand |
John Snow <jsnow@redhat.com> writes: > I did not say "sphinx beautiful", just "sphinx compatible". They will > not throw errors when parsed and interpreted as ReST. "Bang on the keyboard until Sphinx doesn't throw errors anymore" might be good enough for a certain kind of mathematician, but a constructive solution needs a bit more direction. Is there a specification to follow? Other useful resources? > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > scripts/qapi/gen.py | 6 ++++-- > scripts/qapi/parser.py | 9 +++++---- > 2 files changed, 9 insertions(+), 6 deletions(-) > > diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py > index ca66c82b5b8..fc19b2aeb9b 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` and `end_if`. Sadly, the fact that start_if() and end_if() are functions isn't immediately obvious anymore. I've seen :func:`start_if` elsewhere. Is this something we should or want to use? > > - *args: any number of QAPIGenCCode > + :param ifcond: List of conditionals > + :param args: any number of `QAPIGenCCode`. > > Example:: > > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py > index 9d1a3e2eea9..02983979965 100644 > --- a/scripts/qapi/parser.py > +++ b/scripts/qapi/parser.py > @@ -381,10 +381,11 @@ 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 > - * An additional section: ._append_line is ._append_various_line > + > + * 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 > + * An additional section: ._append_line is ._append_various_line > """ > line = line[1:] > if not line: I understand why you insert a blank line (reST wants blank lines around lists), I don't understand why you indent. Can you explain?
diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py index ca66c82b5b8..fc19b2aeb9b 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` and `end_if`. - *args: any number of QAPIGenCCode + :param ifcond: List of conditionals + :param args: any number of `QAPIGenCCode`. Example:: diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 9d1a3e2eea9..02983979965 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -381,10 +381,11 @@ 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 - * An additional section: ._append_line is ._append_various_line + + * 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 + * An additional section: ._append_line is ._append_various_line """ line = line[1:] if not line:
I did not say "sphinx beautiful", just "sphinx compatible". They will not throw errors when parsed and interpreted as ReST. Signed-off-by: John Snow <jsnow@redhat.com> --- scripts/qapi/gen.py | 6 ++++-- scripts/qapi/parser.py | 9 +++++---- 2 files changed, 9 insertions(+), 6 deletions(-)