From 61955fee15191f1e01cd3003af1de4fbaef4c441 Mon Sep 17 00:00:00 2001 From: Thierry Parmentelat Date: Thu, 8 May 2008 09:11:02 +0000 Subject: [PATCH] first draft for the myplc-docs package (cross-module change) --- doc/DocBook.py | 148 -------------------------------------------- doc/DocBookLocal.py | 27 +++++--- doc/Makefile | 19 +++--- 3 files changed, 25 insertions(+), 169 deletions(-) delete mode 100755 doc/DocBook.py mode change 100644 => 100755 doc/DocBookLocal.py diff --git a/doc/DocBook.py b/doc/DocBook.py deleted file mode 100755 index 0b279b2..0000000 --- a/doc/DocBook.py +++ /dev/null @@ -1,148 +0,0 @@ -#!/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 old mode 100644 new mode 100755 index be31df9..62853a8 --- a/doc/DocBookLocal.py +++ b/doc/DocBookLocal.py @@ -1,13 +1,20 @@ +#!/usr/bin/env python +# PATHS to be set by the build system +# this is in .. import api_calls +# in PLCAPI/doc +from DocBook import DocBook -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 +def api_methods(): + 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 + +DocBook(api_methods ()).Process() diff --git a/doc/Makefile b/doc/Makefile index 0a90055..d40adb0 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -4,24 +4,23 @@ # Mark Huang # Copyright (C) 2006 The Trustees of Princeton University # -# $Id: Makefile,v 1.2 2006/11/03 20:36:05 thierry Exp $ +# $Id: Makefile 5574 2007-10-25 20:33:17Z thierry $ # -all: NMAPI.html end +all: NMAPI.html .NMAPI.xml.valid: Methods.xml -Methods.xml: DocBook.py ../api_calls.py - PYTHONPATH=..:../../../PLCAPI python $< > $@ +NM_SOURCES = ../api_calls.py + +# path needs to mention PLCAPI/doc (for DocBook) and PLCAPI/ (for PLC.Parameter) +Methods.xml: DocBookLocal.py $(NM_SOURCES) + PYTHONPATH=..:../../PLCAPI:../../PLCAPI/doc DocBookLocal.py > $@ # # Documentation # -# TODO: figure out where to put this command to strip out the unnecessary bits for PlanetLab Drupal page: -end: - awk 'BEGIN { print " 29 && $$0 != "> out.html - # Validate the XML .%.xml.valid: %.xml xmllint --valid --output $@ $< @@ -44,6 +43,4 @@ $(foreach format,$(FORMATS),$(eval $(call docbook2,$(format)))) clean: rm -f $(patsubst %,*.%,$(FORMATS)) .*.xml.valid Methods.xml -force: - -.PHONY: force clean docclean +.PHONY: clean all -- 2.43.0