fence-agents: master - fencing: Metadata suitable for automatic man pages generation

["Marek Grác" <marx@fedoraproject.org>]

Gitweb:        http://git.fedorahosted.org/git/fence-agents.git?p=fence-agents.git;a=commitdiff;h=122857accf9e20167c2fae3ef76f24979a0d0ca6
Commit:        122857accf9e20167c2fae3ef76f24979a0d0ca6
Parent:        0d3b83cf00ef4c172922d271a6acb34a825561fd
Author:        Marek 'marx' Grac <mgrac@redhat.com>
AuthorDate:    Mon Jul 13 15:43:05 2009 +0200
Committer:     Marek 'marx' Grac <mgrac@redhat.com>
CommitterDate: Mon Jul 13 15:43:05 2009 +0200

fencing: Metadata suitable for automatic man pages generation

Information about individual options are extended so they are more suitable
for creating better metadata. We can use them to produce fresh manual pages.
Metadata have to be formatted using XSLT processor (e.h. xsltproc) using
template ra2man.xsl in lib/

Example:
fence_lpar -o metadata | xsltproc ra2man.xsl - | nroff -mandoc > z
man ./z

@note:
If the default value is array then only string 'list of values' is rendered.
As currently it is not possible to enter arrays from getopt/stdin.
---
 fence/agents/lib/fencing.py.py |   62 +++++++++++++++++++++++++++++++---
 fence/agents/lib/ra2man.xsl    |   72 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 129 insertions(+), 5 deletions(-)

diff --git a/fence/agents/lib/fencing.py.py b/fence/agents/lib/fencing.py.py
index 3829ccc..eaff7a0 100644
--- a/fence/agents/lib/fencing.py.py
+++ b/fence/agents/lib/fencing.py.py
@@ -37,11 +37,15 @@ all_opt = {
 		"getopt" : "h",
 		"longopt" : "help",
 		"help" : "-h, --help                     Display this help and exit",
+		"required" : "0",
+		"shortdesc" : "Display help and exit",
 		"order" : 54 },
 	"version" : { 
 		"getopt" : "V",
 		"longopt" : "version",
 		"help" : "-V, --version                  Output version information and exit",
+		"required" : "0",
+		"shortdesc" : "Display version information and exit",
 		"order" : 53 },
 	"quiet"   : {
 		"getopt" : "q",
@@ -58,6 +62,8 @@ all_opt = {
 		"getopt" : "D:",
 		"longopt" : "debug-file", 
 		"help" : "-D, --debug-file=<debugfile>   Debugging to output file",
+		"required" : "0",
+		"shortdesc" : "Write debug information to given file",
 		"order" : 52 },
 	"agent"   : {
 		"getopt" : "",
@@ -125,34 +131,44 @@ all_opt = {
 		"getopt" : "m:",
 		"longopt" : "module-name",
 		"help" : "-m, --module-name=<module>     DRAC/MC module name",
+		"required" : "0",
+		"shortdesc" : "DRAC/MC module name",
 		"order" : 1 },
 	"drac_version" : {
 		"getopt" : "d:",
 		"longopt" : "drac-version",
 		"help" : "-d, --drac-version=<version>   Force DRAC version to use",
+		"required" : "0",
+		"shortdesc" : "Force DRAC version to use",
 		"order" : 1 },
 	"hmc_version" : {
 		"getopt" : "H:",
 		"longopt" : "hmc-version",
 		"help" : "-H, --hmc-version=<version>   Force HMC version to use: 3, 4 (default)",
+		"required" : "0",
+		"shortdesc" : "Force HMC version to use (3 or 4)",
 		"default" : "4", 
 		"order" : 1 },
 	"ribcl" : {
 		"getopt" : "r:",
 		"longopt" : "ribcl-version",
 		"help" : "-r, --ribcl-version=<version>  Force ribcl version to use",
+		"required" : "0",
+		"shortdesc" : "Force ribcl version to use",
 		"order" : 1 },
 	"cmd_prompt" : {
 		"getopt" : "c:",
 		"longopt" : "command-prompt",
 		"help" : "-c, --command-prompt=<prompt>  Force command prompt",
+		"shortdesc" : "Force command prompt",
+		"required" : "0",
 		"order" : 1 },
 	"secure" : {
 		"getopt" : "x",
 		"longopt" : "ssh",
 		"help" : "-x, --ssh                      Use ssh connection",
-		"required" : "0",
 		"shortdesc" : "SSH connection",
+		"required" : "0",
 		"order" : 1 },
 	"ssl" : {
 		"getopt" : "z",
@@ -290,6 +306,8 @@ all_opt = {
 		"longopt" : "separator",
 		"help" : "-C, --separator=<char>         Separator for CSV created by 'list' operation",
 		"default" : ",", 
+		"required" : "0",
+		"shortdesc" : "Separator for CSV created by operation list",
 		"order" : 100 }
 }
 
@@ -346,14 +364,15 @@ def usage(avail_opt):
 		if len(value["help"]) != 0:
 			print "   " + value["help"]
 
-def metadata(avail_opt):
+def metadata(avail_opt, options, docs):
 	global all_opt
 
 	sorted_list = [ (key, all_opt[key]) for key in avail_opt ]
 	sorted_list.sort(lambda x, y: cmp(x[1]["order"], y[1]["order"]))
 
 	print "<?xml version=\"1.0\" ?>"
-	print "<resource-agent name=\"" + os.path.basename(sys.argv[0]) + "\" >"
+	print "<resource-agent name=\"" + os.path.basename(sys.argv[0])[:-3] + "\" shortdesc=\"" + docs["shortdesc"] + "\" >"
+	print "<longdesc>" + docs["longdesc"] + "</longdesc>"
 	print "<parameters>"
 	for option, value in sorted_list:
 		if all_opt[option].has_key("shortdesc"):
@@ -362,14 +381,42 @@ def metadata(avail_opt):
 			default = ""
 			if all_opt[option].has_key("default"):
 				default = "default=\""+all_opt[option]["default"]+"\""
+			elif options.has_key("-" + all_opt[option]["getopt"][:-1]):
+				if options["-" + all_opt[option]["getopt"][:-1]]:
+					try:
+						default = "default=\"" + options["-" + all_opt[option]["getopt"][:-1]] + "\""
+					except TypeError:
+						## @todo/@note: Currently there is no clean way how to handle lists
+						## we can create a string from it but we can't set it on command line
+						default = "default=\"list of values\""
+			elif options.has_key("-" + all_opt[option]["getopt"]):
+				default = "default=\"true\" "
+
+			mixed = all_opt[option]["help"]
+			## split it between option and help text
+			res = re.compile("^(.*--\S+)\s+", re.IGNORECASE | re.S).search(mixed)
+			if (None != res):
+				mixed = res.group(1)
+			mixed = mixed.replace("<", "&lt;").replace(">", "&gt;")
+			print "\t\t<getopt mixed=\"" + mixed + "\" />"
 
 			if all_opt[option]["getopt"].count(":") > 0:
 				print "\t\t<content type=\"string\" "+default+" />"
 			else:
 				print "\t\t<content type=\"boolean\" "+default+" />"
+				
 			print "\t\t<shortdesc lang=\"en\">" + all_opt[option]["shortdesc"] + "</shortdesc>"
 			print "\t</parameter>"
 	print "</parameters>"
+	print "<actions>"
+	print "\t<action name=\"on\" />"
+	print "\t<action name=\"off\" />"
+	print "\t<action name=\"reboot\" />"
+	print "\t<action name=\"status\" />"
+	print "\t<action name=\"list\" />"
+	print "\t<action name=\"monitor\" />"
+	print "\t<action name=\"meta-data\" />"	
+	print "</actions>"
 	print "</resource-agent>"
 
 def process_input(avail_opt):
@@ -561,8 +608,13 @@ def wait_power_status(tn, options, get_power_fn):
 			return 1
 	return 0
 
-def show_docs(options):
+def show_docs(options, docs = None):
 	device_opt = options["device_opt"]
+
+	if docs == None:
+		docs = { }
+		docs["shortdesc"] = "Fence agent"
+		docs["longdesc"] = ""
 	
 	## Process special options (and exit)
 	#####
@@ -571,7 +623,7 @@ def show_docs(options):
 		sys.exit(0)
 
 	if options.has_key("-o") and options["-o"].lower() == "metadata":
-		metadata(device_opt)
+		metadata(device_opt, options, docs)
 		sys.exit(0)
 
 	if options.has_key("-V"):
diff --git a/fence/agents/lib/ra2man.xsl b/fence/agents/lib/ra2man.xsl
new file mode 100644
index 0000000..2169e1f
--- /dev/null
+++ b/fence/agents/lib/ra2man.xsl
@@ -0,0 +1,72 @@
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:output method="text" indent="no"/>
+
+<xsl:template match="parameter">
+<xsl:param name="show" />
+.TP
+<xsl:if test="$show = 'getopt'">.B <xsl:value-of select="getopt/@mixed" /></xsl:if>
+<xsl:if test="$show = 'stdin'">.B <xsl:value-of select="@name"/></xsl:if>
+. 
+<xsl:value-of select="normalize-space(shortdesc)"/>
+<xsl:text>
+
+</xsl:text>
+<xsl:if test="not(content/@default)"><xsl:if test="@required = 1">This parameter is always required.</xsl:if></xsl:if>
+.br
+<xsl:if test="content/@default">Default Value: <xsl:value-of select="content/@default"/></xsl:if>
+</xsl:template>
+
+<xsl:template match="action">
+.TP
+\fB<xsl:value-of select="@name"/>
+<xsl:choose>
+<xsl:when test="@name = 'on'">
+Power on machine.
+</xsl:when>
+<xsl:when test="@name = 'off'">
+Power off machine.
+</xsl:when>
+<xsl:when test="@name = 'reboot'">
+Reboot machine.
+</xsl:when>
+<xsl:when test="@name = 'monitor'">
+Check if fencing device is running. List available plugs/virtual machines or get status of machine (if it does not support more).
+</xsl:when>
+<xsl:when test="@name = 'meta-data'">
+Display the XML metadata describing this resource.
+</xsl:when>
+<xsl:when test="@name = 'list'">
+List available plugs with aliases/virtual machines if there is support for more then one device. Returns N/A otherwise.
+</xsl:when>
+<xsl:when test="@name = 'status'">
+This returns the status of the plug/virtual machine. 
+</xsl:when>
+<!-- Ehhh -->
+<xsl:otherwise>
+The operational behavior of this is not known.
+</xsl:otherwise>
+</xsl:choose>
+</xsl:template>
+
+<xsl:template match="/resource-agent">
+.TH FENCE_AGENT 8 2009-01-20 "<xsl:value-of select="@name"/> (Fence Agent)"
+.SH NAME
+<xsl:value-of select="@name" /> - <xsl:value-of select="@shortdesc" />
+.SH DESCRIPTION
+<xsl:value-of select="@name" /> accepts options on the command line as well
+as from stdin. Fenced sends parameters through stdin when it execs the
+agent. <xsl:value-of select="@name" /> can be run by itself with command
+line options.  This is useful for testing and for turning outlets on or off
+from scripts.
+
+<xsl:value-of select="normalize-space(longdesc)"/>
+.SH PARAMETERS
+<xsl:apply-templates select="parameters"><xsl:with-param name="show">getopt</xsl:with-param></xsl:apply-templates>
+.SH ACTIONS
+<xsl:apply-templates select="actions"/>
+.SH STDIN PARAMETERS
+<xsl:apply-templates select="parameters"><xsl:with-param name="show">stdin</xsl:with-param></xsl:apply-templates>
+
+</xsl:template>
+
+</xsl:stylesheet>