"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "docutils-0.5/docs/dev/enthought-rfp.txt" of archive docutils-0.5.tar.gz:

    1 ==================================
    2  Enthought API Documentation Tool
    3 ==================================
    4 -----------------------
    5  Request for Proposals
    6 -----------------------
    7 
    8 :Author: Janet Swisher, Senior Technical Writer
    9 :Organization: `Enthought, Inc. <http://www.enthought.com>`_
   10 :Copyright: 2004 by Enthought, Inc.
   11 :License: `Enthought License`_ (BSD Style)
   12 
   13 .. _Enthought License: http://docutils.sf.net/licenses/enthought.txt
   14 
   15 The following is excerpted from the full RFP, and is published here
   16 with permission from `Enthought, Inc.`_  See the `Plan for Enthought
   17 API Documentation Tool`__.
   18 
   19 __ enthought-plan.html
   20 
   21 .. contents::
   22 .. sectnum::
   23 
   24 
   25 Requirements
   26 ============
   27 
   28 The documentation tool will address the following high-level goals:
   29 
   30 
   31 Documentation Extraction
   32 ------------------------
   33 
   34 1. Documentation will be generated directly from Python source code,
   35    drawing from the code structure, docstrings, and possibly other
   36    comments.
   37 
   38 2. The tool will extract logical constructs as appropriate, minimizing
   39    the need for comments that are redundant with the code structure.
   40    The output should reflect both documented and undocumented
   41    elements.
   42 
   43 
   44 Source Format
   45 -------------
   46 
   47 1. The docstrings will be formatted in as terse syntax as possible.
   48    Required tags, syntax, and white space should be minimized.
   49 
   50 2. The tool must support the use of Traits.  Special comment syntax
   51    for Traits may be necessary.  Information about the Traits package
   52    is available at http://code.enthought.com/traits/.  In the
   53    following example, each trait definition is prefaced by a plain
   54    comment::
   55 
   56        __traits__ = {
   57 
   58        # The current selection within the frame.
   59        'selection' : Trait([], TraitInstance(list)),
   60 
   61        # The frame has been activated or deactivated.
   62        'activated' : TraitEvent(),
   63 
   64        'closing' : TraitEvent(),
   65 
   66        # The frame is closed.
   67        'closed' : TraitEvent(),
   68        }
   69 
   70 3. Support for ReStructuredText (ReST) format is desirable, because
   71    much of the existing docstrings uses ReST.  However, the complete
   72    ReST specification need not be supported, if a subset can achieve
   73    the project goals.  If the tool does not support ReST, the
   74    contractor should also provide a tool or path to convert existing
   75    docstrings.
   76 
   77 
   78 Output Format
   79 -------------
   80 
   81 1. Documentation will be output as a navigable suite of HTML
   82    files.
   83 
   84 2. The style of the HTML files will be customizable by a cascading
   85    style sheet and/or a customizable template.
   86 
   87 3. Page elements such as headers and footer should be customizable, to
   88    support differing requirements from one documentation project to
   89    the next.
   90 
   91 
   92 Output Structure and Navigation
   93 -------------------------------
   94 
   95 1. The navigation scheme for the HTML files should not rely on frames,
   96    and should harmonize with conversion to Microsoft HTML Help (.chm)
   97    format.
   98 
   99 2. The output should be structured to make navigable the architecture
  100    of the Python code.  Packages, modules, classes, traits, and
  101    functions should be presented in clear, logical hierarchies.
  102    Diagrams or trees for inheritance, collaboration, sub-packaging,
  103    etc. are desirable but not required.
  104 
  105 3. The output must include indexes that provide a comprehensive view
  106    of all packages, modules, and classes.  These indexes will provide
  107    readers with a clear and exhaustive view of the code base.  These
  108    indexes should be presented in a way that is easily accessible and
  109    allows easy navigation.
  110 
  111 4. Cross-references to other documented elements will be used
  112    throughout the documentation, to enable the reader to move quickly
  113    relevant information.  For example, where type information for an
  114    element is available, the type definition should be
  115    cross-referenced.
  116 
  117 5. The HTML suite should provide consistent navigation back to the
  118    home page, which will include the following information:
  119 
  120    * Bibliographic information
  121 
  122      - Author
  123      - Copyright
  124      - Release date
  125      - Version number
  126 
  127    * Abstract
  128 
  129    * References
  130 
  131      - Links to related internal docs (i.e., other docs for the same
  132        product)
  133 
  134      - Links to related external docs (e.g., supporting development
  135        docs, Python support docs, docs for included packages)
  136 
  137    It should be possible to specify similar information at the top
  138    level of each package, so that packages can be included as
  139    appropriate for a given application.
  140 
  141 
  142 License
  143 =======
  144 
  145 Enthought intends to release the software under an open-source
  146 ("BSD-style") license.