| Message ID | 20250311034303.75779-59-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Add new QAPI transmogrifier | expand |
John Snow <jsnow@redhat.com> writes: > Presently, we never have any empty text entries for members. The next > patch will explicitly generate such sections, so enable support for it > in advance. > > The parser will generate placeholder sections to indicate undocumented > members, but it's the qapidoc generator that's responsible for deciding > what to do with that stub section. > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > docs/sphinx/qapidoc.py | 5 +++-- > 1 file changed, 3 insertions(+), 2 deletions(-) > > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py > index 7c5a08958d5..604ab109a19 100644 > --- a/docs/sphinx/qapidoc.py > +++ b/docs/sphinx/qapidoc.py > @@ -233,11 +233,12 @@ def visit_member(self, section: QAPIDoc.ArgSection) -> None: > # TODO: features for members (documented at entity-level, > # but sometimes defined per-member. Should we add such > # information to member descriptions when we can?) > - assert section.text and section.member > + assert section.member > self.generate_field( > self.member_field_type, > section.member, > - section.text, > + # TODO drop fallbacks when undocumented members are outlawed > + section.text if section.text else "Not Documented.", I'm changing this to "Not documented" to obey English capitalization rules. > section.info, > )
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 7c5a08958d5..604ab109a19 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -233,11 +233,12 @@ def visit_member(self, section: QAPIDoc.ArgSection) -> None: # TODO: features for members (documented at entity-level, # but sometimes defined per-member. Should we add such # information to member descriptions when we can?) - assert section.text and section.member + assert section.member self.generate_field( self.member_field_type, section.member, - section.text, + # TODO drop fallbacks when undocumented members are outlawed + section.text if section.text else "Not Documented.", section.info, )
Presently, we never have any empty text entries for members. The next patch will explicitly generate such sections, so enable support for it in advance. The parser will generate placeholder sections to indicate undocumented members, but it's the qapidoc generator that's responsible for deciding what to do with that stub section. Signed-off-by: John Snow <jsnow@redhat.com> --- docs/sphinx/qapidoc.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)