Added docs for library
authorandy_robinson
Wed, 14 Jun 2000 21:22:52 +0000
changeset 271 574511abf998
parent 270 01635bde618e
child 272 80107aaffa7e
Added docs for library
docs/reference/reference.yml
docs/tools/codegrab.py
docs/tools/stylesheet.py
docs/tools/yaml.py
--- a/docs/reference/reference.yml	Wed Jun 14 21:17:30 2000 +0000
+++ b/docs/reference/reference.yml	Wed Jun 14 21:22:52 2000 +0000
@@ -3,6 +3,11 @@
 This is the API reference for the ReportLab library.  All public
 classes, functions and methods are documented here.
 
+Most of the reference text is built automatically from the
+documentation strings in each class, method and function.
+That's why it uses preformatted text and doesn't look very
+pretty.
+
 Please note the following points:
 .bu <seqdefault id='list'/><bullet>(<seq/>)</bullet>Items with one leading underscore are considered private
 to the modules they are defined in; they are not documented
@@ -55,16 +60,64 @@
 Each package is documented in turn.
 
 .pageBreak
-.h1 pdfgen subpackage API Reference
-.getModuleDoc reportlab.pdfgen.canvas
+.h1 <i>reportlab.pdfgen</i> subpackage
+
+This package contains three modules, canvas.py, textobject.py
+and pathobject.py, which define three classes of corresponding 
+names.  The only class users should construct directly is
+the Canvas, defined in reportlab.pdfgen.canvas; it provides
+methods to obtain PathObjects and TextObjects.
+
+
+.getClassDoc reportlab.pdfgen.canvas Canvas
+.pageBreak
+The method Canvas.beginPath allows users to construct
+a PDFPathObject, which is defined in reportlab/pdfgen/pathobject.py.
+
+.getClassDoc reportlab.pdfgen.pathobject PDFPathObject
+.pageBreak
+The method Canvas.beginText allows users to construct
+a PDFTextObject, which is defined in reportlab/pdfgen/textobject.py.
+
+.getClassDoc reportlab.pdfgen.textobject PDFTextObject
+.pageBreak
+.h1 <i>reportlab.platypus</i> subpackage
+
 .pageBreak
-.getModuleDoc reportlab.pdfgen.pathobject
-.pageBreak
-.getModuleDoc reportlab.pdfgen.textobject
+.h1 <i>reportlab.lib</i> subpackage
+
+This package contains a number of modules which either add utility
+to pdfgen and platypus, or which are of general use in graphics
+applications.
+
+.h2 <i>reportlab.lib.colors</i> module
+.getModuleDoc reportlab.lib.colors
+
+.h2 <i>reportlab.lib.corp</i> module
+.getModuleDoc reportlab.lib.corp
+
+.h2 <i>reportlab.lib.enums</i> module
+.getModuleDoc reportlab.lib.enums
+
+.h2 <i>reportlab.lib.fonts</i> module
+.getModuleDoc reportlab.lib.fonts
+
+.h2 <i>reportlab.lib.pagesizes</i> module
+.getModuleDoc reportlab.lib.pagesizes
+
+.h2 <i>reportlab.lib.sequencer</i> module
+.getModuleDoc reportlab.lib.sequencer
+
+
+
+
 .pageBreak
 .h1 Appendix A - CVS Revision History
 .beginPre Code
 $Log: reference.yml,v $
+Revision 1.6  2000/06/14 21:22:52  andy_robinson
+Added docs for library
+
 Revision 1.5  2000/06/12 11:26:34  andy_robinson
 Numbered list added
 
--- a/docs/tools/codegrab.py	Wed Jun 14 21:17:30 2000 +0000
+++ b/docs/tools/codegrab.py	Wed Jun 14 21:22:52 2000 +0000
@@ -54,11 +54,14 @@
     result = Struct()
     result.functions = []
     result.classes = []
+    result.doc = mod.__doc__
     for name in dir(mod):
         value = getattr(mod, name)
         if type(value) is types.FunctionType:
+            path, file = os.path.split(value.func_code.co_filename)
+            root, ext = os.path.splitext(file)
             #we're possibly interested in it
-            if os.path.splitext(value.func_code.co_filename)[0] == modulename:
+            if root == modulename:
                 #it was defined here
                 funcObj = value
                 fn = Struct()
@@ -68,6 +71,14 @@
                     fn.doc = dedent(funcObj.__doc__)
                 else:
                     fn.doc = '(no documentation string)'
+                #is it official?
+                if name[0:1] == '_':
+                     fn.status = 'private'
+                elif name[-1] in '0123456789':
+                    fn.status = 'experimental'
+                else:
+                    fn.status = 'official'
+                        
                 result.functions.append(fn)
         elif type(value) == types.ClassType:
             if value.__module__ == modulename:
@@ -81,6 +92,12 @@
                 cl.bases = []
                 for base in value.__bases__:
                     cl.bases.append(base.__name__)
+                if name[0:1] == '_':
+                    cl.status = 'private'
+                elif name[-1] in '0123456789':
+                    cl.status = 'experimental'
+                else:
+                    cl.status = 'official'
                 
                 cl.methods = []
                 #loop over dict finding methods defined here
--- a/docs/tools/stylesheet.py	Wed Jun 14 21:17:30 2000 +0000
+++ b/docs/tools/stylesheet.py	Wed Jun 14 21:22:52 2000 +0000
@@ -105,6 +105,7 @@
                                   parent=stylesheet['Normal'],
                                   fontName='Courier',
                                   fontSize=8,
+                                  leftIndent=18,
                                   leading=8.8))
 
     stylesheet.add(ParagraphStyle(name='DocStringIndent',
--- a/docs/tools/yaml.py	Wed Jun 14 21:17:30 2000 +0000
+++ b/docs/tools/yaml.py	Wed Jun 14 21:22:52 2000 +0000
@@ -147,31 +147,28 @@
         """Documents the entire module at this point by making
         paragraphs and preformatted objects"""
         docco = docs.tools.codegrab.getObjectsDefinedIn(modulename, pathname)
+        if docco.doc <> None:
+            self._results.append(('Paragraph', 'DocString', docco.doc))
         if len(docco.functions) > 0:
-            self._results.append(('Paragraph','Heading2', 'Functions in ' + modulename))
             for fn in docco.functions:
                 if fn.status == 'official':
                     self._results.append(('Preformatted','FunctionHeader', fn.proto))
                     self._results.append(('Preformatted','DocString', fn.doc))
-        else:
-            self._results.append(('Paragraph','Heading2', 'No Functions Defined in ' + modulename))
 
         if len(docco.classes) > 0:
-            self._results.append(('Paragraph','Heading2', 'Classes in ' + modulename))
             for cls in docco.classes:
-                self._results.append(('Preformatted','FunctionHeader', 'Class %s:' % cls.name))
-                self._results.append(('Preformatted','DocString', cls.doc))
-                for mth in cls.methods:
-                    if mth.status == 'official':
-                        self._results.append(('Preformatted','FunctionHeader', mth.proto))
-                        self._results.append(('Preformatted','DocStringIndent', mth.doc))
+                if cls.status == 'official':
+                    self._results.append(('Preformatted','FunctionHeader', 'Class %s:' % cls.name))
+                    self._results.append(('Preformatted','DocString', cls.doc))
+                    for mth in cls.methods:
+                        if mth.status == 'official':
+                            self._results.append(('Preformatted','FunctionHeader', mth.proto))
+                            self._results.append(('Preformatted','DocStringIndent', mth.doc))
                     
-        else:
-            self._results.append(('Paragraph','Heading2', 'No Classes Defined in ' + modulename))
 
     def getClassDoc(self, modulename, classname, pathname=None):
         """Documents the class and its public methods"""
-        docco = codegrab.getObjectsDefinedIn(modulename, pathname)
+        docco = docs.tools.codegrab.getObjectsDefinedIn(modulename, pathname)
         found = 0
         for cls in docco.classes:
             if cls.name == classname: