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