1
2
3
4
5
6
7
8
9 """
10 Default help file for the HTML outputter (L{epydoc.docwriter.html}).
11
12 @type HTML_HELP: C{string}
13 @var HTML_HELP: The contents of the HTML body for the default
14 help page.
15 """
16 __docformat__ = 'epytext en'
17
18
19 HTML_HELP = '''
20 <h1 class="epydoc"> API Documentation </h1>
21
22 <p> This document contains the API (Application Programming Interface)
23 documentation for %(this_project)s. Documentation for the Python
24 objects defined by the project is divided into separate pages for each
25 package, module, and class. The API documentation also includes two
26 pages containing information about the project as a whole: a trees
27 page, and an index page. </p>
28
29 <h2> Object Documentation </h2>
30
31 <p>Each <strong>Package Documentation</strong> page contains: </p>
32 <ul>
33 <li> A description of the package. </li>
34 <li> A list of the modules and sub-packages contained by the
35 package. </li>
36 <li> A summary of the classes defined by the package. </li>
37 <li> A summary of the functions defined by the package. </li>
38 <li> A summary of the variables defined by the package. </li>
39 <li> A detailed description of each function defined by the
40 package. </li>
41 <li> A detailed description of each variable defined by the
42 package. </li>
43 </ul>
44
45 <p>Each <strong>Module Documentation</strong> page contains:</p>
46 <ul>
47 <li> A description of the module. </li>
48 <li> A summary of the classes defined by the module. </li>
49 <li> A summary of the functions defined by the module. </li>
50 <li> A summary of the variables defined by the module. </li>
51 <li> A detailed description of each function defined by the
52 module. </li>
53 <li> A detailed description of each variable defined by the
54 module. </li>
55 </ul>
56
57 <p>Each <strong>Class Documentation</strong> page contains: </p>
58 <ul>
59 <li> A class inheritance diagram. </li>
60 <li> A list of known subclasses. </li>
61 <li> A description of the class. </li>
62 <li> A summary of the methods defined by the class. </li>
63 <li> A summary of the instance variables defined by the class. </li>
64 <li> A summary of the class (static) variables defined by the
65 class. </li>
66 <li> A detailed description of each method defined by the
67 class. </li>
68 <li> A detailed description of each instance variable defined by the
69 class. </li>
70 <li> A detailed description of each class (static) variable defined
71 by the class. </li>
72 </ul>
73
74 <h2> Project Documentation </h2>
75
76 <p> The <strong>Trees</strong> page contains the module and class hierarchies: </p>
77 <ul>
78 <li> The <em>module hierarchy</em> lists every package and module, with
79 modules grouped into packages. At the top level, and within each
80 package, modules and sub-packages are listed alphabetically. </li>
81 <li> The <em>class hierarchy</em> lists every class, grouped by base
82 class. If a class has more than one base class, then it will be
83 listed under each base class. At the top level, and under each base
84 class, classes are listed alphabetically. </li>
85 </ul>
86
87 <p> The <strong>Index</strong> page contains indices of terms and
88 identifiers: </p>
89 <ul>
90 <li> The <em>term index</em> lists every term indexed by any object\'s
91 documentation. For each term, the index provides links to each
92 place where the term is indexed. </li>
93 <li> The <em>identifier index</em> lists the (short) name of every package,
94 module, class, method, function, variable, and parameter. For each
95 identifier, the index provides a short description, and a link to
96 its documentation. </li>
97 </ul>
98
99 <h2> The Table of Contents </h2>
100
101 <p> The table of contents occupies the two frames on the left side of
102 the window. The upper-left frame displays the <em>project
103 contents</em>, and the lower-left frame displays the <em>module
104 contents</em>: </p>
105
106 <table class="help summary" border="1" cellspacing="0" cellpadding="3">
107 <tr style="height: 30%%">
108 <td align="center" style="font-size: small">
109 Project<br />Contents<hr />...</td>
110 <td align="center" style="font-size: small" rowspan="2" width="70%%">
111 API<br />Documentation<br />Frame<br /><br /><br />
112 </td>
113 </tr>
114 <tr>
115 <td align="center" style="font-size: small">
116 Module<br />Contents<hr /> <br />...<br />
117 </td>
118 </tr>
119 </table><br />
120
121 <p> The <strong>project contents frame</strong> contains a list of all packages
122 and modules that are defined by the project. Clicking on an entry
123 will display its contents in the module contents frame. Clicking on a
124 special entry, labeled "Everything," will display the contents of
125 the entire project. </p>
126
127 <p> The <strong>module contents frame</strong> contains a list of every
128 submodule, class, type, exception, function, and variable defined by a
129 module or package. Clicking on an entry will display its
130 documentation in the API documentation frame. Clicking on the name of
131 the module, at the top of the frame, will display the documentation
132 for the module itself. </p>
133
134 <p> The "<strong>frames</strong>" and "<strong>no frames</strong>" buttons below the top
135 navigation bar can be used to control whether the table of contents is
136 displayed or not. </p>
137
138 <h2> The Navigation Bar </h2>
139
140 <p> A navigation bar is located at the top and bottom of every page.
141 It indicates what type of page you are currently viewing, and allows
142 you to go to related pages. The following table describes the labels
143 on the navigation bar. Note that not some labels (such as
144 [Parent]) are not displayed on all pages. </p>
145
146 <table class="summary" border="1" cellspacing="0" cellpadding="3" width="100%%">
147 <tr class="summary">
148 <th>Label</th>
149 <th>Highlighted when...</th>
150 <th>Links to...</th>
151 </tr>
152 <tr><td valign="top"><strong>[Parent]</strong></td>
153 <td valign="top"><em>(never highlighted)</em></td>
154 <td valign="top"> the parent of the current package </td></tr>
155 <tr><td valign="top"><strong>[Package]</strong></td>
156 <td valign="top">viewing a package</td>
157 <td valign="top">the package containing the current object
158 </td></tr>
159 <tr><td valign="top"><strong>[Module]</strong></td>
160 <td valign="top">viewing a module</td>
161 <td valign="top">the module containing the current object
162 </td></tr>
163 <tr><td valign="top"><strong>[Class]</strong></td>
164 <td valign="top">viewing a class </td>
165 <td valign="top">the class containing the current object</td></tr>
166 <tr><td valign="top"><strong>[Trees]</strong></td>
167 <td valign="top">viewing the trees page</td>
168 <td valign="top"> the trees page </td></tr>
169 <tr><td valign="top"><strong>[Index]</strong></td>
170 <td valign="top">viewing the index page</td>
171 <td valign="top"> the index page </td></tr>
172 <tr><td valign="top"><strong>[Help]</strong></td>
173 <td valign="top">viewing the help page</td>
174 <td valign="top"> the help page </td></tr>
175 </table>
176
177 <p> The "<strong>show private</strong>" and "<strong>hide private</strong>" buttons below
178 the top navigation bar can be used to control whether documentation
179 for private objects is displayed. Private objects are usually defined
180 as objects whose (short) names begin with a single underscore, but do
181 not end with an underscore. For example, "<code>_x</code>",
182 "<code>__pprint</code>", and "<code>epydoc.epytext._tokenize</code>"
183 are private objects; but "<code>re.sub</code>",
184 "<code>__init__</code>", and "<code>type_</code>" are not. However,
185 if a module defines the "<code>__all__</code>" variable, then its
186 contents are used to decide which objects are private. </p>
187
188 <p> A timestamp below the bottom navigation bar indicates when each
189 page was last updated. </p>
190 '''
191