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_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))
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))