Package epydoc
[hide private]
[frames] | no frames]

Source Code for Package epydoc

  1  # epydoc 
  2  # 
  3  # Copyright (C) 2005 Edward Loper 
  4  # Author: Edward Loper <edloper@loper.org> 
  5  # URL: <http://epydoc.sf.net> 
  6  # 
  7  # $Id: __init__.py 1750 2008-02-23 16:09:47Z edloper $ 
  8   
  9  """ 
 10  Automatic Python reference documentation generator.  Epydoc processes 
 11  Python modules and docstrings to generate formatted API documentation, 
 12  in the form of HTML pages.  Epydoc can be used via a command-line 
 13  interface (`epydoc.cli`) and a graphical interface (`epydoc.gui`). 
 14  Both interfaces let the user specify a set of modules or other objects 
 15  to document, and produce API documentation using the following steps: 
 16   
 17  1. Extract basic information about the specified objects, and objects 
 18     that are related to them (such as the values defined by a module). 
 19     This can be done via introspection, parsing, or both: 
 20   
 21     * *Introspection* imports the objects, and examines them directly 
 22       using Python's introspection mechanisms. 
 23     
 24     * *Parsing* reads the Python source files that define the objects, 
 25       and extracts information from those files. 
 26   
 27  2. Combine and process that information. 
 28   
 29     * **Merging**: Merge the information obtained from introspection & 
 30       parsing each object into a single structure. 
 31        
 32     * **Linking**: Replace any \"pointers\" that were created for 
 33       imported variables with the documentation that they point to. 
 34        
 35     * **Naming**: Assign unique *canonical names* to each of the 
 36       specified objects, and any related objects. 
 37        
 38     * **Docstrings**: Parse the docstrings of each of the specified 
 39       objects. 
 40        
 41     * **Inheritance**: Add variables to classes for any values that 
 42       they inherit from their base classes. 
 43   
 44  3. Generate output.  Output can be generated in a variety of formats: 
 45   
 46     * An HTML webpage. 
 47     
 48     * A LaTeX document (which can be rendered as a PDF file) 
 49   
 50     * A plaintext description. 
 51   
 52  .. digraph:: Overview of epydoc's architecture 
 53     :caption: The boxes represent steps in epydoc's processing chain. 
 54               Arrows are annotated with the data classes used to 
 55               communicate between steps.  The lines along the right 
 56               side mark what portions of the processing chain are 
 57               initiated by build_doc_index() and cli().  Click on 
 58               any item to see its documentation. 
 59                
 60     /* 
 61                    Python module or value                 *       * 
 62                        /           \                      |       | 
 63                       V             V                     |       | 
 64              introspect_docs()  parse_docs()              |       | 
 65                          \        /                       |       | 
 66                           V      V                        |       | 
 67                          merge_docs()                     |       | 
 68                               |              build_doc_index()  cli() 
 69                               V                           |       | 
 70                         link_imports()                    |       | 
 71                               |                           |       | 
 72                               V                           |       | 
 73                      assign_canonical_names()             |       | 
 74                               |                           |       | 
 75                               V                           |       | 
 76                        parse_docstrings()                 |       | 
 77                               |                           |       | 
 78                               V                           |       | 
 79                         inherit_docs()                    *       | 
 80                        /      |        \                          | 
 81                       V       V         V                         | 
 82                  HTMLWriter LaTeXWriter PlaintextWriter           * 
 83     */ 
 84   
 85     ranksep = 0.1; 
 86     node [shape="box", height="0", width="0"] 
 87      
 88     { /* Task nodes */ 
 89       node [fontcolor=\"#000060\"] 
 90       introspect  [label="Introspect value:\\nintrospect_docs()", 
 91                    href="<docintrospecter.introspect_docs>"] 
 92       parse       [label="Parse source code:\\nparse_docs()", 
 93                    href="<docparser.parse_docs>"] 
 94       merge       [label="Merge introspected & parsed docs:\\nmerge_docs()", 
 95                    href="<docbuilder.merge_docs>", width="2.5"] 
 96       link        [label="Link imports:\\nlink_imports()", 
 97                    href="<docbuilder.link_imports>", width="2.5"] 
 98       name        [label="Assign names:\\nassign_canonical_names()", 
 99                    href="<docbuilder.assign_canonical_names>", width="2.5"] 
100       docstrings  [label="Parse docstrings:\\nparse_docstring()", 
101                    href="<docstringparser.parse_docstring>", width="2.5"] 
102       inheritance [label="Inherit docs from bases:\\ninherit_docs()", 
103                    href="<docbuilder.inherit_docs>", width="2.5"] 
104       write_html  [label="Write HTML output:\\nHTMLWriter", 
105                   href="<docwriter.html>"] 
106       write_latex  [label="Write LaTeX output:\\nLaTeXWriter", 
107                   href="<docwriter.latex>"] 
108       write_text  [label="Write text output:\\nPlaintextWriter", 
109                   href="<docwriter.plaintext>"] 
110     } 
111   
112     { /* Input & Output nodes */ 
113       node [fontcolor=\"#602000\", shape="plaintext"] 
114       input [label="Python module or value"] 
115       output [label="DocIndex", href="<apidoc.DocIndex>"] 
116     } 
117   
118     { /* Graph edges */ 
119       edge [fontcolor=\"#602000\"] 
120       input -> introspect 
121       introspect -> merge [label="APIDoc", href="<apidoc.APIDoc>"] 
122       input -> parse 
123       parse -> merge [label="APIDoc", href="<apidoc.APIDoc>"] 
124       merge -> link [label=" DocIndex", href="<apidoc.DocIndex>"] 
125       link -> name [label=" DocIndex", href="<apidoc.DocIndex>"] 
126       name -> docstrings [label=" DocIndex", href="<apidoc.DocIndex>"] 
127       docstrings -> inheritance [label=" DocIndex", href="<apidoc.DocIndex>"] 
128       inheritance -> output 
129       output -> write_html 
130       output -> write_latex 
131       output -> write_text 
132     } 
133   
134     { /* Task collections */ 
135       node [shape="circle",label="",width=.1,height=.1] 
136       edge [fontcolor="black", dir="none", fontcolor=\"#000060\"] 
137       l3 -> l4 [label=" epydoc.\\l docbuilder.\\l build_doc_index()", 
138                 href="<docbuilder.build_doc_index>"] 
139       l1 -> l2 [label=" epydoc.\\l cli()", href="<cli>"] 
140     } 
141     { rank=same; l1 l3 input } 
142     { rank=same; l2 write_html } 
143     { rank=same; l4 output } 
144   
145  Package Organization 
146  ==================== 
147  The epydoc package contains the following subpackages and modules: 
148   
149  .. packagetree:: 
150     :style: UML 
151   
152  The user interfaces are provided by the `gui` and `cli` modules. 
153  The `apidoc` module defines the basic data types used to record 
154  information about Python objects.  The programmatic interface to 
155  epydoc is provided by `docbuilder`.  Docstring markup parsing is 
156  handled by the `markup` package, and output generation is handled by 
157  the `docwriter` package.  See the submodule list for more 
158  information about the submodules and subpackages. 
159   
160  :group User Interface: gui, cli 
161  :group Basic Data Types: apidoc 
162  :group Documentation Generation: docbuilder, docintrospecter, docparser 
163  :group Docstring Processing: docstringparser, markup 
164  :group Output Generation: docwriter 
165  :group Completeness Checking: checker 
166  :group Miscellaneous: log, util, test, compat 
167   
168  :author: `Edward Loper <edloper@gradient.cis.upenn.edu>`__ 
169  :requires: Python 2.3+ 
170  :version: 3.0.1 
171  :see: `The epydoc webpage <http://epydoc.sourceforge.net>`__ 
172  :see: `The epytext markup language 
173      manual <http://epydoc.sourceforge.net/epytext.html>`__ 
174   
175  :todo: Create a better default top_page than trees.html. 
176  :todo: Fix trees.html to work when documenting non-top-level 
177         modules/packages 
178  :todo: Implement @include 
179  :todo: Optimize epytext 
180  :todo: More doctests 
181  :todo: When introspecting, limit how much introspection you do (eg, 
182         don't construct docs for imported modules' vars if it's 
183         not necessary) 
184   
185  :bug: UserDict.* is interpreted as imported .. why?? 
186   
187  :license: IBM Open Source License 
188  :copyright: |copy| 2006 Edward Loper 
189   
190  :newfield contributor: Contributor, Contributors (Alphabetical Order) 
191  :contributor: `Glyph Lefkowitz  <mailto:glyph@twistedmatrix.com>`__ 
192  :contributor: `Edward Loper  <mailto:edloper@gradient.cis.upenn.edu>`__ 
193  :contributor: `Bruce Mitchener  <mailto:bruce@cubik.org>`__ 
194  :contributor: `Jeff O'Halloran  <mailto:jeff@ohalloran.ca>`__ 
195  :contributor: `Simon Pamies  <mailto:spamies@bipbap.de>`__ 
196  :contributor: `Christian Reis  <mailto:kiko@async.com.br>`__ 
197  :contributor: `Daniele Varrazzo  <mailto:daniele.varrazzo@gmail.com>`__ 
198  :contributor: `Jonathan Guyer <mailto:guyer@nist.gov>`__ 
199   
200  .. |copy| unicode:: 0xA9 .. copyright sign 
201  """ 
202  __docformat__ = 'restructuredtext en' 
203   
204  __version__ = '3.0.1' 
205  """The version of epydoc""" 
206   
207  __author__ = 'Edward Loper <edloper@gradient.cis.upenn.edu>' 
208  """The primary author of eypdoc""" 
209   
210  __url__ = 'http://epydoc.sourceforge.net' 
211  """The URL for epydoc's homepage""" 
212   
213  __license__ = 'IBM Open Source License' 
214  """The license governing the use and distribution of epydoc""" 
215   
216  # [xx] this should probably be a private variable: 
217  DEBUG = False 
218  """True if debugging is turned on.""" 
219   
220  # Changes needed for docs: 
221  #   - document the method for deciding what's public/private 
222  #   - epytext: fields are defined slightly differently (@group) 
223  #   - new fields 
224  #   - document __extra_epydoc_fields__ and @newfield 
225  #   - Add a faq? 
226  #   - @type a,b,c: ... 
227  #   - new command line option: --command-line-order 
228