示例#1
0
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
示例#2
0
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
示例#3
0
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'))
示例#4
0
文件: util.py 项目: nltk/epydoc
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
示例#5
0
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]
示例#7
0
文件: setup.py 项目: g2p/systems
     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)
示例#8
0
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
示例#9
0
文件: setup.py 项目: Niner10/ITK-1
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"))
示例#10
0
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)
示例#11
0
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
示例#12
0
文件: epydoc.py 项目: zhengft/scons
        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
示例#13
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'))
示例#14
0
文件: setup.py 项目: Niner10/ITK
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') )
示例#15
0
 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
示例#16
0
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)
示例#17
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'
                              , 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') )
示例#18
0
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
示例#19
0
 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
示例#21
0
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)
示例#22
0
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)
示例#23
0
文件: cli.py 项目: Angeleena/selenium
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)
示例#24
0
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)