def write_latex(docindex, options, format):
"""
Sustituye la función de igual nombre de Epydoc.
"""
latex_writer = TagFSLatexWriter(docindex, **options.__dict__)
log.start_progress('Writing LaTeX docs')
latex_writer.write(options.target)
log.end_progress()
def write_latex(docindex, options, format):
"""
Sustituye la función de igual nombre de Epydoc.
"""
latex_writer = TagFSLatexWriter(docindex, **options.__dict__)
log.start_progress('Writing LaTeX docs')
latex_writer.write(options.target)
log.end_progress()
def write_html(docindex, options):
from epydoc.docwriter.html import HTMLWriter
html_writer = HTMLWriter(docindex, **options.__dict__)
if options.verbose > 0:
log.start_progress('Writing HTML docs to %r' % options.target)
else:
log.start_progress('Writing HTML docs')
html_writer.write(options.target)
log.end_progress()
def write_html(docindex, options):
from epydoc.docwriter.html import HTMLWriter
html_writer = HTMLWriter(docindex, **options.__dict__)
if options.verbose > 0:
log.start_progress('Writing HTML docs to %r' % options.target)
else:
log.start_progress('Writing HTML docs')
html_writer.write(options.target)
log.end_progress()
def write_text(docindex, options):
log.start_progress('Writing output')
from epydoc.docwriter.plaintext import PlaintextWriter
plaintext_writer = PlaintextWriter()
s = ''
for apidoc in docindex.root:
s += plaintext_writer.write(apidoc)
log.end_progress()
if isinstance(s, unicode):
s = s.encode('ascii', 'backslashreplace')
print s
def write_text(docindex, options):
log.start_progress('Writing output')
from epydoc.docwriter.plaintext import PlaintextWriter
plaintext_writer = PlaintextWriter()
s = ''
for apidoc in docindex.root:
s += plaintext_writer.write(apidoc)
log.end_progress()
if isinstance(s, unicode):
s = s.encode('ascii', 'backslashreplace')
print s
def _get_docs_from_items(items, introspect, parse, add_submodules):
# Start the progress bar.
log.start_progress('Building documentation')
progress_estimator = _ProgressEstimator(items)
# Collect (introspectdoc, parsedoc) pairs for each item.
doc_pairs = []
for item in items:
if isinstance(item, basestring):
if is_module_file(item):
doc_pairs.append(
_get_docs_from_module_file(item, introspect, parse,
progress_estimator))
elif is_package_dir(item):
pkgfile = os.path.join(item, '__init__')
doc_pairs.append(
_get_docs_from_module_file(pkgfile, introspect, parse,
progress_estimator))
elif os.path.isfile(item):
doc_pairs.append(
_get_docs_from_pyscript(item, introspect, parse,
progress_estimator))
elif hasattr(__builtin__, item):
val = getattr(__builtin__, item)
doc_pairs.append(
_get_docs_from_pyobject(val, introspect, parse,
progress_estimator))
elif is_pyname(item):
doc_pairs.append(
_get_docs_from_pyname(item, introspect, parse,
progress_estimator))
elif os.path.isdir(item):
log.error("Directory %r is not a package" % item)
elif os.path.isfile(item):
log.error("File %s is not a Python module" % item)
else:
log.error("Could not find a file or object named %s" % item)
else:
doc_pairs.append(
_get_docs_from_pyobject(item, introspect, parse,
progress_estimator))
# This will only have an effect if doc_pairs[-1] contains a
# package's docs. The 'not is_module_file(item)' prevents
# us from adding subdirectories if they explicitly specify
# a package's __init__.py file.
if add_submodules and not is_module_file(item):
doc_pairs += _get_docs_from_submodules(item, doc_pairs[-1],
introspect, parse,
progress_estimator)
log.end_progress()
return doc_pairs
def document(options, cancel, done):
"""
Create the documentation for C{modules}, using the options
specified by C{options}. C{document} is designed to be started in
its own thread by L{EpydocGUI._go}.
@param options: The options to use for generating documentation.
This includes keyword options that can be given to
L{docwriter.html.HTMLWriter}, as well as the option C{target}, which
controls where the output is written to.
@type options: C{dictionary}
"""
from epydoc.docwriter.html import HTMLWriter
from epydoc.docbuilder import build_doc_index
import epydoc.docstringparser
# Set the default docformat.
docformat = options.get('docformat', 'epytext')
epydoc.docstringparser.DEFAULT_DOCFORMAT = docformat
try:
parse = options['introspect_or_parse'] in ('parse', 'both')
introspect = options['introspect_or_parse'] in ('introspect', 'both')
docindex = build_doc_index(options['modules'], parse, introspect)
html_writer = HTMLWriter(docindex, **options)
log.start_progress('Writing HTML docs to %r' % options['target'])
html_writer.write(options['target'])
log.end_progress()
# We're done.
log.warning('Finished!')
done[0] = 'done'
except SystemExit:
# Cancel.
log.error('Cancelled!')
done[0] ='cancel'
raise
except Exception as e:
# We failed.
log.error('Internal error: %s' % e)
done[0] ='cancel'
raise
except:
# We failed.
log.error('Internal error!')
done[0] ='cancel'
raise
def _get_docs_from_items(items, introspect, parse, add_submodules):
# Start the progress bar.
log.start_progress('Building documentation')
progress_estimator = _ProgressEstimator(items)
# Collect (introspectdoc, parsedoc) pairs for each item.
doc_pairs = []
for item in items:
if isinstance(item, basestring):
if is_module_file(item):
doc_pairs.append(_get_docs_from_module_file(
item, introspect, parse, progress_estimator))
elif is_package_dir(item):
pkgfile = os.path.join(item, '__init__')
doc_pairs.append(_get_docs_from_module_file(
pkgfile, introspect, parse, progress_estimator))
elif os.path.isfile(item):
doc_pairs.append(_get_docs_from_pyscript(
item, introspect, parse, progress_estimator))
elif hasattr(__builtin__, item):
val = getattr(__builtin__, item)
doc_pairs.append(_get_docs_from_pyobject(
val, introspect, parse, progress_estimator))
elif is_pyname(item):
doc_pairs.append(_get_docs_from_pyname(
item, introspect, parse, progress_estimator))
elif os.path.isdir(item):
log.error("Directory %r is not a package" % item)
elif os.path.isfile(item):
log.error("File %s is not a Python module" % item)
else:
log.error("Could not find a file or object named %s" %
item)
else:
doc_pairs.append(_get_docs_from_pyobject(
item, introspect, parse, progress_estimator))
# This will only have an effect if doc_pairs[-1] contains a
# package's docs. The 'not is_module_file(item)' prevents
# us from adding subdirectories if they explicitly specify
# a package's __init__.py file.
if add_submodules and not is_module_file(item):
doc_pairs += _get_docs_from_submodules(
item, doc_pairs[-1], introspect, parse, progress_estimator)
log.end_progress()
return doc_pairs
def document(options, cancel, done):
"""
Create the documentation for C{modules}, using the options
specified by C{options}. C{document} is designed to be started in
its own thread by L{EpydocGUI._go}.
@param options: The options to use for generating documentation.
This includes keyword options that can be given to
L{docwriter.html.HTMLWriter}, as well as the option C{target}, which
controls where the output is written to.
@type options: C{dictionary}
"""
from epydoc.docwriter.html import HTMLWriter
from epydoc.docbuilder import build_doc_index
import epydoc.docstringparser
# Set the default docformat.
docformat = options.get("docformat", "epytext")
epydoc.docstringparser.DEFAULT_DOCFORMAT = docformat
try:
parse = options["introspect_or_parse"] in ("parse", "both")
introspect = options["introspect_or_parse"] in ("introspect", "both")
docindex = build_doc_index(options["modules"], parse, introspect)
html_writer = HTMLWriter(docindex, **options)
log.start_progress("Writing HTML docs to %r" % options["target"])
html_writer.write(options["target"])
log.end_progress()
# We're done.
log.warning("Finished!")
done[0] = "done"
except SystemExit:
# Cancel.
log.error("Cancelled!")
done[0] = "cancel"
raise
except Exception, e:
# We failed.
log.error("Internal error: %s" % e)
done[0] = "cancel"
raise
def build_doc_index(items, introspect=True, parse=True,
add_submodules=True):
"""
Build API documentation for the given list of items, and
return it in the form of a L{DocIndex}.
@rtype: L{DocIndex}
@param items: The items to document, specified using any of the
following:
- A string, naming a python package directory
(e.g., C{'epydoc/markup'})
- A string, naming a python file
(e.g., C{'epydoc/docparser.py'})
- A string, naming a python object
(e.g., C{'epydoc.docparser.DocParser'})
- Any (non-string) python object
(e.g., C{list.append})
@param introspect: If true, then use introspection to examine the
specified items. Otherwise, just use parsing.
@param parse: If true, then use parsing to examine the specified
items. Otherwise, just use introspection.
"""
# Get the basic docs for each item.
doc_pairs = _get_docs_from_items(items, introspect, parse, add_submodules)
# Merge the introspection & parse docs.
if parse and introspect:
log.start_progress('Merging parsed & introspected information')
docs = []
for i, (introspect_doc, parse_doc) in enumerate(doc_pairs):
if introspect_doc is not None and parse_doc is not None:
if introspect_doc.canonical_name not in (None, UNKNOWN):
name = introspect_doc.canonical_name
else:
name = parse_doc.canonical_name
log.progress(float(i)/len(doc_pairs), name)
docs.append(merge_docs(introspect_doc, parse_doc))
elif introspect_doc is not None:
docs.append(introspect_doc)
elif parse_doc is not None:
docs.append(parse_doc)
log.end_progress()
elif introspect:
docs = [doc_pair[0] for doc_pair in doc_pairs if doc_pair[0]]
else:
docs = [doc_pair[1] for doc_pair in doc_pairs if doc_pair[1]]
if len(docs) == 0:
log.error('Nothing left to document!')
return None
# Collect the docs into a single index.
docindex = DocIndex(docs)
# Replace any proxy valuedocs that we got from importing with
# their targets.
if parse:
log.start_progress('Linking imported variables')
valdocs = docindex.reachable_valdocs(sort_by_name=True, imports=False,
submodules=False, packages=False,
subclasses=False)
for i, val_doc in enumerate(valdocs):
_report_valdoc_progress(i, val_doc, valdocs)
link_imports(val_doc, docindex)
log.end_progress()
# Assign canonical names.
log.start_progress('Indexing documentation')
for i, val_doc in enumerate(docindex.root):
log.progress(float(i)/len(docindex.root), val_doc.canonical_name)
assign_canonical_names(val_doc, val_doc.canonical_name, docindex)
log.end_progress()
# Parse the docstrings for each object.
log.start_progress('Parsing docstrings')
valdocs = docindex.reachable_valdocs(sort_by_name=True, imports=False,
submodules=False, packages=False,
subclasses=False)
for i, val_doc in enumerate(valdocs):
_report_valdoc_progress(i, val_doc, valdocs)
# the value's docstring
parse_docstring(val_doc, docindex)
# the value's variables' docstrings
if (isinstance(val_doc, NamespaceDoc) and
val_doc.variables not in (None, UNKNOWN)):
for var_doc in val_doc.variables.values():
parse_docstring(var_doc, docindex)
log.end_progress()
# Take care of inheritance.
log.start_progress('Inheriting documentation')
for i, val_doc in enumerate(valdocs):
if isinstance(val_doc, ClassDoc):
percent = float(i)/len(valdocs)
log.progress(percent, val_doc.canonical_name)
inherit_docs(val_doc)
log.end_progress()
# Initialize the groups & sortedvars attributes.
log.start_progress('Sorting & Grouping')
for i, val_doc in enumerate(valdocs):
if isinstance(val_doc, NamespaceDoc):
percent = float(i)/len(valdocs)
log.progress(percent, val_doc.canonical_name)
val_doc.init_sorted_variables()
val_doc.init_variable_groups()
if isinstance(val_doc, ModuleDoc):
val_doc.init_submodule_groups()
log.end_progress()
return docindex
def build_doc_index(items, introspect=True, parse=True, add_submodules=True):
"""
Build API documentation for the given list of items, and
return it in the form of a L{DocIndex}.
@rtype: L{DocIndex}
@param items: The items to document, specified using any of the
following:
- A string, naming a python package directory
(e.g., C{'epydoc/markup'})
- A string, naming a python file
(e.g., C{'epydoc/docparser.py'})
- A string, naming a python object
(e.g., C{'epydoc.docparser.DocParser'})
- Any (non-string) python object
(e.g., C{list.append})
@param introspect: If true, then use introspection to examine the
specified items. Otherwise, just use parsing.
@param parse: If true, then use parsing to examine the specified
items. Otherwise, just use introspection.
"""
# Get the basic docs for each item.
doc_pairs = _get_docs_from_items(items, introspect, parse, add_submodules)
# Merge the introspection & parse docs.
if parse and introspect:
log.start_progress('Merging parsed & introspected information')
docs = []
for i, (introspect_doc, parse_doc) in enumerate(doc_pairs):
if introspect_doc is not None and parse_doc is not None:
if introspect_doc.canonical_name not in (None, UNKNOWN):
name = introspect_doc.canonical_name
else:
name = parse_doc.canonical_name
log.progress(float(i) / len(doc_pairs), name)
docs.append(merge_docs(introspect_doc, parse_doc))
elif introspect_doc is not None:
docs.append(introspect_doc)
elif parse_doc is not None:
docs.append(parse_doc)
log.end_progress()
elif introspect:
docs = [doc_pair[0] for doc_pair in doc_pairs if doc_pair[0]]
else:
docs = [doc_pair[1] for doc_pair in doc_pairs if doc_pair[1]]
if len(docs) == 0:
log.error('Nothing left to document!')
return None
# Collect the docs into a single index.
docindex = DocIndex(docs)
# Replace any proxy valuedocs that we got from importing with
# their targets.
if parse:
log.start_progress('Linking imported variables')
valdocs = docindex.reachable_valdocs(sort_by_name=True,
imports=False,
submodules=False,
packages=False,
subclasses=False)
for i, val_doc in enumerate(valdocs):
_report_valdoc_progress(i, val_doc, valdocs)
link_imports(val_doc, docindex)
log.end_progress()
# Assign canonical names.
log.start_progress('Indexing documentation')
for i, val_doc in enumerate(docindex.root):
log.progress(float(i) / len(docindex.root), val_doc.canonical_name)
assign_canonical_names(val_doc, val_doc.canonical_name, docindex)
log.end_progress()
# Parse the docstrings for each object.
log.start_progress('Parsing docstrings')
valdocs = docindex.reachable_valdocs(sort_by_name=True,
imports=False,
submodules=False,
packages=False,
subclasses=False)
for i, val_doc in enumerate(valdocs):
_report_valdoc_progress(i, val_doc, valdocs)
# the value's docstring
parse_docstring(val_doc, docindex)
# the value's variables' docstrings
if (isinstance(val_doc, NamespaceDoc)
and val_doc.variables not in (None, UNKNOWN)):
for var_doc in val_doc.variables.values():
parse_docstring(var_doc, docindex)
log.end_progress()
# Take care of inheritance.
log.start_progress('Inheriting documentation')
for i, val_doc in enumerate(valdocs):
if isinstance(val_doc, ClassDoc):
percent = float(i) / len(valdocs)
log.progress(percent, val_doc.canonical_name)
inherit_docs(val_doc)
log.end_progress()
# Initialize the groups & sortedvars attributes.
log.start_progress('Sorting & Grouping')
for i, val_doc in enumerate(valdocs):
if isinstance(val_doc, NamespaceDoc):
percent = float(i) / len(valdocs)
log.progress(percent, val_doc.canonical_name)
val_doc.init_sorted_variables()
val_doc.init_variable_groups()
if isinstance(val_doc, ModuleDoc):
val_doc.init_submodule_groups()
log.end_progress()
return docindex
def write_latex(docindex, options, format):
from epydoc.docwriter.latex import LatexWriter
latex_writer = LatexWriter(docindex, **options.__dict__)
log.start_progress('Writing LaTeX docs')
latex_writer.write(options.target)
log.end_progress()
# If we're just generating the latex, and not any output format,
# then we're done.
if format == 'latex': return
if format == 'dvi': steps = 4
elif format == 'ps': steps = 5
elif format == 'pdf': steps = 6
log.start_progress('Processing LaTeX docs')
oldpath = os.path.abspath(os.curdir)
running = None # keep track of what we're doing.
try:
try:
os.chdir(options.target)
# Clear any old files out of the way.
for ext in 'tex aux log out idx ilg toc ind'.split():
if os.path.exists('apidoc.%s' % ext):
os.remove('apidoc.%s' % ext)
# The first pass generates index files.
running = 'latex'
log.progress(0./steps, 'LaTeX: First pass')
run_subprocess('latex api.tex')
# Build the index.
running = 'makeindex'
log.progress(1./steps, 'LaTeX: Build index')
run_subprocess('makeindex api.idx')
# The second pass generates our output.
running = 'latex'
log.progress(2./steps, 'LaTeX: Second pass')
out, err = run_subprocess('latex api.tex')
# The third pass is only necessary if the second pass
# changed what page some things are on.
running = 'latex'
if _RERUN_LATEX_RE.match(out):
log.progress(3./steps, 'LaTeX: Third pass')
out, err = run_subprocess('latex api.tex')
# A fourth path should (almost?) never be necessary.
running = 'latex'
if _RERUN_LATEX_RE.match(out):
log.progress(3./steps, 'LaTeX: Fourth pass')
run_subprocess('latex api.tex')
# If requested, convert to postscript.
if format in ('ps', 'pdf'):
running = 'dvips'
log.progress(4./steps, 'dvips')
run_subprocess('dvips api.dvi -o api.ps -G0 -Ppdf')
# If requested, convert to pdf.
if format in ('pdf'):
running = 'ps2pdf'
log.progress(5./steps, 'ps2pdf')
run_subprocess(
'ps2pdf -sPAPERSIZE=letter -dMaxSubsetPct=100 '
'-dSubsetFonts=true -dCompatibilityLevel=1.2 '
'-dEmbedAllFonts=true api.ps api.pdf')
except RunSubprocessError, e:
if running == 'latex':
e.out = re.sub(r'(?sm)\A.*?!( LaTeX Error:)?', r'', e.out)
e.out = re.sub(r'(?sm)\s*Type X to quit.*', '', e.out)
e.out = re.sub(r'(?sm)^! Emergency stop.*', '', e.out)
log.error("%s failed: %s" % (running, (e.out+e.err).lstrip()))
except OSError, e:
log.error("%s failed: %s" % (running, e))
log.progress(5./steps, 'ps2pdf')
run_subprocess(
'ps2pdf -sPAPERSIZE=letter -dMaxSubsetPct=100 '
'-dSubsetFonts=true -dCompatibilityLevel=1.2 '
'-dEmbedAllFonts=true api.ps api.pdf')
except RunSubprocessError, e:
if running == 'latex':
e.out = re.sub(r'(?sm)\A.*?!( LaTeX Error:)?', r'', e.out)
e.out = re.sub(r'(?sm)\s*Type X to quit.*', '', e.out)
e.out = re.sub(r'(?sm)^! Emergency stop.*', '', e.out)
log.error("%s failed: %s" % (running, (e.out+e.err).lstrip()))
except OSError, e:
log.error("%s failed: %s" % (running, e))
finally:
os.chdir(oldpath)
log.end_progress()
def write_text(docindex, options):
log.start_progress('Writing output')
from epydoc.docwriter.plaintext import PlaintextWriter
plaintext_writer = PlaintextWriter()
s = ''
for apidoc in docindex.root:
s += plaintext_writer.write(apidoc)
log.end_progress()
if isinstance(s, unicode):
s = s.encode('ascii', 'backslashreplace')
print s
def check_docs(docindex, options):
from epydoc.checker import DocChecker
def write_latex(docindex, options, format):
from epydoc.docwriter.latex import LatexWriter
latex_writer = LatexWriter(docindex, **options.__dict__)
log.start_progress('Writing LaTeX docs')
latex_writer.write(options.target)
log.end_progress()
# If we're just generating the latex, and not any output format,
# then we're done.
if format == 'latex': return
if format == 'dvi': steps = 4
elif format == 'ps': steps = 5
elif format == 'pdf': steps = 6
log.start_progress('Processing LaTeX docs')
oldpath = os.path.abspath(os.curdir)
running = None # keep track of what we're doing.
try:
try:
os.chdir(options.target)
# Clear any old files out of the way.
for ext in 'tex aux log out idx ilg toc ind'.split():
if os.path.exists('apidoc.%s' % ext):
os.remove('apidoc.%s' % ext)
# The first pass generates index files.
running = 'latex'
log.progress(0. / steps, 'LaTeX: First pass')
run_subprocess('latex api.tex')
# Build the index.
running = 'makeindex'
log.progress(1. / steps, 'LaTeX: Build index')
run_subprocess('makeindex api.idx')
# The second pass generates our output.
running = 'latex'
log.progress(2. / steps, 'LaTeX: Second pass')
out, err = run_subprocess('latex api.tex')
# The third pass is only necessary if the second pass
# changed what page some things are on.
running = 'latex'
if _RERUN_LATEX_RE.match(out):
log.progress(3. / steps, 'LaTeX: Third pass')
out, err = run_subprocess('latex api.tex')
# A fourth path should (almost?) never be necessary.
running = 'latex'
if _RERUN_LATEX_RE.match(out):
log.progress(3. / steps, 'LaTeX: Fourth pass')
run_subprocess('latex api.tex')
# If requested, convert to postscript.
if format in ('ps', 'pdf'):
running = 'dvips'
log.progress(4. / steps, 'dvips')
run_subprocess('dvips api.dvi -o api.ps -G0 -Ppdf')
# If requested, convert to pdf.
if format in ('pdf'):
running = 'ps2pdf'
log.progress(5. / steps, 'ps2pdf')
run_subprocess('ps2pdf -sPAPERSIZE=letter -dMaxSubsetPct=100 '
'-dSubsetFonts=true -dCompatibilityLevel=1.2 '
'-dEmbedAllFonts=true api.ps api.pdf')
except RunSubprocessError, e:
if running == 'latex':
e.out = re.sub(r'(?sm)\A.*?!( LaTeX Error:)?', r'', e.out)
e.out = re.sub(r'(?sm)\s*Type X to quit.*', '', e.out)
e.out = re.sub(r'(?sm)^! Emergency stop.*', '', e.out)
log.error("%s failed: %s" % (running, (e.out + e.err).lstrip()))
except OSError, e:
log.error("%s failed: %s" % (running, e))
running = 'ps2pdf'
log.progress(5. / steps, 'ps2pdf')
run_subprocess('ps2pdf -sPAPERSIZE=letter -dMaxSubsetPct=100 '
'-dSubsetFonts=true -dCompatibilityLevel=1.2 '
'-dEmbedAllFonts=true api.ps api.pdf')
except RunSubprocessError, e:
if running == 'latex':
e.out = re.sub(r'(?sm)\A.*?!( LaTeX Error:)?', r'', e.out)
e.out = re.sub(r'(?sm)\s*Type X to quit.*', '', e.out)
e.out = re.sub(r'(?sm)^! Emergency stop.*', '', e.out)
log.error("%s failed: %s" % (running, (e.out + e.err).lstrip()))
except OSError, e:
log.error("%s failed: %s" % (running, e))
finally:
os.chdir(oldpath)
log.end_progress()
def write_text(docindex, options):
log.start_progress('Writing output')
from epydoc.docwriter.plaintext import PlaintextWriter
plaintext_writer = PlaintextWriter()
s = ''
for apidoc in docindex.root:
s += plaintext_writer.write(apidoc)
log.end_progress()
if isinstance(s, unicode):
s = s.encode('ascii', 'backslashreplace')
print s
