From 95eb41882baa0571f31be42cd331fcac3f0db596 Mon Sep 17 00:00:00 2001
From: Michael Hanselmann <hansmi@google.com>
Date: Wed, 23 Feb 2011 18:05:22 +0100
Subject: [PATCH] Add script to generate query fields documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 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 | 4 ++++
autotools/docpp | 48 +++++++++++++++++++++++++++++++++++++++++
lib/build/sphinx_ext.py | 16 ++++++++++++++
lib/query.py | 10 ++++++++-
4 files changed, 77 insertions(+), 1 deletion(-)
create mode 100755 autotools/docpp
diff --git a/Makefile.am b/Makefile.am
index 4aaae3fec..66486171d 100644
--- a/Makefile.am
+++ b/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
diff --git a/autotools/docpp b/autotools/docpp
new file mode 100755
index 000000000..0970bcbaf
--- /dev/null
+++ b/autotools/docpp
@@ -0,0 +1,48 @@
+#!/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()
diff --git a/lib/build/sphinx_ext.py b/lib/build/sphinx_ext.py
index 40d1a40cc..1570b02b3 100644
--- a/lib/build/sphinx_ext.py
+++ b/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.
diff --git a/lib/query.py b/lib/query.py
index 6a893a733..0daa3b8d3 100644
--- a/lib/query.py
+++ b/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()
--
GitLab