[XML-SIG] Confused and grasping

uche.ogbuji@fourthought.com uche.ogbuji@fourthought.com
Mon, 27 Sep 1999 20:29:16 -0400


Paul Prescod:

>The Python community will one day have its own package used for the
>Python documentation but it doesn't have that yet.

And speaking of...  What of a py-doc schema?  Mike and I were just discussing 
this.  Does Fred Drake have any ideas?  Is there anything from Javadoc we 
might borrow?

Here is what we've very tentatively set up for FourThought:



<!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:crea
tion_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
>



And here's a style-sheet that we've been using to generate HTML doc pages.



<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>


What does everyone think?  Could we hack the hell out of it on this list and 
adopt it for standard Python docs.


-- 
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