def testencoding(s, introspect=True, parse=True, debug=False): """ An end-to-end test for unicode encodings. This function takes a given string, writes it to a python file, and processes that file's documentation. It then generates HTML output from the documentation, extracts all docstrings from the generated HTML output, and displays them. (In order to extract & display all docstrings, it monkey-patches the HMTLwriter.docstring_to_html() method.)""" # Monkey-patch docstring_to_html original_docstring_to_html = HTMLWriter.docstring_to_html HTMLWriter.docstring_to_html = print_docstring_as_html # Write s to a temporary file. tmp_dir = tempfile.mkdtemp() path = os.path.join(tmp_dir, 'enc_test.py') out = open(path, 'w') out.write(textwrap.dedent(s)) out.close() # Build docs for it docindex = build_doc_index([path], introspect, parse) if docindex is None: return sys.modules.pop('enc_test', None) # Write html output. writer = HTMLWriter(docindex, mark_docstrings=True) writer.write(tmp_dir) for file in os.listdir(tmp_dir): os.unlink(os.path.join(tmp_dir,file)) os.rmdir(tmp_dir) # Restore the HTMLWriter class to its original state. HTMLWriter.docstring_to_html = original_docstring_to_html
def testencoding(s, introspect=True, parse=True, debug=False): """ An end-to-end test for unicode encodings. This function takes a given string, writes it to a python file, and processes that file's documentation. It then generates HTML output from the documentation, extracts all docstrings from the generated HTML output, and displays them. (In order to extract & display all docstrings, it monkey-patches the HMTLwriter.docstring_to_html() method.)""" # Monkey-patch docstring_to_html original_docstring_to_html = HTMLWriter.docstring_to_html HTMLWriter.docstring_to_html = print_docstring_as_html # Write s to a temporary file. file_path = write_pystring_to_tmp_dir(s, 'enc_test.py') # Build docs for it docindex = build_doc_index([file_path], introspect, parse) if docindex is None: return sys.modules.pop('enc_test', None) # Write html output. writer = HTMLWriter(docindex, mark_docstrings=True) writer.write(os.path.dirname(file_path)) cleanup_tmp_dir(file_path, True) # Restore the HTMLWriter class to its original state. HTMLWriter.docstring_to_html = original_docstring_to_html
def generate_doc(): """Generate the epydoc reference manual. """ if not pygccxml_available: print "Please install pygccxml before generating the docs." sys.exit() add_pygccxml_to_PYTHONPATH() import epydoc from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter print "Generating epydoc files..." # Register a logger object so that warnings/errors are shown epydoc.log.register_logger(epydoc.log.SimpleLogger()) docindex = build_doc_index(['pyplusplus', 'pygccxml']) html_writer = HTMLWriter(docindex, prj_name='Py++', prj_url='http://www.language-binding.net', show_private=False, show_frames=False) html_writer.write(os.path.join('docs', 'documentation', 'apidocs'))
def generate_doc(): """Generate the epydoc reference manual. """ if not pygccxml_available: print "Please install pygccxml before generating the docs." sys.exit() add_pygccxml_to_PYTHONPATH() import epydoc from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter print "Generating epydoc files..." # Register a logger object so that warnings/errors are shown epydoc.log.register_logger(epydoc.log.SimpleLogger()) docindex = build_doc_index(['pyplusplus', 'pygccxml']) html_writer = HTMLWriter( docindex , prj_name='Py++' , prj_url='http://www.language-binding.net' , show_private=False , show_frames=False ) html_writer.write( os.path.join('docs', 'documentation', 'apidocs') )
def emit_pydocs(target, source, env): urls = UrlList() slist = [str(s) for s in source] api = build_doc_index(slist) writer = HTMLWriter(api) writer.write_api_list(urls.addUrlMapping) other_targets = ['api-objects.txt', 'class-tree.html', 'crarr.png', 'epydoc.css', 'epydoc.js', 'frames.html', 'help.html', 'identifier-index.html','index.html','module-tree.html','redirect.html', 'toc.html', 'toc-everything.html'] print [m.filename for m in writer.module_list]
def run(self): m = self.distribution.metadata docindex = build_doc_index(self.find_items()) html_writer = HTMLWriter( docindex, prj_name=m.get_name(), prj_url=m.get_url()) html_writer.write(self.target_dir)
def safe_build_doc_index(modules): # build_doc_index isn't re-entrant due to crappy caching! >:( from epydoc.docintrospecter import clear_cache clear_cache() from epydoc.docparser import _moduledoc_cache _moduledoc_cache.clear() # Build a new DocIndex. It swallows exceptions and returns None on error! # >:( result = build_doc_index(modules) if result is None: raise Exception("Failed to build doc index on %r" % (modules,)) return result
def generate_doc(): """Generate the epydoc reference manual. """ print "Generating epydoc files..." from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter docindex = build_doc_index(["pygccxml"]) html_writer = HTMLWriter( docindex, prj_name="pygccxml", prj_url="http://www.language-binding.net", show_private=False, show_frames=False ) html_writer.write(os.path.join("docs", "apidocs"))
def generate_apidoc(outputdir='doc/api'): """ Use epydoc to generate API doc. """ import os from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter docindex = build_doc_index(['solvcon'], introspect=True, parse=True, add_submodules=True) html_writer = HTMLWriter(docindex) # write. outputdir = os.path.join(*outputdir.split('/')) if not os.path.exists(outputdir): os.makedirs(outputdir) html_writer.write(outputdir)
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 epydoc_builder_action(target, source, env): """ Take a list of `source` files and build docs for them in `target` dir. `target` and `source` are lists. Uses OUTDIR and EPYDOCFLAGS environment variables. http://www.scons.org/doc/2.0.1/HTML/scons-user/x3594.html """ # the epydoc build process is the following: # 1. build documentation index # 2. feed doc index to writer for docs from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter # from epydoc.docwriter.latex import LatexWriter # first arg is a list where can be names of python package dirs, # python files, object names or objects itself docindex = build_doc_index([str(src) for src in source]) if docindex is None: return -1 if env['EPYDOCFLAGS'] == '--html': html_writer = HTMLWriter(docindex, docformat='restructuredText', prj_name='SCons', prj_url='http://www.scons.org/') try: html_writer.write(env['OUTDIR']) except OSError: # If directory cannot be created or any file cannot # be created or written to. return -2 """ # PDF support requires external Linux utilites, so it's not crossplatform. # Leaving for now. # http://epydoc.svn.sourceforge.net/viewvc/epydoc/trunk/epydoc/src/epydoc/cli.py elif env['EPYDOCFLAGS'] == '--pdf': pdf_writer = LatexWriter(docindex, docformat='restructuredText', prj_name='SCons', prj_url='http://www.scons.org/') """ return 0
def generate_doc(): """Generate the epydoc reference manual. """ print "Generating epydoc files..." from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter docindex = build_doc_index(['pygccxml']) html_writer = HTMLWriter(docindex, prj_name='pygccxml', prj_url='http://www.language-binding.net', show_private=False, show_frames=False) html_writer.write(os.path.join('docs', 'apidocs'))
def generate_doc(): """Generate the epydoc reference manual. """ print("Generating epydoc files...") from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter docindex = build_doc_index(['pygccxml']) html_writer = HTMLWriter( docindex , prj_name='pygccxml' , prj_url='http://www.language-binding.net' , show_private=False , show_frames=False) html_writer.write( os.path.join('docs', 'apidocs') )
def run(self): try: import epydoc.cli except ImportError: print >>sys.stderr, "Epydoc (http://epydoc.sf.net) needs to be installed to build API documentation" sys.exit(3) else: print 'Building Entangled API documentation...' from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter outputDir = '%s/doc/html' % os.path.abspath(os.path.dirname(__file__)) docindex = build_doc_index(['entangled']) htmlWriter = HTMLWriter(docindex, prj_name='Entangled', prj_url='http://entangled.sourceforge.net', inheritance='grouped', include_source_code=True) htmlWriter.write(outputDir) print 'API documentation created in: %s' % outputDir
def generate_doc(): """Generate the epydoc reference manual. """ print "Generating epydoc files..." from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter docindex = build_doc_index(['pygccxml']) html_writer = HTMLWriter( docindex , prj_name='pygccxml' , prj_url='http://www.language-binding.net' , include_source_code=False #This will decrease the size of generated documentation , show_private=False , show_frames=False) html_writer.write( os.path.join('docs', 'apidocs') )
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 run(self): try: import epydoc.cli except ImportError: print >> sys.stderr, "Epydoc (http://epydoc.sf.net) needs to be installed to build API documentation" sys.exit(3) else: print 'Building Entangled API documentation...' from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter outputDir = '%s/doc/html' % os.path.abspath( os.path.dirname(__file__)) docindex = build_doc_index(['entangled']) htmlWriter = HTMLWriter(docindex, prj_name='Entangled', prj_url='http://entangled.sourceforge.net', inheritance='grouped', include_source_code=True) htmlWriter.write(outputDir) print 'API documentation created in: %s' % outputDir
def emit_pydocs(target, source, env): urls = UrlList() slist = [str(s) for s in source] api = build_doc_index(slist) writer = HTMLWriter(api) writer.write_api_list(urls.addUrlMapping) other_targets = [ 'api-objects.txt', 'class-tree.html', 'crarr.png', 'epydoc.css', 'epydoc.js', 'frames.html', 'help.html', 'identifier-index.html', 'index.html', 'module-tree.html', 'redirect.html', 'toc.html', 'toc-everything.html' ] print[m.filename for m in writer.module_list] pysrcs = [ m.canonical_name.__str__() + '-pysrc.html' for m in writer.module_list ] tocs = [ 'toc-' + m.canonical_name.__str__() + '-module.html' for m in writer.module_list ] tlist = [join('html', url) for url in urls + other_targets + pysrcs + tocs] return tlist, slist
class build_doc(Command): user_options = doc_option def initialize_options(self): self.build_doc = None def finalize_options(self): self.set_undefined_options('build', ('build_doc', 'build_doc')) def run(self): try: from epydoc.docbuilder import build_doc_index from epydoc.docwriter.html import HTMLWriter except ImportError, e: log.warn('%s -- skipping build_doc', e) return names = ["qpid.messaging"] doc_index = build_doc_index(names, True, True) html_writer = HTMLWriter(doc_index, show_private=False) self.mkpath(self.build_doc) log.info('epydoc %s to %s' % (", ".join(names), self.build_doc)) html_writer.write(self.build_doc)
def main(options, names): if options.action == 'text': if options.parse and options.introspect: options.parse = False # Set up the logger if options.action == 'text': logger = None # no logger for text output. elif options.verbosity > 1: logger = ConsoleLogger(options.verbosity) log.register_logger(logger) else: # Each number is a rough approximation of how long we spend on # that task, used to divide up the unified progress bar. stages = [ 40, # Building documentation 7, # Merging parsed & introspected information 1, # Linking imported variables 3, # Indexing documentation 30, # Parsing Docstrings 1, # Inheriting documentation 2 ] # Sorting & Grouping if options.action == 'html': stages += [100] elif options.action == 'text': stages += [30] elif options.action == 'latex': stages += [60] elif options.action == 'dvi': stages += [60, 30] elif options.action == 'ps': stages += [60, 40] elif options.action == 'pdf': stages += [60, 50] elif options.action == 'check': stages += [10] else: raise ValueError, '%r not supported' % options.action if options.parse and not options.introspect: del stages[1] # no merging if options.introspect and not options.parse: del stages[1:3] # no merging or linking logger = UnifiedProgressConsoleLogger(options.verbosity, stages) log.register_logger(logger) # check the output directory. if options.action != 'text': if os.path.exists(options.target): if not os.path.isdir(options.target): return log.error("%s is not a directory" % options.target) # Set the default docformat from epydoc import docstringparser docstringparser.DEFAULT_DOCFORMAT = options.docformat # Set the dot path if options.dotpath: from epydoc import dotgraph dotgraph.DOT_PATH = options.dotpath # Build docs for the named values. from epydoc.docbuilder import build_doc_index docindex = build_doc_index(names, options.introspect, options.parse, add_submodules=(options.action != 'text')) if docindex is None: return # docbuilder already logged an error. # Load profile information, if it was given. if options.pstat_files: try: profile_stats = pstats.Stats(options.pstat_files[0]) for filename in options.pstat_files[1:]: profile_stats.add(filename) except KeyboardInterrupt: raise except Exception, e: log.error("Error reading pstat file: %s" % e) profile_stats = None if profile_stats is not None: docindex.read_profiling_info(profile_stats)
def main(options, names): if options.action == 'text': if options.parse and options.introspect: options.parse = False # Set up the logger if options.action == 'text': logger = None # no logger for text output. elif options.verbosity > 1: logger = ConsoleLogger(options.verbosity) log.register_logger(logger) else: # Each number is a rough approximation of how long we spend on # that task, used to divide up the unified progress bar. stages = [40, # Building documentation 7, # Merging parsed & introspected information 1, # Linking imported variables 3, # Indexing documentation 30, # Parsing Docstrings 1, # Inheriting documentation 2] # Sorting & Grouping if options.action == 'html': stages += [100] elif options.action == 'text': stages += [30] elif options.action == 'latex': stages += [60] elif options.action == 'dvi': stages += [60,30] elif options.action == 'ps': stages += [60,40] elif options.action == 'pdf': stages += [60,50] elif options.action == 'check': stages += [10] else: raise ValueError, '%r not supported' % options.action if options.parse and not options.introspect: del stages[1] # no merging if options.introspect and not options.parse: del stages[1:3] # no merging or linking logger = UnifiedProgressConsoleLogger(options.verbosity, stages) log.register_logger(logger) # check the output directory. if options.action != 'text': if os.path.exists(options.target): if not os.path.isdir(options.target): return log.error("%s is not a directory" % options.target) # Set the default docformat from epydoc import docstringparser docstringparser.DEFAULT_DOCFORMAT = options.docformat # Set the dot path if options.dotpath: from epydoc import dotgraph dotgraph.DOT_PATH = options.dotpath # Build docs for the named values. from epydoc.docbuilder import build_doc_index docindex = build_doc_index(names, options.introspect, options.parse, add_submodules=(options.action!='text')) if docindex is None: return # docbuilder already logged an error. # Load profile information, if it was given. if options.pstat_files: try: profile_stats = pstats.Stats(options.pstat_files[0]) for filename in options.pstat_files[1:]: profile_stats.add(filename) except KeyboardInterrupt: raise except Exception, e: log.error("Error reading pstat file: %s" % e) profile_stats = None if profile_stats is not None: docindex.read_profiling_info(profile_stats)
try: server_path = DetectPackage("xVServer", ["../server"]) except ImportError: print "WARNING: xVServer not found in the PYTHONPATH or parent directory." print "Documentation will not be generated for xVServer." # build documentation index pkgs = filter(None, [client_path, xvlib_path, mapedit_path, server_path]) if len(pkgs) < 1: print "FATAL ERROR: No packages were found to generate documentation from." sys.exit() print "Generating documentation..." start = time.time() doc_index = docbuilder.build_doc_index(pkgs) # write documentation as HTML writer = HTMLWriter(doc_index, prj_name="xVector MMORPG Engine", prj_url="http://www.xvector.org", css="api.css") try: writer.write("api") except Exception as err: print " ** Error while writing HTML documentation: %s" % err.args[1] sys.exit() # complete print " ** Documentation generated in %f seconds." % (time.time() - start)