Avoiding Documentation Costs with Python | Our Success Stories | Python.org
Notice: This page displays a fallback because interactive scripts did not run. Possible causes include disabled JavaScript or failure to load scripts or stylesheets. Avoiding Documentation Costs with Python Written by Andrew Jonathan Fine , Honeywell Introduction This article shows how I integrated Python, COM, DocBook, OpenJade, and Word together to create a documentation tool for BEACON, a visual programming environment.
This documentation tool was used for code reviews in the software development methodology at my company, and led to significant (>$1M) in cost savings. Before starting this project, I had no prior experience using SGML, XML, or other document markup languages. It was only when I was perilously close to reinventing the concept of markup languages, by adapting direct PythonCOM-to-Word interfaces from Mark Hammond's book Python Programming on Win32 , that I decided there had be a better way to do this from a design and maintenance standpoint.
A Web search provided me with a crash course on markup languages such as XML, HTML, and SGML. My search also provided insight into DocBook SGML, a popular open standard, and OpenJade, an open source package that can translate DocBook SGML into Word Rich Text. This arrangement wasn't perfect but I quickly realized that I could use it to save a year in development and maintenance costs, and to respond more quickly to new assignments.
The Core Data Flow My primary task was to translate arbitrary data mined from various sources scattered throughout my organization into sensible-looking Microsoft Word 97 reports. I decided that this was best handled through a core pipeline of applications that cooperated with each other using common data conventions. This pipeline would be controlled by a Python generator application that would drive a set of front end translators, a content inserter, and a post-processing formatter to generate the reports.
Python had recently been chosen as our department's successor language for automated test scripts. I noticed Python's potential beyond use for testing, so I obtained permission from my manager to use it for this task. The front end translators in this application harvest content (pictures, tables, paragraphs) from various data sources and place it into a dictionary. The content inserter creates a Word document and inserts values from the dictionary into it.
The post-processing formatter takes the result and modifies it according to the latest corporate Word format style template. This flow was designed to cope with changes in requirements by the different teams within our department, and by corporate-level standards. For example, the layout of reports was determined by the generator application in a layout class that could be replaced with other classes to support new types of reports.
The first front-end translator I needed to create was to take pictures, tables, and data from recursive property lists constructed by an aerospace industry software visual programming tool called BEACON. From this translator I was able to obtain a huge amount of sample data fit for testing the Word content inserter. Problems with the Inserter The first version of the content inserter was based on principles demonstrated in Python Programming on Win32 , which contains a detailed description of how Python can create and manipulate Word documents with the Word 97 COM object model.
This implementation inserted the content into Word documents by driving Word directly through its COM interface. Unfortunately, the COM interface was much too slow to handle the massive number of table cells that were extracted from the BEACON source code. Worse were the reuse issues with the classes I was writing for dealing with the different stylistic requirements at the different levels of sections, headings, paragraphs, and phrases.
To address these problems, I considered writing ASCII text files to specify margins, font, heading level, and insertion points for standard forms. But inventing my own standard for text-specified typesetting would have been time consuming and costly both to develop and to maintain. What I really needed was a Python API to quickly generate nicely typeset copy in Word 97 for a limited set of documents, but in 2001 there was nothing available to do this.
My only alternative was to find an open standard for typesetting that could be translated into Word 97 format after documents had been generated. Shopping for a Standard To find a solution, I spent some time surveying available open source typesetting solutions. The two most popular are TeX and DocBook , both of which are supported by open source implementations written in C. DocBook was chosen because it had more clearly defined and documented production rules for typesetting elements.
DocBook, The Definitive Guide is a real treasure when it comes to explaining these rules in detail. DocBook provides a set of Document Type Definition (.DTD) and Document Stylesheet (.DSL) files written in DSSSL, the Document Style Semantics and Specification Language. DocBook comes packaged in two flavors, one for SGML and the other for XML document encoding. Both SGML and XML have similar nested structures of tags and the same logical structure for the DTDs and DSLs.
However, the XML rules were still under development during 2001, so I chose the more reliable and mature SGML rule set. DocBook also provides the ability to write local document type definitions and style sheets, called Local.DTD and Local.DSL , respectively. These allow for the introduction of additional document elements, and their renderings, on top of those provided by DocBook. For example, some of the teams at my company wanted features in the final Word document that amounted to arbitrary Word field-code support in the SGML.
To support this, I wrote a local DocBook stylesheet and definition file pair (Local.DSL, Local.DTD) to emit the sequences in RTF corresponding to the desired field codes. RTF requires unescaped characters { , } , and \\ , so I modified OpenJade to map Unicodes 0xFFFD , 0xFFFE , and 0xFFFF in the stylesheet to these unescaped characters. I also found an archived post on the docbook-apps mailing list that was extremely helpful for aligning the contents of DocBook download components into a workable hierarchy.
An Example Python API for DocBook To support development of the necessary content inserter with DocBook, I needed a Python API that could be used to quickly generate the SGML formatted documents. The design chosen for this API provides abstract classes for each document element type in a DocBook Python module. These abstract classes can be inherited in code that defines particular document structures, and can be nested arbitrarily, so that each maps to a different level or part of the output document's structure.
As an example, suppose we want to generate the following table as part of a Word document: Name Type statex Integer statey Long The SGML text used for this table is written in terms of Local.DSL and Local.DTD as follows: <!DOCTYPE informaltable SYSTEM "C:\Local.dtd"> <informaltable frame='all'> <tgroup cols='2' colsep='1' rowsep='1' align='center'> <colspec colname='Name' colwidth='75' align='left'></colspec> <colspec colname='Type' colwidth='64' align='center'></colspec> <thead> <row> <entry><emphasis role='bold'>Name</emphasis></entry> <entry><emphasis role='bold'>Type</emphasis></entry> </row> </thead> <tbody> <row> <entry><phrase role='xe' condition='italic'>statex</phrase></entry> <entry>Integer</entry> </row> <row> <entry><phrase role='xe' condition='italic'>statey</phrase></entry> <entry>Long</entry> </row> </tbody> </tgroup> </informaltable> Here is the Python listing that generates the above SGML by basing on the DocBook class tree: from DocBook import DocBook class ItalicIndexPhrase (DocBook.Rules.Phrase): "italic indexible text phrase" TITLE = DocBook.Rules.Phrase def __init__ (self, text): DocBook.Rules.Phrase.__init__ (self, 'xe'
The rest of this page is on the live site.