[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 06/11] qapidoc: introduce QAPISchemaIfCond.docgen()
From: |
Markus Armbruster |
Subject: |
[PULL 06/11] qapidoc: introduce QAPISchemaIfCond.docgen() |
Date: |
Thu, 26 Aug 2021 14:32:20 +0200 |
From: Marc-André Lureau <marcandre.lureau@redhat.com>
Instead of building the condition documentation from a list of string,
use the result generated from QAPISchemaIfCond.docgen().
This changes the generated documentation from:
- COND1, COND2... (where COND1, COND2 are Literal nodes, and ',' is Text)
to:
- COND1 and COND2 (the whole string as a Literal node)
This will allow us to generate more complex conditions in the following
patches, such as "(COND1 and COND2) or COND3".
Adding back the differentiated formatting is left to the wish list.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210804083105.97531-6-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[TODO comment added]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 14 ++++++++------
scripts/qapi/common.py | 7 +++++++
scripts/qapi/schema.py | 10 +++++++++-
3 files changed, 24 insertions(+), 7 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 511520f33f..d791b59492 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -112,17 +112,19 @@ def _make_section(self, title):
def _nodes_for_ifcond(self, ifcond, with_if=True):
"""Return list of Text, literal nodes for the ifcond
- Return a list which gives text like ' (If: cond1, cond2, cond3)', where
- the conditions are in literal-text and the commas are not.
+ Return a list which gives text like ' (If: condition)'.
If with_if is False, we don't return the "(If: " and ")".
"""
- condlist = intersperse([nodes.literal('', c) for c in ifcond.ifcond],
- nodes.Text(', '))
+
+ doc = ifcond.docgen()
+ if not doc:
+ return []
+ doc = nodes.literal('', doc)
if not with_if:
- return condlist
+ return [doc]
nodelist = [nodes.Text(' ('), nodes.strong('', 'If: ')]
- nodelist.extend(condlist)
+ nodelist.append(doc)
nodelist.append(nodes.Text(')'))
return nodelist
diff --git a/scripts/qapi/common.py b/scripts/qapi/common.py
index ba9fe14e4b..ddc54e4368 100644
--- a/scripts/qapi/common.py
+++ b/scripts/qapi/common.py
@@ -205,6 +205,13 @@ def cgen_ifcond(ifcond: Union[str, List[str]]) -> str:
return '(' + ') && ('.join(ifcond) + ')'
+def docgen_ifcond(ifcond: Union[str, List[str]]) -> str:
+ # TODO Doc generated for conditions needs polish
+ if not ifcond:
+ return ''
+ return ' and '.join(ifcond)
+
+
def gen_if(cond: str) -> str:
if not cond:
return ''
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index 4ea7e88846..a9345af7b7 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -19,7 +19,12 @@
import re
from typing import Optional
-from .common import POINTER_SUFFIX, c_name, cgen_ifcond
+from .common import (
+ POINTER_SUFFIX,
+ c_name,
+ cgen_ifcond,
+ docgen_ifcond,
+)
from .error import QAPIError, QAPISemError, QAPISourceError
from .expr import check_exprs
from .parser import QAPISchemaParser
@@ -32,6 +37,9 @@ def __init__(self, ifcond=None):
def cgen(self):
return cgen_ifcond(self.ifcond)
+ def docgen(self):
+ return docgen_ifcond(self.ifcond)
+
def is_present(self):
return bool(self.ifcond)
--
2.31.1
- [PULL 00/11] QAPI patches patches for 2021-08-26, Markus Armbruster, 2021/08/26
- [PULL 01/11] qapi: Fix crash on redefinition with a different condition, Markus Armbruster, 2021/08/26
- [PULL 09/11] qapi: Use 'if': { 'any': ... } where appropriate, Markus Armbruster, 2021/08/26
- [PULL 04/11] qapi: add QAPISchemaIfCond.is_present(), Markus Armbruster, 2021/08/26
- [PULL 07/11] qapi: replace if condition list with dict {'all': [...]}, Markus Armbruster, 2021/08/26
- [PULL 06/11] qapidoc: introduce QAPISchemaIfCond.docgen(),
Markus Armbruster <=
- [PULL 02/11] docs: update the documentation upfront about schema configuration, Markus Armbruster, 2021/08/26
- [PULL 03/11] qapi: wrap Sequence[str] in an object, Markus Armbruster, 2021/08/26
- [PULL 11/11] qapi: make 'if' condition strings simple identifiers, Markus Armbruster, 2021/08/26
- [PULL 10/11] qapi: add 'not' condition operation, Markus Armbruster, 2021/08/26
- [PULL 08/11] qapi: add 'any' condition, Markus Armbruster, 2021/08/26
- [PULL 05/11] qapi: introduce QAPISchemaIfCond.cgen(), Markus Armbruster, 2021/08/26
- Re: [PULL 00/11] QAPI patches patches for 2021-08-26, Peter Maydell, 2021/08/26