def test_classic_class(self):
     class C: "Classic class"
     c = C()
     self.assertEqual(pydoc.describe(C), 'class C')
     self.assertEqual(pydoc.describe(c), 'instance of C')
     expected = 'instance of C in module %s' % __name__
     self.assertIn(expected, pydoc.render_doc(c))

 def test_classic_class(self):
     class C: "Classic class"
     c = C()
     self.assertEqual(pydoc.describe(C), 'class C')
     self.assertEqual(pydoc.describe(c), 'C')
     expected = 'C in module %s' % __name__
     self.assertTrue(expected in pydoc.render_doc(c))

def dump_object(name, tmp_obj):
    print ">>>>>>>>>>>>>>>>>>>>>>>>>>", name, tmp_obj
    print describe(tmp_obj)

    # From line 921, method docmodule:
    classes = []
    for key, value in inspect.getmembers(tmp_obj, inspect.isclass):
        if (inspect.getmodule(value) or tmp_obj) is tmp_obj:
            classes.append((key, value))
            dump_object(key, value)
    funcs = []
    for key, value in inspect.getmembers(tmp_obj, inspect.isroutine):
        if inspect.isbuiltin(value) or inspect.getmodule(value) is tmp_obj:
            funcs.append((key, value))
    data = []
    for key, value in inspect.getmembers(tmp_obj, isdata):
        if key not in ['__builtins__', '__doc__']:
            data.append((key, value))
    methods = []
    for key, value in inspect.getmembers(tmp_obj, inspect.ismethod):
        if key not in ['__builtins__', '__doc__']:
            methods.append((key, value))

    print "C:", classes
    print "\nF:", funcs
    print "\nD:", data
    print "\nM:", methods
    for m in methods:
        print inspect.getargspec(m[1]), inspect.getdoc(m[1]), inspect.getcomments(m[1])
    print "<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<"

    def test_class(self):
        class C(object): "New-style class"
        c = C()

        self.assertEqual(pydoc.describe(C), 'class C')
        self.assertEqual(pydoc.describe(c), 'C')
        expected = 'C in module %s object' % __name__
        self.assertTrue(expected in pydoc.render_doc(c))

    def test_class(self):
        class C:
            "New-style class"

        c = C()

        self.assertEqual(pydoc.describe(C), "class C")
        self.assertEqual(pydoc.describe(c), "C")
        expected = "C in module %s object" % __name__
        self.assertIn(expected, pydoc.render_doc(c))

    def _generate_assertions_html(self, lang):
        object = pikzie.assertions.Assertions
        html_name = "html/assertions.html"
        translation = None
        if lang:
            html_name = "%s.%s" % (html_name, lang)
            translation = gettext.translation("pikzie", "data/locale", [lang])

        print(html_name)

        original_getdoc = pydoc.getdoc
        def getdoc(object):
            document = original_getdoc(object)
            if document == "":
                return document
            else:
                return translation.gettext(document)
        if translation:
            pydoc.getdoc = getdoc
        page = pydoc.html.page(pydoc.describe(object),
                               pydoc.html.document(object, "assertions"))
        pydoc.getdoc = original_getdoc

        html = file(html_name, "w")
        html.write(page.strip())
        html.close()

def doc2(thing, title="Python Library Documentation: %s", forceload=0):
    """Display text documentation, given an object or a path to an object."""
    import types

    try:
        object, name = pydoc.resolve(thing, forceload)
        desc = pydoc.describe(object)
        module = mygetmodule(object)
        if name and "." in name:
            desc += " in " + name[: name.rfind(".")]
        elif module and module is not object:
            desc += " in module " + module.__name__

        if not (
            inspect.ismodule(object)
            or inspect.isclass(object)
            or inspect.isroutine(object)
            or isinstance(object, property)
        ):
            # If the passed object is a piece of data or an instance,
            # document its available methods instead of its value.

            # if this is a instance of used defined old-style class
            if type(object) == types.InstanceType:
                object = object.__class__
            else:
                object = type(object)
            desc += " object"
        pydoc.pager(title % desc + "\n\n" + pydoc.text.document(object, name))
    except (ImportError, pydoc.ErrorDuringImport), value:
        print value

def gethtmldoc(thing, forceload=0):
    obj, name = pydoc.resolve(thing, forceload)
    page = pydoc.html.page(
        pydoc.describe(obj),
        pydoc.html.document(obj, name)
    )
    return page

def writedoc(key,top=False):
    """Write HTML documentation to a file in the current directory."""
    if(type(key) == str and (key == "modules" or key == "/.")):
        heading = pydoc.html.heading(
            '<br><big><big><strong>&nbsp;'
            'Python: Index of Modules'
            '</strong></big></big>',
            '#ffffff', '#7799ee')
        builtins = []
        for name in sys.builtin_module_names:
            builtins.append('<a href="%s">%s</a>' % (cgi.escape(name,quote=True), cgi.escape(name)))
        indices = ['<p>Built-in modules: ' + cgi.escape(join(builtins, ', '))]
        seen = {}
        for dir in pydoc.pathdirs():
            indices.append(pydoc.html.index(dir, seen))
        print cleanlinks(heading + join(indices))
        return

    if(type(key) != types.ModuleType):
        object = pydoc.locate(key)
        if(object == None and top):
            print "could not locate module/object for key " + \
                   cgi.escape(key) + "<br><a href=\"pydoc:modules\">go to index</a>";
    else:
        object = key
            
    if object:
        print cleanlinks(pydoc.html.page(pydoc.describe(object), pydoc.html.document(object)))

def PrintHtml(name, things):
  """Print HTML documentation to stdout."""
  ambiguous = len(things) > 1
  
  content = ""
  for thing in things:
    obj, name = pydoc.resolve(thing, forceload=0)
    title = pydoc.describe(obj)
    if ambiguous:
      if inspect.ismethoddescriptor(obj):
        content += '\n\n<h2>method %s in class %s</h2>\n' % (obj.__name__, obj.__dict__)
      else:
        content += '<h2>%s in module <a href="py:%s">%s</a></h2>\n' % (title, obj.__module__, obj.__module__)
    content += pydoc.html.document(obj, name)
  
  if ambiguous:
    title = 'Matches for "%s"' % name
    content = '<h1>%s</h1>\n\n%s' % (title, content)
  
  page = pydoc.html.page(title, content)
  
  # Note: rewriting the anchors in a form more useful to Evergreen should be in Evergreen, not here.
  # The rewriting here should be generally useful to anyone or anything that needs Python documentation.
  
  # Remove a couple of useless (and seemingly broken) links.
  page = page.replace('<a href=".">index</a><br>', '')
  page = re.sub('<br><a href="[^"]+\.html">Module Docs</a>', '', page)
  
  # There's a bug in pydoc that makes it output the text of the "Modules" section in cyan instead of white.
  page = re.sub('"#fffff"', '"#ffffff"', page)
  # The explicit font specifications are unnecessary manual uglification.
  page = re.sub(' face="[^"]+"', '', page);
  
  sys.stdout.write(page + '\n')

def _writeclientdoc(doc, thing, forceload=0):
    """Write HTML documentation to a file in the current directory.
    """
    docmodule = pydoc.HTMLDoc.docmodule
    def strongarm(self, object, name=None, mod=None, *ignored):
        result = docmodule(self, object, name, mod, *ignored)

        # Grab all the aliases to pyclasses and create links.
        nonmembers = []
        push = nonmembers.append
        for k,v in inspect.getmembers(object, inspect.isclass):
            if inspect.getmodule(v) is not object and getattr(v,'typecode',None) is not None:
                push('<a href="%s.html">%s</a>: pyclass alias<br/>' %(v.__name__,k))

        result += self.bigsection('Aliases', '#ffffff', '#eeaa77', ''.join(nonmembers))
        return result

    pydoc.HTMLDoc.docmodule = strongarm
    try:
        object, name = pydoc.resolve(thing, forceload)
        page = pydoc.html.page(pydoc.describe(object), pydoc.html.document(object, name))
        name = os.path.join(doc, name + '.html')
        file = open(name, 'w')
        file.write(page)
        file.close()
    except (ImportError, pydoc.ErrorDuringImport), value:
        log.debug(str(value))

def GenerateHTMLForModule(module):
  html = pydoc.html.page(pydoc.describe(module),
                         pydoc.html.document(module, module.__name__))

  # pydoc writes out html with links in a variety of funky ways. We need
  # to fix them up.
  assert not telemetry_dir.endswith(os.sep)
  links = re.findall('(<a href="(.+?)">(.+?)</a>)', html)
  for link_match in links:
    link, href, link_text = link_match
    if not href.startswith('file:'):
      continue

    new_href = href.replace('file:', '')
    new_href = new_href.replace(telemetry_dir, '..')
    new_href = new_href.replace(os.sep, '/')

    new_link_text = link_text.replace(telemetry_dir + os.sep, '')

    new_link = '<a href="%s">%s</a>' % (new_href, new_link_text)
    html = html.replace(link, new_link)

  # pydoc writes out html with absolute path file links. This is not suitable
  # for checked in documentation. So, fix up the HTML after it is generated.
  #html = re.sub('href="file:%s' % telemetry_dir, 'href="..', html)
  #html = re.sub(telemetry_dir + os.sep, '', html)
  return html

def local_docs(word):
    import pydoc
    try:
        obj, name = pydoc.resolve(word)
    except ImportError:
        return None
    desc = pydoc.describe(obj)
    return [(desc, urljoin(pydoc_url()[0], "%s.html" % word))]

def _writebrokedoc(doc, ex, name, forceload=0):
    try:
        fname = os.path.join(doc, name + '.html')
        page = pydoc.html.page(pydoc.describe(ex), pydoc.html.document(str(ex), fname))
        file = open(fname, 'w')
        file.write(page)
        file.close()
    except (ImportError, pydoc.ErrorDuringImport), value:
        log.debug(str(value))

def custom_writedoc(thing, forceload=0):
    """Write HTML documentation to specific directory"""
    try:
        object, name = pydoc.resolve(thing, forceload)
        page = pydoc.html.page(pydoc.describe(object), pydoc.html.document(object, name))
        file = open(PYDOC_OUTPUT_DIR + name + '.html', 'w')
        file.write(page)
        file.close()
        print 'wrote', PYDOC_OUTPUT_DIR + name + '.html'
    except (ImportError, pydoc.ErrorDuringImport), value:
        print value

def helpNonVerbose(thing, title='Python Library Documentation: %s', forceload=0):
    """
    Utility method to return python help in the form of a string
    (based on the code in pydoc.py)
    Note: only a string (including unicode) should be passed in for "thing"
    """
    
    import pydoc as pydocs
    import inspect
    import string

    result=""

    # Important for converting an incoming c++ unicode character string!
    thingStr=str(thing)

    """Display text documentation, given an object or a path to an object."""
    try:
        # Possible two-stage object resolution!
        # Sometimes we get docs for strings, other times for objects
        #
        try:
            object, name = pydocs.resolve(thingStr, forceload)
        except:
            # Get an object from a string
            thingObj=eval(thingStr)
            object, name = pydocs.resolve(thingObj, forceload)
        desc = pydocs.describe(object)
        module = inspect.getmodule(object)
        if name and '.' in name:
            desc += ' in ' + name[:name.rfind('.')]
        elif module and module is not object:
            desc += ' in module ' + module.__name__
        if not (inspect.ismodule(object) or
                inspect.isclass(object) or
                inspect.isroutine(object) or
                inspect.isgetsetdescriptor(object) or
                inspect.ismemberdescriptor(object) or
                isinstance(object, property)):
            # If the passed object is a piece of data or an instance,
            # document its available methods instead of its value.
            object = type(object)
            desc += ' object'
        text = pydocs.TextDoc()
        result=pydocs.plain(title % desc + '\n\n' + text.document(object, name))
        
        # Remove multiple empty lines
        result = [ line for line in result.splitlines() if line.strip() ]
        result = string.join(result,"\n")

    except:
        pass

    return result

def _writedoc(doc, thing, forceload=0):
    """Write HTML documentation to a file in the current directory.
    """
    try:
        object, name = pydoc.resolve(thing, forceload)
        page = pydoc.html.page(pydoc.describe(object), pydoc.html.document(object, name))
        fname = os.path.join(doc, name + '.html')
        file = open(fname, 'w')
        file.write(page)
        file.close()
    except (ImportError, pydoc.ErrorDuringImport), value:
        traceback.print_exc(sys.stderr)

def insert_formatted(buf, iter, obj, heading_type_tag, inline_type_tag, value_tag):
    """Insert a nicely-formatted display of obj into a gtk.TextBuffer

    @param buf: the buffer to insert the formatted display into
    @param iter: the location to insert the formatted display
    @param obj: the object to display in the buffer
    @param heading_type_tag: tag to use for the object type if we are outputting a block
    @param inline_type_tag: tag to use for the object type if we are outputting a single line
    @param value_tag: the tag to use for the objects value

    """

    text = format(obj)
     
    if text.find("\n") >= 0:
        insert_with_tag(buf, iter, pydoc.describe(obj), heading_type_tag)
        buf.insert(iter, "\n")
    else:
        insert_with_tag(buf, iter, pydoc.describe(obj), inline_type_tag)
        buf.insert(iter, ": ")

    insert_with_tag(buf, iter, text, value_tag)

def docHTML(text):
    """ just testing """
    import pydoc
    try:
        token=text.split()[-1]
        if '(' in token:   #better do regex
           token=token[:-1]
        obj=eval(token)
        #pyobj,name=pydoc.resolve(obj,0)
        ins=pydoc.plain(pydoc.render_doc(obj))
        html=pydoc.HTMLDoc()
        return html.page(pydoc.describe(obj), html.document(obj, name))
    except NameError:
        pass

def buildAllDocs(symbol='pyroclast'):
	"""Recursively constructs HTML pages of documentation the given module
	   contents, beginning with pyroclast itself, which are subsequently written
	   to the package's 'docs/' folder.
	"""
	dd = getDocDir()
	obj, name = pydoc.resolve(symbol)
	page = pydoc.html.page(pydoc.describe(obj), pydoc.html.document(obj,name))
	with open(dd + name + '.html', 'w') as f:
		f.write(page)
	if hasattr(obj, '__all__'):
		for a in obj.__all__:
			identifier = name + '.' + a
			child = importlib.import_module(identifier)
			buildAllDocs(child)