first draft for the myplc-docs package (cross-module change)

diff --git a/PLC/Filter.py b/PLC/Filter.py
index 4e950f1..195c4e6 100644 (file)
--- 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 (executable)
--- 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 (file)
new mode 100755 (executable)
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 (file)
--- 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 (file)
--- 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})
 </programlisting>
 
-      <para>Would all be equivalent queries. Attributes that are
+      <para>Would be equivalent queries. Attributes that are
       themselves arrays (such as <literal>nodenetwork_ids</literal>
       and <literal>slice_ids</literal> for nodes) cannot be used in
       filters.</para>
+
+      <para> Filters support a few extra features illustrated in the following examples.</para>
+      <itemizedlist>
+       <listitem>
+         <para> <emphasis> Pattern Matching </emphasis> </para>
+         <programlisting>GetNodes ( { 'hostname' : '*.fr' } ) </programlisting>
+       </listitem>
+       <listitem>
+         <para> <emphasis> Negation </emphasis> </para>
+         <programlisting>GetNodes( { '~peer_id' : None } ) </programlisting>
+       </listitem>
+       <listitem>
+         <para> <emphasis> Numeric comparisons </emphasis> </para>
+         <programlisting>GetEvents( { '>time' : 1178531418 } ) </programlisting>
+         <programlisting>GetEvents( { ']event_id' : 2305 } ) </programlisting>
+       </listitem>
+       <listitem>
+         <para> <emphasis> Sorting and Clipping </emphasis> </para>
+         <programlisting> GetNodes( { '-SORT' : 'hostname' , '-OFFSET' : 30 , '-LIMIT' : 25 }</programlisting>
+       </listitem>
+      </itemizedlist>
     </section>
 
     <section>