1
2
3
4
5
6
7
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 <[email protected]>`__
169 :requires: Python 2.3+
170 :version: 3.0 beta 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:[email protected]>`__
192 :contributor: `Edward Loper <mailto:[email protected]>`__
193 :contributor: `Bruce Mitchener <mailto:[email protected]>`__
194 :contributor: `Jeff O'Halloran <mailto:[email protected]>`__
195 :contributor: `Simon Pamies <mailto:[email protected]>`__
196 :contributor: `Christian Reis <mailto:[email protected]>`__
197 :contributor: `Daniele Varrazzo <mailto:[email protected]>`__
198
199 .. |copy| unicode:: 0xA9 .. copyright sign
200 """
201 __docformat__ = 'restructuredtext en'
202
203 __version__ = '3.0beta1'
204 """The version of epydoc"""
205
206 __author__ = 'Edward Loper <[email protected]>'
207 """The primary author of eypdoc"""
208
209 __url__ = 'http://epydoc.sourceforge.net'
210 """The URL for epydoc's homepage"""
211
212 __license__ = 'IBM Open Source License'
213 """The license governing the use and distribution of epydoc"""
214
215
216 DEBUG = False
217 """True if debugging is turned on."""
218
219
220
221
222
223
224
225
226
227