1 Enthought API文档工具¶
1.1 Request for Proposals¶
- Author
Janet Swisher, Senior Technical Writer
- Organization
- Copyright
2004 by Enthought, Inc.
- License
Enthought License (BSD Style)
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.
目录
1.1.1 Requirements¶
The documentation tool will address the following high-level goals:
1.1.1.1 Documentation Extraction¶
Documentation will be generated directly from Python source code, drawing from the code structure, docstrings, and possibly other comments.
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.
1.1.1.2 Source Format¶
The docstrings will be formatted in as terse syntax as possible. Required tags, syntax, and white space should be minimized.
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://code.enthought.com/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(), }
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.
1.1.1.3 Output Format¶
Documentation will be output as a navigable suite of HTML files.
The style of the HTML files will be customizable by a cascading style sheet and/or a customizable template.
Page elements such as headers and footer should be customizable, to support differing requirements from one documentation project to the next.
1.1.2 License¶
Enthought intends to release the software under an open-source (“BSD-style”) license.