added "Plan for Enthought API Documentation Tool" and "Enthought API Documentation Tool RFP"

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@2241 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 518 insertions, 0 deletions

diff --git a/docutils/docs/dev/enthought-plan.txt b/docutils/docs/dev/enthought-plan.txt
new file mode 100644
index 000000000..ab4bfb2d4
--- /dev/null
+++ b/docutils/docs/dev/enthought-plan.txt
@@ -0,0 +1,372 @@
+===========================================
+ Plan for Enthought API Documentation Tool
+===========================================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date$
+:Revision: $Revision$
+:Copyright: 2004 by `Enthought, Inc. <http://www.enthought.com>`_
+:License: `Enthought License`_ (BSD-style)
+
+.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt
+
+This document should be read in conjunction with the `Enthought API
+Documentation Tool RFP`__ prepared by Janet Swisher.
+
+__ enthought-rfp.html
+
+.. contents::
+.. sectnum::
+
+
+Development Plan
+================
+
+1. Analyze prior art, most notably Epydoc_ and HappyDoc_, to see how
+   they do what they do.  I have no desire to reinvent wheels
+   unnecessarily.  I want to take the best ideas from each tool,
+   combined with the outline in `PEP 258`_ (which will evolve), and
+   build at least the foundation of the definitive Python
+   auto-documentation tool.
+
+   .. _Epydoc: http://epydoc.sourceforge.net/
+   .. _HappyDoc: http://happydoc.sourceforge.net/
+   .. _PEP 258:
+      http://docutils.sf.net/spec/pep-0258.html#python-source-reader
+
+2. Decide on a base platform.  The best way to achieve Enthought's
+   goals in a reasonable time frame may be to extend Epydoc or
+   HappyDoc.  Or it may be necessary to start fresh.
+
+3. Extend the reStructuredText parser.  See `Proposed Changes to
+   reStructuredText`_ below.
+
+4. Depending on the base platform chosen, build or extend the
+   docstring & doc comment extraction tool.  This may be the biggest
+   part of the project, but I won't be able to break it down into
+   details until more is known.
+
+
+Repository
+==========
+
+If possible, all software and documentation files will be stored in
+the CVS repository of Docutils and/or the base project, which are all
+publicly-available via anonymous pserver access.
+
+The Docutils project is very open about granting CVS write access; so
+far, everyone who asked has been given access.  Any Enthought staff
+member who would like CVS write access will get it.
+
+If either Epydoc or HappyDoc is chosen as the base platform, I will
+ask the project's administrator for CVS access for myself and any
+Enthought staff member who wants it.  If sufficient access is not
+granted -- althought I doubt that there would be any problem -- we may
+have to begin a fork, which could be hosted on SourceForge, on
+Enthought's Subversion server, or anywhere else deemed appropriate.
+
+
+Copyright & License
+===================
+
+Most existing Docutils files have been placed in the public domain, as
+follows::
+
+    :Copyright: This document has been placed in the public domain.
+
+This is in conjunction with the "Public Domain Dedication" section of
+COPYING.txt__.
+
+__ http://docutils.sourceforge.net/COPYING.html
+
+The code and documentation originating from Enthought funding will
+have Enthought's copyright and license declaration.  While I will try
+to keep Enthought-specific code and documentation separate from the
+existing files, there will inevitably be cases where it makes the most
+sense to extend existing files.
+
+I propose the following:
+
+1. New files related to this Enthought-funded work will be identified
+   with the following field-list headers::
+
+       :Copyright: 2004 by Enthought, Inc.
+       :License: Enthought License (BSD Style)
+
+   The license field text will be linked to the license file itself.
+
+2. For significant or major changes to an existing file (more than 10%
+   change), the headers shall change as follows (for example)::
+
+       :Copyright: 2001-2004 by David Goodger
+       :Copyright: 2004 by Enthought, Inc.
+       :License: BSD-style
+
+   If the Enthought-funded portion becomes greater than the previously
+   existing portion, Enthought's copyright line will be shown first.
+
+3. In cases of insignificant or minor changes to an existing file
+   (less than 10% change), the public domain status shall remain
+   unchanged.
+
+A section describing all of this will be added to the Docutils
+`COPYING`__ instructions file.
+
+If another project is chosen as the base project, similar changes
+would be made to their files, subject to negotiation.
+
+__ http://docutils.sf.net/COPYING.html
+
+
+Proposed Changes to reStructuredText
+====================================
+
+Doc Comment Syntax
+------------------
+
+The "traits" construct is implemented as dictionaries, where
+standalone strings would be Python syntax errors.  Therefore traits
+require documentation in comments.  We also need a way to
+differentiate between ordinary "internal" comments and documentation
+comments (doc comments).
+
+Javadoc uses the following syntax for doc comments::
+
+    /**
+     * The first line of a multi-line doc comment begins with a slash
+     * and *two* asterisks.  The doc comment ends normally.
+     */
+
+Python doesn't have multi-line comments; only single-line.  A similar
+convention in Python might look like this::
+
+    ##
+    # The first line of a doc comment begins with *two* hash marks.
+    # The doc comment ends with the first non-comment line.
+    'data' : AnyValue,
+
+    ## The double-hash-marks could occur on the first line of text,
+    #  saving a line in the source.
+    'data' : AnyValue,
+
+How to indicate the end of the doc comment? ::
+
+    ##
+    # The first line of a doc comment begins with *two* hash marks.
+    # The doc comment ends with the first non-comment line, or another
+    # double-hash-mark.
+    ##
+    # This is an ordinary, internal, non-doc comment.
+    'data' : AnyValue,
+
+    ## First line of a doc comment, terse syntax.
+    #  Second (and last) line.  Ends here: ##
+    # This is an ordinary, internal, non-doc comment.
+    'data' : AnyValue,
+
+Or do we even need to worry about this case?  A simple blank line
+could be used::
+
+    ## First line of a doc comment, terse syntax.
+    #  Second (and last) line.  Ends with a blank line.
+
+    # This is an ordinary, internal, non-doc comment.
+    'data' : AnyValue,
+
+Other possibilities::
+
+    #" Instead of double-hash-marks, we could use a hash mark and a
+    #  quotation mark to begin the doc comment.
+    'data' : AnyValue,
+
+    ## We could require double-hash-marks on every line.  This has the
+    ## added benefit of delimiting the *end* of the doc comment, as
+    ## well as working well with line wrapping in Emacs
+    ## ("fill-paragraph" command).
+    # Ordinary non-doc comment.
+    'data' : AnyValue,
+
+    #" A hash mark and a quotation mark on each line looks funny, and
+    #" it doesn't work well with line wrapping in Emacs.
+    'data' : AnyValue,
+
+These styles (repeated on each line) work well with line wrapping in
+Emacs::
+
+    ##  #>  #|  #-  #%  #!  #*
+
+These styles do *not* work well with line wrapping in Emacs::
+
+    #"  #'  #:  #)  #.  #/  #@  #$  #^  #=  #+  #_  #~
+
+The style of doc comment indicator used could be a runtime, global
+and/or per-module setting.  That may add more complexity than it's
+worth though.
+
+
+Recommendation
+``````````````
+
+I recommend adopting "#*" on every line::
+
+    # This is an ordinary non-doc comment.
+
+    #* This is a documentation comment, with an asterisk after the
+    #* hash marks on every line.
+    'data' : AnyValue,
+
+I initially recommended adopting double-hash-marks::
+
+    # This is an ordinary non-doc comment.
+
+    ## This is a documentation comment, with double-hash-marks on
+    ## every line.
+    'data' : AnyValue,
+
+But Janet Swisher rightly pointed out that this could collide with
+ordinary comments that are then block-commented.  This applies to
+double-hash-marks on the first line only as well.  So they're out.
+
+
+Docstring Density & Whitespace Minimization
+-------------------------------------------
+
+One problem with extensively documented classes & functions, is that
+there is a lot of screen space wasted on whitespace.  Here's some
+current Enthought code (from lib/cp/fluids/gassmann.py)::
+
+    def max_gas(temperature, pressure, api, specific_gravity=.56):
+        """
+        Computes the maximum dissolved gas in oil using Batzle and
+        Wang (1992).
+
+        Parameters
+        ----------
+        temperature : sequence
+            Temperature in degrees Celsius
+        pressure: sequence
+            Pressure in MPa
+        api : sequence
+            Stock tank oil API
+        specific_gravity : sequence
+            Specific gravity of gas at STP, default is .56
+
+        Returns
+        -------
+        max_gor : sequence
+            Maximum dissolved gas in liters/liter
+
+        Description
+        -----------
+        This estimate is based on equations given by Mavko, Mukerji,
+        and Dvorkin, (1998, pp. 218-219, or 2003, p. 236) obtained
+        originally from Batzle and Wang (1992).
+        """
+        code...
+
+The docstring is 24 lines long.
+
+Rather than using subsections, field lists (which exist now) can save
+5 lines::
+
+    def max_gas(temperature, pressure, api, specific_gravity=.56):
+        """
+        Computes the maximum dissolved gas in oil using Batzle and
+        Wang (1992).
+
+        :Parameters:
+            temperature : sequence
+                Temperature in degrees Celsius
+            pressure: sequence
+                Pressure in MPa
+            api : sequence
+                Stock tank oil API
+            specific_gravity : sequence
+                Specific gravity of gas at STP, default is .56
+        :Returns:
+            max_gor : sequence
+                Maximum dissolved gas in liters/liter
+        :Description:
+            This estimate is based on equations given by Mavko,
+            Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, p. 236)
+            obtained originally from Batzle and Wang (1992).
+        """
+        code...
+
+The output for field lists is typically a table structure.  For
+example:
+
+    :Parameters:
+        temperature : sequence
+            Temperature in degrees Celsius
+        pressure: sequence
+            Pressure in MPa
+        api : sequence
+            Stock tank oil API
+        specific_gravity : sequence
+            Specific gravity of gas at STP, default is .56
+    :Returns:
+        max_gor : sequence
+            Maximum dissolved gas in liters/liter
+    :Description:
+        This estimate is based on equations given by Mavko,
+        Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, p. 236)
+        obtained originally from Batzle and Wang (1992).
+
+But the definition lists describing the parameters and return values
+are still wasteful of space.  There are a lot of half-filled lines.
+
+Definition lists are currently defined as::
+
+    term : classifier
+        definition
+
+Where the classifier part is optional.
+
+* We could allow multiple classifiers::
+
+      term : classifier one : two : three ...
+          definition
+
+* We could allow the definition on the same line as the term, but only
+  in limited and well-known contexts::
+
+      term -- definition
+
+  This is the syntax used by StructuredText (one of reStructuredText's
+  predecessors).  It was not adopted for reStructuredText because it
+  is ambiguous -- people often use "--" in their text, as I just did.
+  But given a constrained context, the ambiguity would be acceptable.
+  That context would be: in docstrings, within a field list, perhaps
+  only with certain well-defined field names (parameters, returns).
+
+
+Recommendation
+``````````````
+
+Combining these ideas, the function definition becomes::
+
+    def max_gas(temperature, pressure, api, specific_gravity=.56):
+        """
+        Computes the maximum dissolved gas in oil using Batzle and
+        Wang (1992).
+
+        :Parameters:
+            temperature : sequence -- Temperature in degrees Celsius
+            pressure: sequence -- Pressure in MPa
+            api : sequence -- Stock tank oil API
+            specific_gravity : sequence -- Specific gravity of gas at
+                STP, default is .56
+        :Returns:
+            max_gor : sequence -- Maximum dissolved gas in liters/liter
+        :Description:
+            This estimate is based on equations given by Mavko,
+            Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, p. 236)
+            obtained originally from Batzle and Wang (1992).
+        """
+        code...
+
+The docstring is reduced to 15 lines, from the original 24.  For
+longer docstrings with many parameters and return values, the
+difference would be more significant.
diff --git a/docutils/docs/dev/enthought-rfp.txt b/docutils/docs/dev/enthought-rfp.txt
new file mode 100644
index 000000000..31b483229
--- /dev/null
+++ b/docutils/docs/dev/enthought-rfp.txt
@@ -0,0 +1,146 @@
+==================================
+ Enthought API Documentation Tool
+==================================
+-----------------------
+ Request for Proposals
+-----------------------
+
+:Author: Janet Swisher, Senior Technical Writer
+:Organization: `Enthought, Inc. <http://www.enthought.com>`_
+:Copyright: 2004 by Enthought, Inc.
+:License: `Enthought License`_ (BSD Style)
+
+.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt
+
+The following is excerpted from the full RFP, and is published here
+with permission from `Enthought, Inc.`_  See the `Plan for Enthought
+API Documentation Tool`__.
+
+__ enthought-plan.html
+
+.. contents::
+.. sectnum::
+
+
+Requirements
+============
+
+The documentation tool will address the following high-level goals:
+
+
+Documentation Extraction
+------------------------
+
+1. Documentation will be generated directly from Python source code,
+   drawing from the code structure, docstrings, and possibly other
+   comments.
+
+2. The tool will extract logical constructs as appropriate, minimizing
+   the need for comments that are redundant with the code structure.
+   The output should reflect both documented and undocumented
+   elements.
+
+
+Source Format
+-------------
+
+1. The docstrings will be formatted in as terse syntax as possible.
+   Required tags, syntax, and white space should be minimized.
+
+2. The tool must support the use of Traits.  Special comment syntax
+   for Traits may be necessary.  Information about the Traits package
+   is available at http://old.scipy.org/site_content/traits.  In the
+   following example, each trait definition is prefaced by a plain
+   comment::
+
+       __traits__ = {
+
+       # The current selection within the frame.
+       'selection' : Trait([], TraitInstance(list)),
+
+       # The frame has been activated or deactivated.
+       'activated' : TraitEvent(),
+
+       'closing' : TraitEvent(),
+
+       # The frame is closed.
+       'closed' : TraitEvent(),
+       }
+
+3. Support for ReStructuredText (ReST) format is desirable, because
+   much of the existing docstrings uses ReST.  However, the complete
+   ReST specification need not be supported, if a subset can achieve
+   the project goals.  If the tool does not support ReST, the
+   contractor should also provide a tool or path to convert existing
+   docstrings.
+
+
+Output Format
+-------------
+
+1. Documentation will be output as a navigable suite of HTML
+   files.
+
+2. The style of the HTML files will be customizable by a cascading
+   style sheet and/or a customizable template.
+
+3. Page elements such as headers and footer should be customizable, to
+   support differing requirements from one documentation project to
+   the next.
+
+
+Output Structure and Navigation
+-------------------------------
+
+1. The navigation scheme for the HTML files should not rely on frames,
+   and should harmonize with conversion to Microsoft HTML Help (.chm)
+   format.
+
+2. The output should be structured to make navigable the architecture
+   of the Python code.  Packages, modules, classes, traits, and
+   functions should be presented in clear, logical hierarchies.
+   Diagrams or trees for inheritance, collaboration, sub-packaging,
+   etc. are desirable but not required.
+
+3. The output must include indexes that provide a comprehensive view
+   of all packages, modules, and classes.  These indexes will provide
+   readers with a clear and exhaustive view of the code base.  These
+   indexes should be presented in a way that is easily accessible and
+   allows easy navigation.
+
+4. Cross-references to other documented elements will be used
+   throughout the documentation, to enable the reader to move quickly
+   relevant information.  For example, where type information for an
+   element is available, the type definition should be
+   cross-referenced.
+
+5. The HTML suite should provide consistent navigation back to the
+   home page, which will include the following information: o
+
+   * Bibliographic information
+
+     - Author
+     - Copyright
+     - Release date
+     - Version number
+
+   * Abstract
+
+   * References
+
+     - Links to related internal docs (i.e., other docs for the same
+       product)
+
+     - Links to related external docs (e.g., supporting development
+       docs, Python support docs, docs for included packages)
+
+   It should be possible to specify similar information at the top
+   level of each package, so that packages can be included as
+   appropriate for a given application.
+
+
+License
+=======
+
+Enthought intends to release the software under an open-source
+("BSD-style") license.