1
==================================
2
Enthought API Documentation Tool
3
==================================
4
-----------------------
6
-----------------------
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)
13
.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt
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`__.
19
__ enthought-plan.html
28
The documentation tool will address the following high-level goals:
31
Documentation Extraction
32
------------------------
34
1. Documentation will be generated directly from Python source code,
35
drawing from the code structure, docstrings, and possibly other
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
47
1. The docstrings will be formatted in as terse syntax as possible.
48
Required tags, syntax, and white space should be minimized.
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
58
# The current selection within the frame.
59
'selection' : Trait([], TraitInstance(list)),
61
# The frame has been activated or deactivated.
62
'activated' : TraitEvent(),
64
'closing' : TraitEvent(),
66
# The frame is closed.
67
'closed' : TraitEvent(),
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
81
1. Documentation will be output as a navigable suite of HTML
84
2. The style of the HTML files will be customizable by a cascading
85
style sheet and/or a customizable template.
87
3. Page elements such as headers and footer should be customizable, to
88
support differing requirements from one documentation project to
92
Output Structure and Navigation
93
-------------------------------
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)
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.
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.
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
117
5. The HTML suite should provide consistent navigation back to the
118
home page, which will include the following information:
120
* Bibliographic information
131
- Links to related internal docs (i.e., other docs for the same
134
- Links to related external docs (e.g., supporting development
135
docs, Python support docs, docs for included packages)
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.
145
Enthought intends to release the software under an open-source
146
("BSD-style") license.
added
removed
docs/dev/enthought-rfp.txt
