Add script to generate query fields documentation

- All lines matching "@QUERY_FIELDS_${resource}@" in the input will be
  replaced with a definition list describing the fields for $resource
- The core code is kept in the Sphinx extension, so that it could be
  used from there, too

Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: René Nussbaumer <rn@google.com>

Makefile.am

@@ -19,6 +19,7 @@ CHECK_PYTHON_CODE = $(top_srcdir)/autotools/check-python-code
 CHECK_MAN = $(top_srcdir)/autotools/check-man
 CHECK_VERSION = $(top_srcdir)/autotools/check-version
 CHECK_NEWS = $(top_srcdir)/autotools/check-news
+DOCPP = $(top_srcdir)/autotools/docpp
 REPLACE_VARS_SED = autotools/replace_vars.sed
 
 clientdir = $(pkgpythondir)/client
@@ -392,6 +393,7 @@ EXTRA_DIST = \
 	autotools/check-news \
 	autotools/check-tar \
 	autotools/check-version \
+	autotools/docpp \
 	autotools/gen-coverage \
 	autotools/testrunner \
 	$(RUN_IN_TEMPDIR) \
@@ -575,6 +577,7 @@ srclink_files = \
 
 check_python_code = \
 	$(BUILD_BASH_COMPLETION) \
+	$(DOCPP) \
 	$(all_python_code)
 
 lint_python_code = \
@@ -584,6 +587,7 @@ lint_python_code = \
 	$(dist_tools_SCRIPTS) \
 	$(pkglib_python_scripts) \
 	$(BUILD_BASH_COMPLETION) \
+	$(DOCPP) \
 	$(PYTHON_BOOTSTRAP)
 
 test/daemon-util_unittest.bash: daemons/daemon-util

autotools/docpp

+#!/usr/bin/python
+#
+
+# Copyright (C) 2011 Google Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301, USA.
+
+
+"""Script to replace special directives in documentation.
+
+"""
+
+import re
+import fileinput
+
+from ganeti import query
+from ganeti.build import sphinx_ext
+
+
+_QUERY_FIELDS_RE = re.compile(r"^@QUERY_FIELDS_(?P<kind>[A-Z]+)@$")
+
+
+def main():
+  for line in fileinput.input():
+    m = _QUERY_FIELDS_RE.match(line)
+    if m:
+      fields = query.ALL_FIELDS[m.group("kind").lower()]
+      for i in sphinx_ext.BuildQueryFields(fields):
+        print i
+    else:
+      print line,
+
+
+if __name__ == "__main__":
+  main()

lib/build/sphinx_ext.py

@@ -216,6 +216,22 @@ class PythonAssert(sphinx.util.compat.Directive):
     return []
 
 
+def BuildQueryFields(fields):
+  """Build query fields documentation.
+
+  @type fields: dict (field name as key, field details as value)
+
+  """
+  for (_, (fdef, _, _)) in utils.NiceSort(fields.items(),
+                                          key=operator.itemgetter(0)):
+    assert len(fdef.doc.splitlines()) == 1
+    yield "``%s``" % fdef.name
+    yield "  %s" % fdef.doc
+
+
+# TODO: Implement Sphinx directive for query fields
+
+
 def setup(app):
   """Sphinx extension callback.
 

lib/query.py

@@ -1397,5 +1397,13 @@ LOCK_FIELDS = _BuildLockFields()
 #: Fields available for node group queries
 GROUP_FIELDS = _BuildGroupFields()
 
+#: All available resources
+ALL_FIELDS = {
+  constants.QR_INSTANCE: INSTANCE_FIELDS,
+  constants.QR_NODE: NODE_FIELDS,
+  constants.QR_LOCK: LOCK_FIELDS,
+  constants.QR_GROUP: GROUP_FIELDS,
+  }
+
 #: All available field lists
-ALL_FIELD_LISTS = [NODE_FIELDS, INSTANCE_FIELDS, LOCK_FIELDS, GROUP_FIELDS]
+ALL_FIELD_LISTS = ALL_FIELDS.values()