[XML-SIG] PyDoc/XML?
uche.ogbuji@fourthought.com
uche.ogbuji@fourthought.com
Mon, 27 Sep 1999 20:36:35 -0400
This is a multipart MIME message.
--==_Exmh_20014085760
Content-Type: text/plain; charset=us-ascii
I just realized that it might be easier to extract the proposed DTD and
stylesheet if they're attachments. So I've attached them to this message.
I should also note that the schema we came up with was to cover Java, IDL and
C as well as Python, although Python was 98% of its target.
And finally, I also included a sample XML doc file according to the DTD, and
the HTML that comes from the style-sheet.
--
Uche Ogbuji
FourThought LLC, IT Consultants
uche.ogbuji@fourthought.com (970)481-0805
Software engineering, project management, Intranets and Extranets
http://FourThought.com http://OpenTechnology.org
--==_Exmh_20014085760
Content-Type: text/html ; name="example.html"; charset=us-ascii
Content-Description: example.html
Content-Disposition: attachment; filename="example.html"
<!--This file is automagically generated. Do not edit-->
<HTML>
<HEAD>
<TITLE>
Documentation for
Example.py
</TITLE>
</HEAD>
<BODY>
<H1>
The
Python
module
Example.py
</H1>
<P>
Code written by
Mike Olson
on
1999-04-15
.
Documentation written by
Mike Olson
.
</P>
<H3>
Description
</H3>
<P>
This document serves as a sample for all code.
</P>
<H3>
Module Dependenies
</H3>
<TABLE>
<TR>
<TD>
engine.py
</TD>
</TR>
<TR>
<TD>
wheels.py
</TD>
</TR>
</TABLE>
<H3>
External Documentation References
</H3>
<TABLE>
<TR>
<TD>
<A HREF = '/documents/design/design_doc.html'>Design Doc</A>
</TD>
</TR>
</TABLE>
<H2>
Definition of Class
Jeep
</H2>
<H3>
Base Classes
</H3>
<TABLE>
<TR>
<TD>
SUV
</TD>
</TR>
</TABLE>
<H3>
Public Member Variables
</H3>
<TABLE BORDER = '1'>
<TR>
<TD>
Engine *
m_engine
</TD>
<TD>
A pointer to the engine that makes it go
</TD>
</TR>
<TR>
<TD>
Wheels [4]
m_wheels
</TD>
<TD>
The wheels attached to this instance of the Jeep
</TD>
</TR>
</TABLE>
<H3>
Public Class Methods
</H3>
<H4>
Drive
()
</H4>
<H5>
Description
</H5>
Override SUV::drive to make it go more places
<H5>
Parameters
</H5>
<TABLE BORDER = '1'>
<TR>
<TH>
Name
</TH>
<TH>
Type
</TH>
<TH>
Description
</TH>
<TH>
Constraints
</TH>
</TR>
<TR>
<TD>
<B>
where
</B>
</TD>
<TD>
<B>
Location &
</B>
</TD>
<TD>
Where to drive to
</TD>
<TD>
The location must be less the self.gas*20 miles away
</TD>
</TR>
<TR>
<TD>
<B>
maxSpeed
</B>
</TD>
<TD>
<B>
float
</B>
</TD>
<TD>
Maximum speed that should be attained during the drive.
</TD>
<TD>
The value must be greater then 0 and less then 80 miles/hr.
</TD>
</TR>
</TABLE>
<H5>
Return Value(s)
</H5>
<TABLE BORDER = '1'>
<TR>
<TH>
Type
</TH>
<TH>
Description
</TH>
<TH>
Post Condition
</TH>
</TR>
<TR>
<TD>
<B>
boolean
</B>
</TD>
<TD>
Did the Jeep make it to the location?
</TD>
<TD>
1 if the Jeep made it. 0 if the Jeep got stuck
</TD>
</TR>
</TABLE>
<BR>
<HR>
</HR>
<H4>
RemoveTop
()
</H4>
<H5>
Description
</H5>
Remove the top from the Jeep
<H5>
Parameters
</H5>
No Parameters
<H5>
Return Value(s)
</H5>
<TABLE BORDER = '1'>
<TR>
<TH>
Type
</TH>
<TH>
Description
</TH>
<TH>
Post Condition
</TH>
</TR>
<TR>
<TD>
<B>
boolean
</B>
</TD>
<TD>
The results of removing the top
</TD>
<TD>
1 if the top was removed. 0 if the top could not be removed
</TD>
</TR>
</TABLE>
<BR>
<HR>
</HR>
<H2>
Public Functions
</H2>
<H4>
GetAJeep
()
</H4>
<H5>
Description
</H5>
Get a reference to a Jeep
<H5>
Parameters
</H5>
No Parameters
<H5>
Return Value(s)
</H5>
<TABLE BORDER = '1'>
<TR>
<TH>
Type
</TH>
<TH>
Description
</TH>
<TH>
Post Condition
</TH>
</TR>
<TR>
<TD>
<B>
KeySet
</B>
</TD>
<TD>
Will return a set of Keys for a Jeep
</TD>
<TD>
The keys are gaurenteed to start a Jeep
</TD>
</TR>
</TABLE>
<BR>
<HR>
</HR>
</BODY>
</HTML>
--==_Exmh_20014085760
Content-Type: text/plain ; name="example.xml"; charset=us-ascii
Content-Description: example.xml
Content-Disposition: attachment; filename="example.xml"
<?xml version="1.0"?>
<!DOCTYPE doc:module SYSTEM "module_doc.dtd">
<?xml-stylesheet href="module_doc.xsl" ?>
<doc:module CVS_ROOT="ext:liszt:/var/local/cvsroot" CVS_FILENAME="examples/documentation.xml,v" ID = "Example">
<doc:overview>
<doc:module_name>Example.py</doc:module_name>
<doc:module_language>Python</doc:module_language>
<doc:author>
<doc:code_author>Mike Olson</doc:code_author>
<doc:documentation_author>Mike Olson</doc:documentation_author>
</doc:author>
<doc:creation_date>1999-04-15</doc:creation_date>
<doc:description>This document serves as a sample for all code.</doc:description>
<doc:dependency_list>
<doc:dependency MODULE='ENGINE'>engine.py</doc:dependency>
<doc:dependency MODULE='WHEELS'>wheels.py</doc:dependency>
</doc:dependency_list>
<doc:reference_list>
<doc:reference href='/documents/design/design_doc.html'>Design Doc</doc:reference>
</doc:reference_list>
</doc:overview>
<doc:class NAME='Jeep' ID = 'JEEP'>
<doc:base_class CLASS = 'SUV'>SUV</doc:base_class>
<doc:member NAME='m_wheels' TYPE = 'Wheels [4]'>The wheels attached to this instance of the Jeep</doc:member>
<doc:member NAME='m_engine' TYPE = 'Engine *'>A pointer to the engine that makes it go</doc:member>
<doc:function NAME='Drive'>
<doc:description>Override SUV::drive to make it go more places</doc:description>
<doc:parameter NAME='where' TYPE='Location &'>
<doc:description>Where to drive to</doc:description>
<doc:constraint>The location must be less the self.gas*20 miles away</doc:constraint>
</doc:parameter>
<doc:parameter NAME='maxSpeed' TYPE='float'>
<doc:description>Maximum speed that should be attained during the drive.</doc:description>
<doc:constraint>The value must be greater then 0 and less then 80 miles/hr.</doc:constraint>
</doc:parameter>
<doc:return_value TYPE='boolean'>
<doc:description>Did the Jeep make it to the location?</doc:description>
<doc:post_condition>1 if the Jeep made it. 0 if the Jeep got stuck</doc:post_condition>
</doc:return_value>
</doc:function>
<doc:function NAME='RemoveTop'>
<doc:description>Remove the top from the Jeep</doc:description>
<doc:return_value TYPE='boolean'>
<doc:description>The results of removing the top</doc:description>
<doc:post_condition>1 if the top was removed. 0 if the top could not be removed</doc:post_condition>
</doc:return_value>
</doc:function>
</doc:class>
<doc:function NAME='GetAJeep'>
<doc:description>Get a reference to a Jeep</doc:description>
<doc:return_value TYPE='KeySet'>
<doc:description>Will return a set of Keys for a Jeep</doc:description>
<doc:post_condition>The keys are gaurenteed to start a Jeep</doc:post_condition>
</doc:return_value>
</doc:function>
</doc:module>
--==_Exmh_20014085760
Content-Type: text/plain ; name="module_doc.xsl"; charset=us-ascii
Content-Description: module_doc.xsl
Content-Disposition: attachment; filename="module_doc.xsl"
<xsl:stylesheet>
<xsl:template match='doc:module'>
<xsl:comment>This file is automagically generated. Do not edit</xsl:comment>
<HTML>
<HEAD>
<TITLE>Documentation for <xsl:value-of select='doc:overview/doc:module_name'/></TITLE>
</HEAD>
<BODY>
<xsl:apply-templates select='doc:overview|doc:class'/>
<H2>Public Functions</H2>
<xsl:apply-templates select='doc:function'/>
</BODY>
</HTML>
</xsl:template>
<xsl:template match='doc:overview'>
<H1>The <xsl:value-of select = 'doc:module_language'/> module <xsl:value-of select='doc:module_name'/></H1>
<P>Code written by <xsl:value-of select='doc:author/doc:code_author'/>
on <xsl:value-of select = 'doc:creation_date'/>.
Documentation written by
<xsl:choose>
<xsl:when test = '.[./doc:author/doc:documentation_author]'>
<xsl:value-of select='doc:author/doc:documentation_author'/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select='doc:author/doc:code_author'/>
</xsl:otherwise>
</xsl:choose>
.</P>
<H3>Description</H3>
<P>
<xsl:value-of select='doc:description'/>
</P>
<xsl:apply-templates select='doc:dependency_list'/>
<xsl:apply-templates select='doc:reference_list'/>
</xsl:template>
<xsl:template match='doc:dependency_list'>
<H3>Module Dependenies</H3>
<TABLE>
<xsl:apply-templates />
</TABLE>
</xsl:template>
<xsl:template match='doc:dependency'>
<TR><TD>
<xsl:value-of select='.'/>
</TD></TR>
</xsl:template>
<xsl:template match='doc:reference_list'>
<H3>External Documentation References</H3>
<TABLE>
<xsl:apply-templates />
</TABLE>
</xsl:template>
<xsl:template match='doc:reference'>
<TR><TD>
<A HREF='{@href}'>
<xsl:value-of select='.'/>
</A>
</TD></TR>
</xsl:template>
<xsl:template match='doc:class'>
<H2>Definition of Class <xsl:value-of select='@NAME'/></H2>
<H3> Base Classes </H3>
<TABLE>
<xsl:apply-templates select = 'doc:base_class'/>
</TABLE>
<H3> Public Member Variables </H3>
<TABLE BORDER='1'>
<xsl:apply-templates select='doc:member'>
<xsl:sort select='@NAME'/>
</xsl:apply-templates>
</TABLE>
<H3> Public Class Methods </H3>
<xsl:apply-templates select='doc:function'>
<xsl:sort select='@NAME'/>
</xsl:apply-templates>
</xsl:template>
<xsl:template match='doc:base_class'>
<TR><TD>
<xsl:value-of select='.'/>
</TD></TR>
</xsl:template>
<xsl:template match='doc:member'>
<TR>
<TD>
<xsl:value-of select='@TYPE'/>
<xsl:text> </xsl:text>
<xsl:value-of select='@NAME'/>
</TD>
<TD>
<xsl:value-of select='.'/>
</TD>
</TR>
</xsl:template>
<xsl:template match='doc:function'>
<H4>
<xsl:value-of select='@NAME'/>()
</H4>
<H5>Description</H5>
<xsl:value-of select='doc:description'/>
<H5>Parameters</H5>
<xsl:choose>
<xsl:when test='.[./doc:parameter]'>
<TABLE BORDER='1'>
<TR>
<TH>Name</TH>
<TH>Type</TH>
<TH>Description</TH>
<TH>Constraints</TH>
</TR>
<xsl:for-each select='doc:parameter'>
<TR>
<TD><B><xsl:value-of select='@NAME'/></B></TD>
<TD><B><xsl:value-of select='@TYPE'/></B></TD>
<TD><xsl:value-of select='doc:description'/></TD>
<TD><xsl:value-of select='doc:constraint'/></TD>
</TR>
</xsl:for-each>
</TABLE>
</xsl:when>
<xsl:otherwise>
No Parameters
</xsl:otherwise>
</xsl:choose>
<H5>Return Value(s)</H5>
<TABLE BORDER='1'>
<TR>
<TH>Type</TH>
<TH>Description</TH>
<TH>Post Condition</TH>
</TR>
<xsl:for-each select='doc:return_value'>
<TR>
<TD><B><xsl:value-of select='@TYPE'/></B></TD>
<TD><xsl:value-of select='doc:description'/></TD>
<TD><xsl:value-of select='doc:post_condition'/></TD>
</TR>
</xsl:for-each>
</TABLE>
<BR></BR>
<HR></HR>
</xsl:template>
</xsl:stylesheet>
--==_Exmh_20014085760
Content-Type: text/plain; name="module_doc.dtd"; charset=us-ascii
Content-Description: module_doc.dtd
Content-Disposition: attachment; filename="module_doc.dtd"
<!ELEMENT doc:module (doc:overview,doc:class?,doc:function*)>
<!ATTLIST doc:module
CVS_ROOT CDATA #REQUIRED
CVS_FILENAME CDATA #REQUIRED
ID ID #REQUIRED
>
<!-- this will give a brief overview of the module -->
<!ELEMENT doc:overview (doc:module_name,doc:module_language,doc:author,doc:creation_date,doc:description,doc:dependency_list,doc:reference_list)>
<!-- The short name (not the full RCS File name) -->
<!ELEMENT doc:module_name (#PCDATA)>
<!ELEMENT doc:module_language (#PCDATA)>
<!-- Who wrote this stuff -->
<!ELEMENT doc:author (doc:code_author,doc:documentation_author?)>
<!-- Who wrote the original code -->
<!ELEMENT doc:code_author (#PCDATA)>
<!-- Who wrote the original documentation
If this is not in the AUTHOR tag the CODE_AUTHOR
will be assumed
-->
<!ELEMENT doc:documentation_author (#PCDATA)>
<!--When was the code created in ISO 8601-->
<!ELEMENT doc:creation_date (#PCDATA)>
<!-- A quick description -->
<!ELEMENT doc:description (#PCDATA)>
<!-- A container for the dependencies -->
<!ELEMENT doc:dependency_list (doc:dependency*)>
<!-- The module that this module is dependent on -->
<!ELEMENT doc:dependency (#PCDATA)>
<!ATTLIST doc:dependency
MODULE IDREF #REQUIRED
>
<!-- A container for the references -->
<!ELEMENT doc:reference_list (doc:reference*)>
<!-- The module that this module references ie a design -->
<!ELEMENT doc:reference (#PCDATA)>
<!ATTLIST doc:reference
xml:link CDATA #FIXED 'simple'
href CDATA #REQUIRED
>
<!-- This defines the documentation for a function. It can exist at the
global level, or inside a class (for a member). The documentation is the
same in either case.
-->
<!ELEMENT doc:function (doc:description,doc:parameter*,doc:return_value+)>
<!ATTLIST doc:function
NAME CDATA #REQUIRED
>
<!-- all inout parameters must be defined as both parameter and return_value -->
<!-- Represents on 'in' parameter for the function or 1/2 of an 'inout'-->
<!ELEMENT doc:parameter (doc:description,doc:constraint)>
<!ATTLIST doc:parameter
NAME CDATA #REQUIRED
TYPE CDATA #REQUIRED
>
<!-- Defines in prose a list of constraints on the parameter ie 1-10 -->
<!ELEMENT doc:constraint (#PCDATA)>
<!-- Represents the return value, and 'out' parameterm or 1/2 of an 'inout' -->
<!ELEMENT doc:return_value (doc:description,doc:post_condition)>
<!ATTLIST doc:return_value
TYPE CDATA #REQUIRED
>
<!-- In prose define the changes to a variable, or the constraints on a
return value ie will always be 1 or 0
-->
<!ELEMENT doc:post_condition (#PCDATA)>
<!-- This defines a class, it has base classes, members and methods-->
<!ELEMENT doc:class (doc:base_class*,doc:member*,doc:function*)>
<!ATTLIST doc:class
NAME CDATA #REQUIRED
ID ID #REQUIRED
>
<!ELEMENT doc:base_class (#PCDATA)>
<!ATTLIST doc:base_class
CLASS IDREF #REQUIRED
>
<!ELEMENT doc:member (#PCDATA)>
<!ATTLIST doc:member
NAME CDATA #REQUIRED
TYPE CDATA #REQUIRED
>
--==_Exmh_20014085760--