/usr/share/doc/docutils-doc/docs/dev/enthought-rfp.html is in docutils-doc 0.14+dfsg-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 | <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
<title>Enthought API Documentation Tool</title>
<meta name="author" content="Janet Swisher, Senior Technical Writer" />
<meta name="organization" content="Enthought, Inc." />
<meta name="copyright" content="2004 by Enthought, Inc." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="enthought-api-documentation-tool">
<h1 class="title">Enthought API Documentation Tool</h1>
<h2 class="subtitle" id="request-for-proposals">Request for Proposals</h2>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Janet Swisher, Senior Technical Writer</td></tr>
<tr><th class="docinfo-name">Organization:</th>
<td><a class="first reference external" href="http://www.enthought.com">Enthought, Inc.</a></td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>2004 by Enthought, Inc.</td></tr>
<tr class="license field"><th class="docinfo-name">License:</th><td class="field-body"><a class="reference external" href="http://docutils.sf.net/licenses/enthought.txt">Enthought License</a> (BSD Style)</td>
</tr>
</tbody>
</table>
<p>The following is excerpted from the full RFP, and is published here
with permission from <a class="reference external" href="http://www.enthought.com">Enthought, Inc.</a> See the <a class="reference external" href="enthought-plan.html">Plan for Enthought
API Documentation Tool</a>.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#requirements" id="id2">1 Requirements</a><ul class="auto-toc">
<li><a class="reference internal" href="#documentation-extraction" id="id3">1.1 Documentation Extraction</a></li>
<li><a class="reference internal" href="#source-format" id="id4">1.2 Source Format</a></li>
<li><a class="reference internal" href="#output-format" id="id5">1.3 Output Format</a></li>
<li><a class="reference internal" href="#output-structure-and-navigation" id="id6">1.4 Output Structure and Navigation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#license" id="id7">2 License</a></li>
</ul>
</div>
<div class="section" id="requirements">
<h1><a class="toc-backref" href="#id2">1 Requirements</a></h1>
<p>The documentation tool will address the following high-level goals:</p>
<div class="section" id="documentation-extraction">
<h2><a class="toc-backref" href="#id3">1.1 Documentation Extraction</a></h2>
<ol class="arabic simple">
<li>Documentation will be generated directly from Python source code,
drawing from the code structure, docstrings, and possibly other
comments.</li>
<li>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.</li>
</ol>
</div>
<div class="section" id="source-format">
<h2><a class="toc-backref" href="#id4">1.2 Source Format</a></h2>
<ol class="arabic">
<li><p class="first">The docstrings will be formatted in as terse syntax as possible.
Required tags, syntax, and white space should be minimized.</p>
</li>
<li><p class="first">The tool must support the use of Traits. Special comment syntax
for Traits may be necessary. Information about the Traits package
is available at <a class="reference external" href="http://code.enthought.com/traits/">http://code.enthought.com/traits/</a>. In the
following example, each trait definition is prefaced by a plain
comment:</p>
<pre class="literal-block">
__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(),
}
</pre>
</li>
<li><p class="first">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.</p>
</li>
</ol>
</div>
<div class="section" id="output-format">
<h2><a class="toc-backref" href="#id5">1.3 Output Format</a></h2>
<ol class="arabic simple">
<li>Documentation will be output as a navigable suite of HTML
files.</li>
<li>The style of the HTML files will be customizable by a cascading
style sheet and/or a customizable template.</li>
<li>Page elements such as headers and footer should be customizable, to
support differing requirements from one documentation project to
the next.</li>
</ol>
</div>
<div class="section" id="output-structure-and-navigation">
<h2><a class="toc-backref" href="#id6">1.4 Output Structure and Navigation</a></h2>
<ol class="arabic">
<li><p class="first">The navigation scheme for the HTML files should not rely on frames,
and should harmonize with conversion to Microsoft HTML Help (.chm)
format.</p>
</li>
<li><p class="first">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.</p>
</li>
<li><p class="first">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.</p>
</li>
<li><p class="first">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.</p>
</li>
<li><p class="first">The HTML suite should provide consistent navigation back to the
home page, which will include the following information:</p>
<ul class="simple">
<li>Bibliographic information<ul>
<li>Author</li>
<li>Copyright</li>
<li>Release date</li>
<li>Version number</li>
</ul>
</li>
<li>Abstract</li>
<li>References<ul>
<li>Links to related internal docs (i.e., other docs for the same
product)</li>
<li>Links to related external docs (e.g., supporting development
docs, Python support docs, docs for included packages)</li>
</ul>
</li>
</ul>
<p>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.</p>
</li>
</ol>
</div>
</div>
<div class="section" id="license">
<h1><a class="toc-backref" href="#id7">2 License</a></h1>
<p>Enthought intends to release the software under an open-source
("BSD-style") license.</p>
</div>
</div>
</body>
</html>
|