From: Thierry Parmentelat Date: Thu, 8 May 2008 09:11:02 +0000 (+0000) Subject: first draft for the myplc-docs package (cross-module change) X-Git-Tag: PLCAPI-4.2-7~5 X-Git-Url: http://git.onelab.eu/?p=plcapi.git;a=commitdiff_plain;h=a7c033397aba357a21336361f0b0f41df26866b1 first draft for the myplc-docs package (cross-module change) --- diff --git a/PLC/Filter.py b/PLC/Filter.py index 4e950f1..195c4e6 100644 --- a/PLC/Filter.py +++ b/PLC/Filter.py @@ -55,11 +55,11 @@ class Filter(Parameter, dict): * fields starting with - are special and relate to row selection, i.e. sorting and clipping * '-SORT' : a field name, or an ordered list of field names that are used for sorting - * these fields may start with + (default) or - for denoting increasing or decreasing order + these fields may start with + (default) or - for denoting increasing or decreasing order example : filter = { '-SORT' : [ '+node_id', '-hostname' ] } * '-OFFSET' : the number of first rows to be ommitted * '-LIMIT' : the amount of rows to be returned - example : filter = { '-OFFSET' : 100, 'LIMIT':25} + example : filter = { '-OFFSET' : 100, '-LIMIT':25} A realistic example would read GetNodes ( { 'hostname' : '*.edu' , '-SORT' : 'hostname' , '-OFFSET' : 30 , '-LIMIT' : 25 } ) diff --git a/doc/DocBook.py b/doc/DocBook.py index 254e99e..9b6fcfa 100755 --- a/doc/DocBook.py +++ b/doc/DocBook.py @@ -13,8 +13,7 @@ import xml.dom.minidom from xml.dom.minidom import Element, Text import codecs -from PLC.Method import * -import DocBookLocal +from PLC.Parameter import Parameter, Mixed, xmlrpc_type, python_type # xml.dom.minidom.Text.writexml adds surrounding whitespace to textual # data when pretty-printing. Override this behavior. @@ -103,46 +102,52 @@ class paramElement(Element): 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") +class DocBook: + + def __init__ (self,functions_list): + self.functions_list = functions_list + + def Process (self): + + for func in self.functions_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 a01ad6c..f1624fd --- a/doc/DocBookLocal.py +++ b/doc/DocBookLocal.py @@ -1,8 +1,11 @@ +#!/usr/bin/env python from PLC.API import PLCAPI +from DocBook import DocBook -def get_func_list(methods = None): - api = PLCAPI(None) - if not methods: - methods = api.methods - return [api.callable(method) for method in methods] +def api_methods(): + api = PLCAPI(None) + methods = api.methods + return [api.callable(method) for method in methods] + +DocBook(api_methods ()).Process() diff --git a/doc/Makefile b/doc/Makefile index 3adaa1f..4a303c5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,12 +7,14 @@ # $Id$ # -all: PLCAPI.pdf +all: PLCAPI.html .PLCAPI.xml.valid: Methods.xml -Methods.xml: DocBook.py ../PLC/__init__.py ../PLC/Methods/__init__.py - PYTHONPATH=.. python $< > $@ +API_SOURCES = ../PLC/__init__.py ../PLC/Methods/__init__.py + +Methods.xml: DocBook.py DocBookLocal.py $(API_SOURCES) + PYTHONPATH=.. DocBookLocal.py > $@ # # Documentation @@ -40,6 +42,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 diff --git a/doc/PLCAPI.xml b/doc/PLCAPI.xml index f778525..6dd3326 100644 --- a/doc/PLCAPI.xml +++ b/doc/PLCAPI.xml @@ -131,13 +131,33 @@ # plcsh code fragment (see below) GetNodes([1,2,3]) GetNodes({'node_id': [1,2,3]}) -GetNodes({'node_id': 1}) + GetNodes({'node_id': 2}) + GetNodes({'node_id': 3}) - Would all be equivalent queries. Attributes that are + Would be equivalent queries. Attributes that are themselves arrays (such as nodenetwork_ids and slice_ids for nodes) cannot be used in filters. + + Filters support a few extra features illustrated in the following examples. + + + Pattern Matching + GetNodes ( { 'hostname' : '*.fr' } ) + + + Negation + GetNodes( { '~peer_id' : None } ) + + + Numeric comparisons + GetEvents( { '>time' : 1178531418 } ) + GetEvents( { ']event_id' : 2305 } ) + + + Sorting and Clipping + GetNodes( { '-SORT' : 'hostname' , '-OFFSET' : 30 , '-LIMIT' : 25 } + +