def test_multiple_types(): mod = fromText(''' def f(a): """ @param a: it\'s a parameter! @type a: a pink thing! @type a: no, blue! aaaargh! """ class C(object): """ @ivar a: it\'s an instance var @type a: a pink thing! @type a: no, blue! aaaargh! """ class D(object): """ @cvar a: it\'s an instance var @type a: a pink thing! @type a: no, blue! aaaargh! """ class E(object): """ @cvar: missing name @type: name still missing """ ''') # basically "assert not fail": epydoc2stan.doc2stan(mod.contents['f']) epydoc2stan.doc2stan(mod.contents['C']) epydoc2stan.doc2stan(mod.contents['D']) epydoc2stan.doc2stan(mod.contents['E'])
def get(self, ob, summary=False): doc = epydoc2stan.doc2stan(ob, summary=summary) typ = epydoc2stan.type2stan(ob) if typ is None: return doc else: return [doc, ' (type: ', typ, ')']
def stanForOb(self, ob, summary=False): current_docstring = self.currentDocstringForObject(ob) if summary: return epydoc2stan.doc2stan( ob.doctarget, summary=True, docstring=current_docstring)[0] r = [tags.div(epydoc2stan.doc2stan(ob.doctarget, docstring=current_docstring)[0]), tags.a(href="edit?ob="+ob.fullName())("Edit"), " "] if ob.doctarget in self.editsbyob: r.append(tags.a(href="history?ob="+ob.fullName())( "View docstring history (", str(len(self.editsbyob[ob.doctarget])), " versions)")) else: r.append(tags.span(class_='undocumented')("No edits yet.")) return r
def get_summary(func): def part_flat(x): if isinstance(x, list): return "".join(map(part_flat, x)) else: return x return part_flat( epydoc2stan.doc2stan(mod.contents[func], summary=True)[0].children)
def get_summary(func): def part_flat(x): if isinstance(x, list): return ''.join(map(part_flat, x)) else: return x return part_flat( epydoc2stan.doc2stan( mod.contents[func], summary=True)[0].children)
def moduleSummary(modorpack): r = tags.li(taglink(modorpack), ' - ', epydoc2stan.doc2stan(modorpack, summary=True)[0]) if not isinstance(modorpack, model.Package): return r contents = [m for m in modorpack.orderedcontents if m.isVisible and m.name != '__init__'] if not contents: return r ul = tags.ul() for m in sorted(contents, key=lambda m:m.fullName()): ul(moduleSummary(m)) return r(ul)
def moduleSummary(modorpack): r = tags.li(util.taglink(modorpack), ' - ', epydoc2stan.doc2stan(modorpack, summary=True)[0]) if not isinstance(modorpack, model.Package): return r contents = [m for m in modorpack.orderedcontents if m.isVisible and m.name != '__init__'] if not contents: return r ul = tags.ul() for m in sorted(contents, key=lambda m:m.fullName()): ul(moduleSummary(m)) return r(ul)
def test_multiple_types(): mod = fromText(''' def f(a): """ @param a: it\'s a parameter! @type a: a pink thing! @type a: no, blue! aaaargh! """ class C(object): """ @ivar a: it\'s an instance var @type a: a pink thing! @type a: no, blue! aaaargh! """ class D(object): """ @cvar a: it\'s an instance var @type a: a pink thing! @type a: no, blue! aaaargh! """ ''') # basically "assert not fail": epydoc2stan.doc2stan(mod.contents["f"]) epydoc2stan.doc2stan(mod.contents["C"]) epydoc2stan.doc2stan(mod.contents["D"])
def test_multiple_types(): mod = fromText(''' def f(a): """ @param a: it\'s a parameter! @type a: a pink thing! @type a: no, blue! aaaargh! """ class C(object): """ @ivar a: it\'s an instance var @type a: a pink thing! @type a: no, blue! aaaargh! """ class D(object): """ @cvar a: it\'s an instance var @type a: a pink thing! @type a: no, blue! aaaargh! """ ''') # basically "assert not fail": epydoc2stan.doc2stan(mod.contents['f']) epydoc2stan.doc2stan(mod.contents['C']) epydoc2stan.doc2stan(mod.contents['D'])
def subclassesFrom(hostsystem, cls, anchors): r = tags.li() name = cls.fullName() if name not in anchors: r(tags.a(name=name)) anchors.add(name) r(util.taglink(cls), ' - ', epydoc2stan.doc2stan(cls, summary=True)[0]) scs = [sc for sc in cls.subclasses if sc.system is hostsystem and ' ' not in sc.fullName() and sc.isVisible] if len(scs) > 0: ul = tags.ul() for sc in sorted(scs, key=_lckey): ul(subclassesFrom(hostsystem, sc, anchors)) r(ul) return r
def subclassesFrom(hostsystem, cls, anchors): r = tags.li() name = cls.fullName() if name not in anchors: r(tags.a(name=name)) anchors.add(name) r(taglink(cls), ' - ', epydoc2stan.doc2stan(cls, summary=True)[0]) scs = [sc for sc in cls.subclasses if sc.system is hostsystem and ' ' not in sc.fullName() and sc.isVisible] if len(scs) > 0: ul = tags.ul() for sc in sorted(scs, key=_lckey): ul(subclassesFrom(hostsystem, sc, anchors)) r(ul) return r
def preview(self, request, tag): docstring = parse_str(self.docstring) stan, errors = epydoc2stan.doc2stan( self.ob, docstring=docstring) if self.isPreview or errors: if errors: #print stan, errors #assert isinstance(stan, tags.pre) [text] = stan.children lines = text.replace('\r\n', '\n').split('\n') line2err = {} for err in errors: if isinstance(err, str): ln = None else: ln = err.linenum() line2err.setdefault(ln, []).append(err) w = len(str(len(lines))) for i, line in enumerate(lines): i += 1 cls = "preview" if i in line2err: cls += " error" tag(tags.pre(class_=cls)("%*s"%(w, i), ' ', line)) for err in line2err.get(i, []): tag(tags.p(class_="errormessage")(err.descr())) i += 1 for err in line2err.get(i, []): tag(tags.p(class_="errormessage")(err.descr())) items = [] for err in line2err.get(None, []): items.append(tags.li(str(err))) if items: tag(tags.ul(items)) else: tag = tag(stan) return tag(tags.h2("Edit")) else: return ()
def docstring(self, request, tag): docstring = self.root.edits(self.ob)[self.rev].newDocstring if docstring is None: docstring = '' return epydoc2stan.doc2stan(self.ob, docstring=docstring)[0]
def get(self, ob, summary=False): return epydoc2stan.doc2stan(ob, summary=summary)[0]
def get_summary(func): stan = epydoc2stan.doc2stan(mod.contents[func], summary=True) assert stan.tagName == 'span', stan return flatten(stan.children)
def main(args): import cPickle options, args = parse_args(args) exitcode = 0 if options.configfile: readConfigFile(options) try: # step 1: make/find the system if options.systemclass: systemclass = findClassFromDottedName(options.systemclass, '--system-class') if not issubclass(systemclass, model.System): msg = "%s is not a subclass of model.System" error(msg, systemclass) else: systemclass = zopeinterface.ZopeInterfaceSystem if options.inputpickle: system = cPickle.load(open(options.inputpickle, 'rb')) if options.systemclass: if type(system) is not systemclass: cls = type(system) msg = ("loaded pickle has class %s.%s, differing " "from explicitly requested %s") error(msg, cls.__module__, cls.__name__, options.systemclass) else: system = systemclass() # Once pickle support is removed, always instantiate System with # options and make fetchIntersphinxInventories private in __init__. system.options = options system.fetchIntersphinxInventories() system.urlprefix = '' if options.moresystems: moresystems = [] for fnamepref in options.moresystems: fname, prefix = fnamepref.split(':', 1) moresystems.append(cPickle.load(open(fname, 'rb'))) moresystems[-1].urlprefix = prefix moresystems[-1].options = system.options moresystems[-1].subsystems.append(system) system.moresystems = moresystems system.sourcebase = options.htmlsourcebase if options.abbrevmapping: for thing in options.abbrevmapping.split(','): k, v = thing.split('=') system.abbrevmapping[k] = v # step 1.5: check that we're actually going to accomplish something here if options.auto: options.server = True options.edit = True for fn in os.listdir('.'): if os.path.isdir(fn) and \ os.path.exists(os.path.join(fn, '__init__.py')): options.packages.append(fn) elif fn.endswith('.py') and fn != 'setup.py': options.modules.append(fn) args = list(args) + options.modules + options.packages if options.makehtml == MAKE_HTML_DEFAULT: if not options.outputpickle and not options.testing \ and not options.server and not options.makeintersphinx: options.makehtml = True else: options.makehtml = False if options.buildtime: try: system.buildtime = datetime.datetime.strptime( options.buildtime, BUILDTIME_FORMAT) except ValueError, e: error(e) # step 2: add any packages and modules if args: prependedpackage = None if options.prependedpackage: for m in options.prependedpackage.split('.'): prependedpackage = system.Package( system, m, None, prependedpackage) system.addObject(prependedpackage) initmodule = system.Module(system, '__init__', None, prependedpackage) system.addObject(initmodule) for path in args: path = os.path.abspath(path) if path in system.packages: continue if os.path.isdir(path): system.msg('addPackage', 'adding directory ' + path) system.addPackage(path, prependedpackage) else: system.msg('addModuleFromPath', 'adding module ' + path) system.addModuleFromPath(prependedpackage, path) system.packages.append(path) # step 3: move the system to the desired state if not system.packages: error("The system does not contain any code, did you " "forget an --add-package?") system.process() if system.options.livecheck: error("write this") if system.options.projectname is None: name = '/'.join([ro.name for ro in system.rootobjects]) system.msg( 'warning', 'WARNING: guessing '+name+' for project name', thresh=-1) system.projectname = name else: system.projectname = system.options.projectname # step 4: save the system, if desired if options.outputpickle: system.msg('', 'saving output pickle to ' + options.outputpickle) del system.options # don't persist the options f = open(options.outputpickle, 'wb') cPickle.dump(system, f, cPickle.HIGHEST_PROTOCOL) f.close() system.options = options # step 5: make html, if desired if options.makehtml: options.makeintersphinx = True if options.htmlwriter: writerclass = findClassFromDottedName( options.htmlwriter, '--html-writer') else: from pydoctor import templatewriter writerclass = templatewriter.TemplateWriter system.msg('html', 'writing html to %s using %s.%s'%( options.htmloutput, writerclass.__module__, writerclass.__name__)) writer = writerclass(options.htmloutput) writer.system = system writer.prepOutputDirectory() system.epytextproblems = [] if options.htmlsubjects: subjects = [] for fn in options.htmlsubjects: subjects.append(system.allobjects[fn]) elif options.htmlsummarypages: writer.writeModuleIndex(system) subjects = [] else: writer.writeModuleIndex(system) subjects = system.rootobjects writer.writeIndividualFiles(subjects, options.htmlfunctionpages) if system.epytextproblems: def p(msg): system.msg(('epytext', 'epytext-summary'), msg, thresh=-1, topthresh=1) p("these %s objects' docstrings are not proper epytext:" %(len(system.epytextproblems),)) exitcode = 2 for fn in system.epytextproblems: p(' '+fn) if options.outputpickle: system.msg( '', 'saving output pickle to ' + options.outputpickle) # save again, with epytextproblems del system.options # don't persist the options f = open(options.outputpickle, 'wb') cPickle.dump(system, f, cPickle.HIGHEST_PROTOCOL) f.close() system.options = options if options.makeintersphinx: if not options.makehtml: subjects = system.rootobjects # Generate Sphinx inventory. sphinx_inventory = SphinxInventory( logger=system.msg, project_name=system.projectname, ) if not os.path.exists(options.htmloutput): os.makedirs(options.htmloutput) sphinx_inventory.generate( subjects=subjects, basepath=options.htmloutput, ) # Finally, if we should serve html, lets serve some html. if options.server: from pydoctor.server import ( EditingPyDoctorResource, PyDoctorResource) from pydoctor.epydoc2stan import doc2stan from twisted.web.server import Site from twisted.web.resource import Resource from twisted.web.vhost import VHostMonsterResource from twisted.internet import reactor if options.edit: if not options.nocheck: system.msg( "server", "Checking formatting of docstrings.") included_obs = [ ob for ob in system.orderedallobjects if ob.isVisible] for i, ob in enumerate(included_obs): system.progress( "server", i+1, len(included_obs), "docstrings checked, found %s problems" % ( len(system.epytextproblems))) doc2stan(ob, docstring=ob.docstring) root = EditingPyDoctorResource(system) else: root = PyDoctorResource(system) if options.facing_path: options.local_only = True realroot = Resource() cur = realroot realroot.putChild('vhost', VHostMonsterResource()) segments = options.facing_path.split('/') for segment in segments[:-1]: next = Resource() cur.putChild(segment, next) cur = next cur.putChild(segments[-1], root) root = realroot system.msg( "server", "Setting up server at http://localhost:%d/" % options.server_port) if options.auto: def wb_open(): import webbrowser webbrowser.open( 'http://localhost:%d/' % options.server_port) reactor.callWhenRunning(wb_open) from twisted.python import log log.startLogging(sys.stdout) site = Site(root) if options.local_only: interface = 'localhost' else: interface = '' reactor.listenTCP(options.server_port, site, interface=interface) reactor.run()