From 12637df59055939f1872304e7c795f5fad3f2f67 Mon Sep 17 00:00:00 2001
From: Andrea Spadaccini <spadaccio@google.com>
Date: Thu, 6 Oct 2011 20:19:43 +0100
Subject: [PATCH] Generalize docpp and sphinx_ext
autotools/docpp
* handle generic custom directives in the form <class>_<kind>
* adapt handling of query fields
build/sphinx_ext.py
* add the BuildValuesDoc function to output definitions using the sphinx
syntax that was already used for query fields
* adapt BuildQueryFields to use BuildValuesDoc
Signed-off-by: Andrea Spadaccini <spadaccio@google.com>
Reviewed-by: Michael Hanselmann <hansmi@google.com>
---
autotools/docpp | 13 +++++++++----
lib/build/sphinx_ext.py | 21 ++++++++++++++++-----
2 files changed, 25 insertions(+), 9 deletions(-)
diff --git a/autotools/docpp b/autotools/docpp
index 0970bcbaf..5d3bde8d6 100755
--- a/autotools/docpp
+++ b/autotools/docpp
@@ -30,15 +30,20 @@ from ganeti import query
from ganeti.build import sphinx_ext
-_QUERY_FIELDS_RE = re.compile(r"^@QUERY_FIELDS_(?P<kind>[A-Z]+)@$")
+_DOC_RE = re.compile(r"^@(?P<class>[A-Z_]+)_(?P<kind>[A-Z]+)@$")
+
+_DOC_CLASSES_DATA = {
+ "QUERY_FIELDS": (query.ALL_FIELDS, sphinx_ext.BuildQueryFields),
+ }
def main():
for line in fileinput.input():
- m = _QUERY_FIELDS_RE.match(line)
+ m = _DOC_RE.match(line)
if m:
- fields = query.ALL_FIELDS[m.group("kind").lower()]
- for i in sphinx_ext.BuildQueryFields(fields):
+ fields_dict, builder = _DOC_CLASSES_DATA[m.group("class")]
+ fields = fields_dict[m.group("kind").lower()]
+ for i in builder(fields):
print i
else:
print line,
diff --git a/lib/build/sphinx_ext.py b/lib/build/sphinx_ext.py
index 0d2d2e3cf..addb987f2 100644
--- a/lib/build/sphinx_ext.py
+++ b/lib/build/sphinx_ext.py
@@ -270,11 +270,22 @@ def BuildQueryFields(fields):
@type fields: dict (field name as key, field details as value)
"""
- for (_, (fdef, _, _, _)) in utils.NiceSort(fields.items(),
- key=compat.fst):
- assert len(fdef.doc.splitlines()) == 1
- yield "``%s``" % fdef.name
- yield " %s" % fdef.doc
+ defs = [(fdef.name, fdef.doc)
+ for (_, (fdef, _, _, _)) in utils.NiceSort(fields.items(),
+ key=compat.fst)]
+ yield BuildValuesDoc(defs)
+
+
+def BuildValuesDoc(values):
+ """Builds documentation for a list of values
+
+ @type values: list of tuples in the form (value, documentation)
+
+ """
+ for name, doc in values:
+ assert len(doc.splitlines()) == 1
+ yield "``%s``" % name
+ yield " %s" % doc
# TODO: Implement Sphinx directive for query fields
--
GitLab