Package epydoc :: Package docwriter :: Module html_help
[hide private]
[frames] | no frames]

Source Code for Module epydoc.docwriter.html_help

  1  # 
  2  # epydoc.css: default help page 
  3  # Edward Loper 
  4  # 
  5  # Created [01/30/01 05:18 PM] 
  6  # $Id: 1239 2006-07-05 11:29:50Z edloper $ 
  7  # 
  9  """ 
 10  Default help file for the HTML outputter (L{epydoc.docwriter.html}). 
 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' 
 18  # Expects: {'this_project': name} 
 19  HTML_HELP = ''' 
 20  <h1 class="epydoc"> API Documentation </h1> 
 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> 
 29  <h2> Object Documentation </h2> 
 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> 
 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> 
 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> 
 74  <h2> Project Documentation </h2> 
 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> 
 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> 
 99  <h2> The Table of Contents </h2> 
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> 
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 />&nbsp;<br />...<br />&nbsp; 
117      </td> 
118    </tr> 
119  </table><br /> 
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> 
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> 
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> 
138  <h2> The Navigation Bar </h2> 
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> 
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> 
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> 
188  <p> A timestamp below the bottom navigation bar indicates when each 
189  page was last updated. </p> 
190  '''