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>

diff --git a/autotools/docpp b/autotools/docpp
index 0970bcb..5d3bde8 100755 (executable)
--- 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 0d2d2e3..addb987 100644 (file)
--- 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