From 106d33a2055836ce373a3cc5c69c41728a97ceb5 Mon Sep 17 00:00:00 2001 From: Stephen Soltesz Date: Thu, 25 Oct 2007 16:49:32 +0000 Subject: [PATCH] Take the new doc out of the branch and into trunk --- doc/DocBook.py | 148 ++++++++++++++++++++++++++++++++++++++++++++ doc/DocBookLocal.py | 13 ++++ doc/Makefile | 45 ++++++++++++++ doc/NMAPI.xml | 49 +++++++++++++++ 4 files changed, 255 insertions(+) create mode 100755 doc/DocBook.py create mode 100644 doc/DocBookLocal.py create mode 100644 doc/Makefile create mode 100644 doc/NMAPI.xml diff --git a/doc/DocBook.py b/doc/DocBook.py new file mode 100755 index 0000000..0b279b2 --- /dev/null +++ b/doc/DocBook.py @@ -0,0 +1,148 @@ +#!/usr/bin/python +# +# Generates a DocBook section documenting all PLCAPI methods on +# stdout. +# +# Mark Huang +# Copyright (C) 2006 The Trustees of Princeton University +# +# $Id: DocBook.py,v 1.3 2006/10/25 19:35:36 mlhuang Exp $ +# + +import xml.dom.minidom +from xml.dom.minidom import Element, Text +import codecs + +from PLC.Method import * +import DocBookLocal + +# xml.dom.minidom.Text.writexml adds surrounding whitespace to textual +# data when pretty-printing. Override this behavior. +class TrimText(Text): + """text""" + def __init__(self, text = None): + self.data = unicode(text) + + def writexml(self, writer, indent="", addindent="", newl=""): + Text.writexml(self, writer, "", "", "") + +class TrimTextElement(Element): + """text""" + def __init__(self, tagName, text = None): + Element.__init__(self, tagName) + if text is not None: + self.appendChild(TrimText(text)) + + def writexml(self, writer, indent="", addindent="", newl=""): + writer.write(indent) + Element.writexml(self, writer, "", "", "") + writer.write(newl) + +class simpleElement(TrimTextElement): pass + +class paraElement(simpleElement): + """text""" + def __init__(self, text = None): + simpleElement.__init__(self, 'para', text) + +class blockquoteElement(Element): + """
text......text
""" + def __init__(self, text = None): + Element.__init__(self, 'blockquote') + if text is not None: + # Split on blank lines + lines = [line.strip() for line in text.strip().split("\n")] + lines = "\n".join(lines) + paragraphs = lines.split("\n\n") + + for paragraph in paragraphs: + self.appendChild(paraElement(paragraph)) + +def param_type(param): + """Return the XML-RPC type of a parameter.""" + if isinstance(param, Mixed) and len(param): + subtypes = [param_type(subparam) for subparam in param] + return " or ".join(subtypes) + elif isinstance(param, (list, tuple, set)) and len(param): + return "array of " + " or ".join([param_type(subparam) for subparam in param]) + else: + return xmlrpc_type(python_type(param)) + +class paramElement(Element): + """An optionally named parameter.""" + def __init__(self, name, param): + # + Element.__init__(self, 'listitem') + + description = Element('para') + + if name: + description.appendChild(simpleElement('parameter', name)) + description.appendChild(TrimText(": ")) + + description.appendChild(TrimText(param_type(param))) + + if isinstance(param, (list, tuple, set)) and len(param) == 1: + param = param[0] + + if isinstance(param, Parameter): + description.appendChild(TrimText(", " + param.doc)) + param = param.type + + self.appendChild(description) + + if isinstance(param, dict): + itemizedlist = Element('itemizedlist') + self.appendChild(itemizedlist) + for name, subparam in param.iteritems(): + itemizedlist.appendChild(paramElement(name, subparam)) + + elif isinstance(param, (list, tuple, set)) and len(param): + itemizedlist = Element('itemizedlist') + self.appendChild(itemizedlist) + for subparam in param: + itemizedlist.appendChild(paramElement(None, subparam)) + +api_func_list = DocBookLocal.get_func_list() +for func in api_func_list: + method = func.name + + if func.status == "deprecated": + continue + + (min_args, max_args, defaults) = func.args() + + section = Element('section') + section.setAttribute('id', func.name) + section.appendChild(simpleElement('title', func.name)) + + prototype = "%s (%s)" % (method, ", ".join(max_args)) + para = paraElement('Prototype:') + para.appendChild(blockquoteElement(prototype)) + section.appendChild(para) + + para = paraElement('Description:') + para.appendChild(blockquoteElement(func.__doc__)) + section.appendChild(para) + + para = paraElement('Allowed Roles:') + para.appendChild(blockquoteElement(", ".join(func.roles))) + section.appendChild(para) + + section.appendChild(paraElement('Parameters:')) + params = Element('itemizedlist') + if func.accepts: + for name, param, default in zip(max_args, func.accepts, defaults): + params.appendChild(paramElement(name, param)) + else: + listitem = Element('listitem') + listitem.appendChild(paraElement('None')) + params.appendChild(listitem) + section.appendChild(params) + + section.appendChild(paraElement('Returns:')) + returns = Element('itemizedlist') + returns.appendChild(paramElement(None, func.returns)) + section.appendChild(returns) + + print section.toprettyxml(encoding = "UTF-8") diff --git a/doc/DocBookLocal.py b/doc/DocBookLocal.py new file mode 100644 index 0000000..be31df9 --- /dev/null +++ b/doc/DocBookLocal.py @@ -0,0 +1,13 @@ + +import api_calls + +def get_func_list(): + api_function_list = [] + for func in dir(api_calls): + try: + f = api_calls.__getattribute__(func) + if 'group' in f.__dict__.keys(): + api_function_list += [api_calls.__getattribute__(func)] + except: + pass + return api_function_list diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..4308fac --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,45 @@ +# +# (Re)builds API documentation +# +# Mark Huang +# Copyright (C) 2006 The Trustees of Princeton University +# +# $Id: Makefile,v 1.2 2006/11/03 20:36:05 thierry Exp $ +# + +all: NMAPI.html + +.NMAPI.xml.valid: Methods.xml + +Methods.xml: DocBook.py ../api_calls.py + PYTHONPATH=..:../../PLCAPI python $< > $@ + +# +# Documentation +# + +# Validate the XML +.%.xml.valid: %.xml + xmllint --valid --output $@ $< + +# Remove the temporary output file after compilation +.SECONDARY: .%.xml.valid + +# Compile it into other formats +FORMATS := dvi html man ps pdf rtf tex texi txt + +DOCBOOK2FLAGS := -V biblio-number=1 + +define docbook2 +%.$(1): %.xml .%.xml.valid + docbook2$(1) --nochunks $$(DOCBOOK2FLAGS) $$< +endef + +$(foreach format,$(FORMATS),$(eval $(call docbook2,$(format)))) + +clean: + rm -f $(patsubst %,*.%,$(FORMATS)) .*.xml.valid Methods.xml + +force: + +.PHONY: force clean docclean diff --git a/doc/NMAPI.xml b/doc/NMAPI.xml new file mode 100644 index 0000000..7ea30be --- /dev/null +++ b/doc/NMAPI.xml @@ -0,0 +1,49 @@ + + +]> + + + + PlanetLab Node Manager API Documentation + + + + Introduction + + The PlanetLab Node Manager API (NMAPI) is the interface through + which the slices access the Node API. + +
+ Authentication + + Authentication for NM operations is based on the identity of the + connecting slice. For slices whose roles are defined as + 'nm-controller', the target slice must be listed delegated and as + controlled by the calling slice. + +
+
+ Connection + + The NM XMLRPC server listens locally on every PlanetLab node at http://localhost:812. +
+ + + + + PlanetLab API Methods + + + &Methods; + + + + + + + -- 2.43.0