1
2
3
4
5
6
7
8
9 """
10 Command-line interface for epydoc. Abbreviated Usage::
11
12 epydoc [options] NAMES...
13
14 NAMES... The Python modules to document.
15 --html Generate HTML output (default).
16 --latex Generate LaTeX output.
17 --pdf Generate pdf output, via LaTeX.
18 -o DIR, --output DIR The output directory.
19 --inheritance STYLE The format for showing inherited objects.
20 -V, --version Print the version of epydoc.
21 -h, --help Display a usage message.
22
23 Run \"epydoc --help\" for a complete option list. See the epydoc(1)
24 man page for more information.
25
26 Config Files
27 ============
28 Configuration files can be specified with the C{--config} option.
29 These files are read using U{ConfigParser
30 <http://docs.python.org/lib/module-ConfigParser.html>}. Configuration
31 files may set options or add names of modules to document. Option
32 names are (usually) identical to the long names of command line
33 options. To specify names to document, use any of the following
34 option names::
35
36 module modules value values object objects
37
38 A simple example of a config file is::
39
40 [epydoc]
41 modules: sys, os, os.path, re, %(MYSANDBOXPATH)/utilities.py
42 name: Example
43 graph: classtree
44 introspect: no
45
46 All ConfigParser interpolations are done using local values and the
47 environment variables.
48
49
50 Verbosity Levels
51 ================
52 The C{-v} and C{-q} options increase and decrease verbosity,
53 respectively. The default verbosity level is zero. The verbosity
54 levels are currently defined as follows::
55
56 Progress Markup warnings Warnings Errors
57 -3 none no no no
58 -2 none no no yes
59 -1 none no yes yes
60 0 (default) bar no yes yes
61 1 bar yes yes yes
62 2 list yes yes yes
63 """
64 __docformat__ = 'epytext en'
65
66 import sys, os, time, re, pickle, textwrap, tempfile, shutil
67 from glob import glob
68 from optparse import OptionParser, OptionGroup, SUPPRESS_HELP
69 import optparse
70 import epydoc
71 from epydoc import log
72 from epydoc.util import wordwrap, run_subprocess, RunSubprocessError
73 from epydoc.util import plaintext_to_html, TerminalController
74 from epydoc.apidoc import UNKNOWN
75 from epydoc.compat import *
76 import ConfigParser
77 from epydoc.docwriter.html_css import STYLESHEETS as CSS_STYLESHEETS
78 from epydoc.docwriter.latex_sty import STYLESHEETS as STY_STYLESHEETS
79 from epydoc.docwriter.dotgraph import DotGraph
80 from epydoc.docwriter.dotgraph import COLOR as GRAPH_COLOR
81
82
83 try:
84 from epydoc.docwriter import xlink
85 except:
86 xlink = None
87
88 INHERITANCE_STYLES = ('grouped', 'listed', 'included', 'hidden')
89 GRAPH_TYPES = ('classtree', 'callgraph', 'umlclasstree')
90 ACTIONS = ('html', 'text', 'latex', 'dvi', 'ps', 'pdf', 'check')
91 DEFAULT_DOCFORMAT = 'epytext'
92 PROFILER = 'profile'
93 TARGET_ACTIONS = ('html', 'latex', 'dvi', 'ps', 'pdf')
94 DEFAULT_ACTIONS = ('html',)
95 PDFDRIVERS = ('pdflatex', 'latex', 'auto')
96
97
98
99
100
101 DOCFORMATS = ('epytext', 'plaintext', 'restructuredtext', 'javadoc')
102 HELP_TOPICS = {
103 'docformat': textwrap.dedent('''\
104 __docformat__ is a module variable that specifies the markup
105 language for the docstrings in a module. Its value is a
106 string, consisting the name of a markup language, optionally
107 followed by a language code (such as "en" for English). Epydoc
108 currently recognizes the following markup language names:
109 ''' + ', '.join(DOCFORMATS)),
110 'inheritance': textwrap.dedent('''\
111 The following inheritance formats are currently supported:
112 - grouped: inherited objects are gathered into groups,
113 based on what class they were inherited from.
114 - listed: inherited objects are listed in a short list
115 at the end of their section.
116 - included: inherited objects are mixed in with
117 non-inherited objects.'''),
118 'css': textwrap.dedent(
119 'The following built-in CSS stylesheets are available:\n' +
120 '\n'.join([' %10s: %s' % (key, descr)
121 for (key, (sheet, descr))
122 in CSS_STYLESHEETS.items()])),
123 'sty': textwrap.dedent(
124 'The following built-in LaTeX style files are available:\n' +
125 ', '.join(STY_STYLESHEETS)),
126
127
128
129 }
130
131
132 HELP_TOPICS['topics'] = wordwrap(
133 'Epydoc can provide additional help for the following topics: ' +
134 ', '.join(['%r' % topic for topic in HELP_TOPICS.keys()]))
135
136
137
138
139
140 DEFAULT_TARGET = dict(
141 html='html', latex='latex', dvi='api.dvi', ps='api.ps',
142 pdf='api.pdf', pickle='api.pickle')
143
145 return dict(
146 actions=[], show_frames=True, docformat=DEFAULT_DOCFORMAT,
147 show_private=True, show_imports=False, inheritance="listed",
148 verbose=0, quiet=0, load_pickle=False, parse=True, introspect=True,
149 debug=epydoc.DEBUG, profile=False, graphs=[],
150 list_classes_separately=False, graph_font=None, graph_font_size=None,
151 include_source_code=True, pstat_files=[], simple_term=False,
152 fail_on=None, exclude=[], exclude_parse=[], exclude_introspect=[],
153 external_api=[], external_api_file=[], external_api_root=[],
154 redundant_details=False, src_code_tab_width=8, verbosity=0,
155 include_timestamp=True, target={}, default_target=None,
156 pdfdriver='auto', show_submodule_list=True, inherit_from_object=False,
157 show_deprecated=True)
158
159
160
162 action = opt.replace('-', '')
163 optparser.values.actions.append(action)
164
166 if optparser.values.actions:
167 optparser.values.target[optparser.values.actions[-1]] = value
168 elif optparser.values.default_target is None:
169 optparser.values.default_target = value
170 else:
171 optparser.error("Default output target specified multiple times!")
172
174
175 usage = '%prog [ACTION] [options] NAMES...'
176 version = "Epydoc, version %s" % epydoc.__version__
177 optparser = OptionParser(usage=usage, add_help_option=False)
178
179 optparser.add_option('--config',
180 action='append', dest="configfiles", metavar='FILE',
181 help=("A configuration file, specifying additional OPTIONS "
182 "and/or NAMES. This option may be repeated."))
183
184 optparser.add_option("--output", "-o",
185 action='callback', callback=add_target, type='string', metavar="PATH",
186 help="The output directory. If PATH does not exist, then "
187 "it will be created.")
188
189 optparser.add_option("--quiet", "-q",
190 action="count", dest="quiet",
191 help="Decrease the verbosity.")
192
193 optparser.add_option("--verbose", "-v",
194 action="count", dest="verbose",
195 help="Increase the verbosity.")
196
197 optparser.add_option("--debug",
198 action="store_true", dest="debug",
199 help="Show full tracebacks for internal errors.")
200
201 optparser.add_option("--simple-term",
202 action="store_true", dest="simple_term",
203 help="Do not try to use color or cursor control when displaying "
204 "the progress bar, warnings, or errors.")
205
206 action_group = OptionGroup(optparser, 'Actions')
207 optparser.add_option_group(action_group)
208
209 action_group.add_option("--html",
210 action='callback', callback=add_action,
211 help="Write HTML output.")
212
213 action_group.add_option("--text",
214 action='callback', callback=add_action,
215 help="Write plaintext output. (not implemented yet)")
216
217 action_group.add_option("--latex",
218 action='callback', callback=add_action,
219 help="Write LaTeX output.")
220
221 action_group.add_option("--dvi",
222 action='callback', callback=add_action,
223 help="Write DVI output.")
224
225 action_group.add_option("--ps",
226 action='callback', callback=add_action,
227 help="Write Postscript output.")
228
229 action_group.add_option("--pdf",
230 action='callback', callback=add_action,
231 help="Write PDF output.")
232
233 action_group.add_option("--check",
234 action='callback', callback=add_action,
235 help="Check completeness of docs.")
236
237 action_group.add_option("--pickle",
238 action='callback', callback=add_action,
239 help="Write the documentation to a pickle file.")
240
241
242 action_group.add_option("--version",
243 action='callback', callback=add_action,
244 help="Show epydoc's version number and exit.")
245
246 action_group.add_option("-h", "--help",
247 action='callback', callback=add_action,
248 help="Show this message and exit. For help on specific "
249 "topics, use \"--help TOPIC\". Use \"--help topics\" for a "
250 "list of available help topics")
251
252
253 generation_group = OptionGroup(optparser, 'Generation Options')
254 optparser.add_option_group(generation_group)
255
256 generation_group.add_option("--docformat",
257 dest="docformat", metavar="NAME",
258 help="The default markup language for docstrings. Defaults "
259 "to \"%s\"." % DEFAULT_DOCFORMAT)
260
261 generation_group.add_option("--parse-only",
262 action="store_false", dest="introspect",
263 help="Get all information from parsing (don't introspect)")
264
265 generation_group.add_option("--introspect-only",
266 action="store_false", dest="parse",
267 help="Get all information from introspecting (don't parse)")
268
269 generation_group.add_option("--exclude",
270 dest="exclude", metavar="PATTERN", action="append",
271 help="Exclude modules whose dotted name matches "
272 "the regular expression PATTERN")
273
274 generation_group.add_option("--exclude-introspect",
275 dest="exclude_introspect", metavar="PATTERN", action="append",
276 help="Exclude introspection of modules whose dotted name matches "
277 "the regular expression PATTERN")
278
279 generation_group.add_option("--exclude-parse",
280 dest="exclude_parse", metavar="PATTERN", action="append",
281 help="Exclude parsing of modules whose dotted name matches "
282 "the regular expression PATTERN")
283
284 generation_group.add_option("--inheritance",
285 dest="inheritance", metavar="STYLE",
286 help="The format for showing inheritance objects. STYLE "
287 "should be one of: %s." % ', '.join(INHERITANCE_STYLES))
288
289 generation_group.add_option("--show-private",
290 action="store_true", dest="show_private",
291 help="Include private variables in the output. (default)")
292
293 generation_group.add_option("--no-private",
294 action="store_false", dest="show_private",
295 help="Do not include private variables in the output.")
296
297 generation_group.add_option("--show-deprecated",
298 action="store_true", dest="show_deprecated",
299 help="Include deprecated objects in the output. (default)")
300
301 generation_group.add_option("--no-deprecated",
302 action="store_false", dest="show_deprecated",
303 help="Do not include deprecated objects in the output.")
304
305 generation_group.add_option("--show-imports",
306 action="store_true", dest="show_imports",
307 help="List each module's imports.")
308
309 generation_group.add_option("--no-imports",
310 action="store_false", dest="show_imports",
311 help="Do not list each module's imports. (default)")
312
313 generation_group.add_option('--show-sourcecode',
314 action='store_true', dest='include_source_code',
315 help=("Include source code with syntax highlighting in the "
316 "HTML output. (default)"))
317
318 generation_group.add_option('--no-sourcecode',
319 action='store_false', dest='include_source_code',
320 help=("Do not include source code with syntax highlighting in the "
321 "HTML output."))
322
323 generation_group.add_option('--include-log',
324 action='store_true', dest='include_log',
325 help=("Include a page with the process log (epydoc-log.html)"))
326
327 generation_group.add_option('--redundant-details',
328 action='store_true', dest='redundant_details',
329 help=("Include values in the details lists even if all info "
330 "about them is already provided by the summary table."))
331
332 generation_group.add_option('--show-submodule-list',
333 action='store_true', dest='show_submodule_list',
334 help="Include a list of submodules on package documentation "
335 "pages. (default)")
336
337 generation_group.add_option('--no-submodule-list',
338 action='store_false', dest='show_submodule_list',
339 help="Do not include a list of submodules on package "
340 "documentation pages.")
341
342 generation_group.add_option('--inherit-from-object',
343 action='store_true', dest='inherit_from_object',
344 help="Include methods & properties that are inherited from "
345 "\"object\".")
346
347 generation_group.add_option('--no-inherit-from-object',
348 action='store_false', dest='inherit_from_object',
349 help="Do not include methods & properties that are inherited "
350 "from \"object\". (default)")
351
352 generation_group.add_option('--google-analytics',
353 action='store', dest='google_analytics',
354 help="Tracker code for google analytics (eg UA-427085-11).")
355
356 output_group = OptionGroup(optparser, 'Output Options')
357 optparser.add_option_group(output_group)
358
359 output_group.add_option("--name", "-n",
360 dest="prj_name", metavar="NAME",
361 help="The documented project's name (for the navigation bar).")
362
363 output_group.add_option("--css", "-c",
364 dest="css", metavar="STYLESHEET",
365 help="The CSS stylesheet. STYLESHEET can be either a "
366 "builtin stylesheet or the name of a CSS file.")
367
368 output_group.add_option("--sty",
369 dest="sty", metavar="LATEXSTYLE",
370 help="The LaTeX style file. LATEXSTYLE can be either a "
371 "builtin style file or the name of a .sty file.")
372
373 output_group.add_option("--pdfdriver",
374 dest="pdfdriver", metavar="DRIVER",
375 help="The command sequence that should be used to render "
376 "pdf output. \"pdflatex\" will generate the pdf directly "
377 "using pdflatex. \"latex\" will generate the pdf using "
378 "latex, dvips, and ps2pdf in succession. \"auto\" will use "
379 "pdflatex if available, and latex otherwise.")
380
381 output_group.add_option("--url", "-u",
382 dest="prj_url", metavar="URL",
383 help="The documented project's URL (for the navigation bar).")
384
385 output_group.add_option("--navlink",
386 dest="prj_link", metavar="HTML",
387 help="HTML code for a navigation link to place in the "
388 "navigation bar.")
389
390 output_group.add_option("--top",
391 dest="top_page", metavar="PAGE",
392 help="The \"top\" page for the HTML documentation. PAGE can "
393 "be a URL, the name of a module or class, or one of the "
394 "special names \"trees.html\", \"indices.html\", or \"help.html\"")
395
396 output_group.add_option("--help-file",
397 dest="help_file", metavar="FILE",
398 help="An alternate help file. FILE should contain the body "
399 "of an HTML file -- navigation bars will be added to it.")
400
401 output_group.add_option("--show-frames",
402 action="store_true", dest="show_frames",
403 help="Include frames in the HTML output. (default)")
404
405 output_group.add_option("--no-frames",
406 action="store_false", dest="show_frames",
407 help="Do not include frames in the HTML output.")
408
409 output_group.add_option('--separate-classes',
410 action='store_true', dest='list_classes_separately',
411 help=("When generating LaTeX or PDF output, list each class in "
412 "its own section, instead of listing them under their "
413 "containing module."))
414
415 output_group.add_option('--src-code-tab-width',
416 action='store', type='int', dest='src_code_tab_width',
417 help=("When generating HTML output, sets the number of spaces "
418 "each tab in source code listings is replaced with."))
419
420 output_group.add_option('--suppress-timestamp',
421 action='store_false', dest='include_timestamp',
422 help=("Do not include a timestamp in the generated output."))
423
424
425
426 if xlink is not None:
427 link_group = OptionGroup(optparser,
428 xlink.ApiLinkReader.settings_spec[0])
429 optparser.add_option_group(link_group)
430
431 for help, names, opts in xlink.ApiLinkReader.settings_spec[2]:
432 opts = opts.copy()
433 opts['help'] = help
434 link_group.add_option(*names, **opts)
435
436 graph_group = OptionGroup(optparser, 'Graph Options')
437 optparser.add_option_group(graph_group)
438
439 graph_group.add_option('--graph',
440 action='append', dest='graphs', metavar='GRAPHTYPE',
441 help=("Include graphs of type GRAPHTYPE in the generated output. "
442 "Graphs are generated using the Graphviz dot executable. "
443 "If this executable is not on the path, then use --dotpath "
444 "to specify its location. This option may be repeated to "
445 "include multiple graph types in the output. GRAPHTYPE "
446 "should be one of: all, %s." % ', '.join(GRAPH_TYPES)))
447
448 graph_group.add_option("--dotpath",
449 dest="dotpath", metavar='PATH',
450 help="The path to the Graphviz 'dot' executable.")
451
452 graph_group.add_option('--graph-font',
453 dest='graph_font', metavar='FONT',
454 help=("Specify the font used to generate Graphviz graphs. (e.g., "
455 "helvetica or times)."))
456
457 graph_group.add_option('--graph-font-size',
458 dest='graph_font_size', metavar='SIZE',
459 help=("Specify the font size used to generate Graphviz graphs, "
460 "in points."))
461
462 graph_group.add_option('--pstat',
463 action='append', dest='pstat_files', metavar='FILE',
464 help="A pstat output file, to be used in generating call graphs.")
465
466 graph_group.add_option('--max-html-graph-size',
467 action='store', dest='max_html_graph_size', metavar='SIZE',
468 help="Set the maximum graph size for HTML graphs. This should "
469 "be a string of the form \"w,h\", specifying the maximum width "
470 "and height in inches. Default=%r" % DotGraph.DEFAULT_HTML_SIZE)
471
472 graph_group.add_option('--max-latex-graph-size',
473 action='store', dest='max_latex_graph_size', metavar='SIZE',
474 help="Set the maximum graph size for LATEX graphs. This should "
475 "be a string of the form \"w,h\", specifying the maximum width "
476 "and height in inches. Default=%r" % DotGraph.DEFAULT_LATEX_SIZE)
477
478 graph_group.add_option(