From 05bb5d58295cd959c34f1fbcd5b605cd6dafaacc Mon Sep 17 00:00:00 2001 From: pinky <> Date: Sun, 7 Jan 2007 21:41:39 +0000 Subject: Repotrlab 2.0 bzr revid: pinky-b8333ccaab5dad8ff965b6c380fadadf30d5212a --- bin/reportlab/docs/reference/build.bat | 3 + bin/reportlab/docs/reference/genreference.py | 29 ++++ bin/reportlab/docs/reference/reference.yml | 217 +++++++++++++++++++++++++++ 3 files changed, 249 insertions(+) create mode 100755 bin/reportlab/docs/reference/build.bat create mode 100644 bin/reportlab/docs/reference/genreference.py create mode 100644 bin/reportlab/docs/reference/reference.yml (limited to 'bin/reportlab/docs/reference') diff --git a/bin/reportlab/docs/reference/build.bat b/bin/reportlab/docs/reference/build.bat new file mode 100755 index 00000000000..483af7b9b6c --- /dev/null +++ b/bin/reportlab/docs/reference/build.bat @@ -0,0 +1,3 @@ +del reference.pdf +python ..\tools\yaml2pdf.py reference.yml +start reference.pdf diff --git a/bin/reportlab/docs/reference/genreference.py b/bin/reportlab/docs/reference/genreference.py new file mode 100644 index 00000000000..c2b6afd7598 --- /dev/null +++ b/bin/reportlab/docs/reference/genreference.py @@ -0,0 +1,29 @@ +#!/bin/env python +#Copyright ReportLab Europe Ltd. 2000-2004 +#see license.txt for license details +#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/reference/genreference.py +__version__=''' $Id: genreference.py 2385 2004-06-17 15:26:05Z rgbecker $ ''' +__doc__ = """ +This module contains the script for building the reference. +""" +def run(verbose=None, outDir=None): + import os, sys, shutil + from reportlab.tools.docco import yaml2pdf + from reportlab.lib.utils import _RL_DIR + if verbose is None: verbose=('-s' not in sys.argv) + yaml2pdf.run('reference.yml','reference.pdf') + if verbose: print 'Saved reference.pdf' + docdir = os.path.join(_RL_DIR,'docs') + if outDir: docDir = outDir + destfn = docdir + os.sep + 'reference.pdf' + shutil.copyfile('reference.pdf', destfn) + if verbose: print 'copied to %s' % destfn + +def makeSuite(): + "standard test harness support - run self as separate process" + from reportlab.test.utils import ScriptThatMakesFileTest + return ScriptThatMakesFileTest('../docs/reference', 'genreference.py', 'reference.pdf') + + +if __name__=='__main__': + run() diff --git a/bin/reportlab/docs/reference/reference.yml b/bin/reportlab/docs/reference/reference.yml new file mode 100644 index 00000000000..65e4091af5c --- /dev/null +++ b/bin/reportlab/docs/reference/reference.yml @@ -0,0 +1,217 @@ +.t ReportLab API Reference + +.nextPageTemplate Normal + +.h1 Introduction + +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 ()Items with one leading underscore are considered private +to the modules they are defined in; they are not documented +here and we make no commitment to their maintenance. +.bu ()Items ending in a digit (usually zero) are experimental; +they are released to allow widespread testing, but are +guaranteed to be broken in future (if only by dropping the +zero). By all means play with these and give feedback, but +do not use them in production scripts. + +.h2 Package Architecture + +The reportlab package is broken into a number of subpackages. +These are as follows: + +.df reportlab.pdfgen +- this is the programming +interface to the PDF file format. The Canvas (and its co-workers, +TextObject and PathObject) provide everything you need to +create PDF output working at a low level - individual shapes +and lines of text. Internally, it constructs blocks of +page marking operators which match your drawing commands, +and hand them over to the pdfbase +package for drawing. + +.df reportlab.pdfbase +- this is not part of the +public interface. It contains code to handle the 'outer +structure' of PDF files, and utilities to handle text metrics +and compressed streams. + +.df reportlab.platypus +- PLATYPUS stands for +"Page Layout and Typography Using Scripts". It provides a +higher level of abstraction dealing with paragraphs, frames +on the page, and document templates. This is used for multi- +page documents such as this reference. + +.df reportlab.lib +- this contains code of +interest to application developers which cuts across +both of our libraries, such as standard colors, units, and +page sizes. It will also contain more drawable and flowable +objects in future. + +There is also a demos directory containing various demonstrations, +and a docs directory. These can be accessed with package +notation but should not be thought of as packages. + +Each package is documented in turn. + +.pageBreak +.h1 reportlab.pdfgen 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 reportlab.platypus subpackage + +The platypus package defines our high-level page layout API. +The division into modules is far from final and has been +based more on balancing the module lengths than on any +particular programming interface. The __init__ module +imports the key classes into the top level of the package. + +.h2 Overall Structure + +Abstractly Platypus currently can be thought of has having four +levels: documents, pages, frames and flowables (things which can fit into frames in some way). +In practice there is a fifth level, the canvas, so that if you want +you can do anything that pdfgen's canvas allows. + +.h2 Document Templates +.h3 BaseDocTemplate + +The basic document template class; it provides for initialisation and +rendering of documents. A whole bunch of methods +handle_XXX handle document +rendering events. These event routines all contain some +significant semantics so while these may be overridden that +may require some detailed knowledge. Some other methods are +completely virtual and are designed to be overridden. +.h3 BaseDocTemplate +.getClassDoc reportlab.platypus.doctemplate BaseDocTemplate + +.pageBreak +A simple document processor can be made using derived class, +SimpleDocTemplate. + +.pageBreak +.h3 SimpleDocTemplate +.getClassDoc reportlab.platypus.doctemplate SimpleDocTemplate + +.pageBreak +.h2 Flowables +.getClassDoc reportlab.platypus.paragraph Paragraph +.getClassDoc reportlab.platypus.flowables Flowable +.getClassDoc reportlab.platypus.flowables XBox +.getClassDoc reportlab.platypus.flowables Preformatted +.getClassDoc reportlab.platypus.flowables Image +.getClassDoc reportlab.platypus.flowables Spacer +.getClassDoc reportlab.platypus.flowables PageBreak +.getClassDoc reportlab.platypus.flowables CondPageBreak +.getClassDoc reportlab.platypus.flowables KeepTogether +.getClassDoc reportlab.platypus.flowables Macro +.getClassDoc reportlab.platypus.xpreformatted XPreformatted +.getClassDoc reportlab.platypus.xpreformatted PythonPreformatted + +.pageBreak +.h1 reportlab.lib 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 reportlab.lib.colors module +.getModuleDoc reportlab.lib.colors + +.h2 reportlab.lib.corp module +.getModuleDoc reportlab.lib.corp + +.h2 reportlab.lib.enums module +.getModuleDoc reportlab.lib.enums + +.h2 reportlab.lib.fonts module +.getModuleDoc reportlab.lib.fonts + +.h2 reportlab.lib.pagesizes module +.getModuleDoc reportlab.lib.pagesizes + +.h2 reportlab.lib.sequencer module +.getModuleDoc reportlab.lib.sequencer + + + + +.pageBreak +.h1 Appendix A - CVS Revision History +.beginPre Code +$Log: reference.yml,v $ +Revision 1.1 2001/10/05 12:33:33 rgbecker +Moved from original project docs, history lost + +Revision 1.13 2001/08/30 10:32:38 dinu_gherman +Added missing flowables. + +Revision 1.12 2001/07/11 09:21:27 rgbecker +Typo fix from Jerome Alet + +Revision 1.11 2000/07/10 23:56:09 andy_robinson +Paragraphs chapter pretty much complete. Fancy cover. + +Revision 1.10 2000/07/03 15:39:51 rgbecker +Documentation fixes + +Revision 1.9 2000/06/28 14:52:43 rgbecker +Documentation changes + +Revision 1.8 2000/06/19 23:52:31 andy_robinson +rltemplate now simple, based on UserDocTemplate + +Revision 1.7 2000/06/17 07:46:45 andy_robinson +Small text changes + +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 + +Revision 1.4 2000/06/12 11:13:09 andy_robinson +Added sequencer tags to paragraph parser + +Revision 1.3 2000/06/09 01:44:24 aaron_watters +added automatic generation for pathobject and textobject modules. + +Revision 1.2 2000/06/07 13:39:22 andy_robinson +Added some text to the first page of reference, and a build batch file + +Revision 1.1.1.1 2000/06/05 16:39:04 andy_robinson +initial import + +.endPre + + + -- cgit v1.2.3