# -*- coding: utf-8 -*- """ sphinx.environment ~~~~~~~~~~~~~~~~~~ Global creation environment. :copyright: 2007-2009 by Georg Brandl. :license: BSD. """ import re import os import time import heapq import types import imghdr import difflib import cPickle as pickle from os import path from glob import glob from string import ascii_uppercase as uppercase from itertools import izip, groupby try: import hashlib md5 = hashlib.md5 except ImportError: # 2.4 compatibility import md5 md5 = md5.new from docutils import nodes from docutils.io import FileInput, NullOutput from docutils.core import Publisher from docutils.utils import Reporter, relative_path from docutils.readers import standalone from docutils.parsers.rst import roles from docutils.parsers.rst.languages import en as english from docutils.parsers.rst.directives.html import MetaBody from docutils.writers import UnfilteredWriter from docutils.transforms import Transform from docutils.transforms.parts import ContentsFilter from sphinx import addnodes from sphinx.util import get_matching_docs, SEP, ustrftime from sphinx.directives import additional_xref_types default_settings = { 'embed_stylesheet': False, 'cloak_email_addresses': True, 'pep_base_url': 'http://www.python.org/dev/peps/', 'rfc_base_url': 'http://rfc.net/', 'input_encoding': 'utf-8', 'doctitle_xform': False, 'sectsubtitle_xform': False, } # This is increased every time an environment attribute is added # or changed to properly invalidate pickle files. ENV_VERSION = 26 default_substitutions = set([ 'version', 'release', 'today', ]) dummy_reporter = Reporter('', 4, 4) class RedirStream(object): def __init__(self, writefunc): self.writefunc = writefunc def write(self, text): if text.strip(): self.writefunc(text) class NoUri(Exception): """Raised by get_relative_uri if there is no URI available.""" pass class DefaultSubstitutions(Transform): """ Replace some substitutions if they aren't defined in the document. """ # run before the default Substitutions default_priority = 210 def apply(self): config = self.document.settings.env.config # only handle those not otherwise defined in the document to_handle = default_substitutions - set(self.document.substitution_defs) for ref in self.document.traverse(nodes.substitution_reference): refname = ref['refname'] if refname in to_handle: text = config[refname] if refname == 'today' and not text: # special handling: can also specify a strftime format text = ustrftime(config.today_fmt or _('%B %d, %Y')) ref.replace_self(nodes.Text(text, text)) class MoveModuleTargets(Transform): """ Move module targets to their nearest enclosing section title. """ default_priority = 210 def apply(self): for node in self.document.traverse(nodes.target): if not node['ids']: continue if node['ids'][0].startswith('module-') and \ node.parent.__class__ is nodes.section: node.parent['ids'] = node['ids'] node.parent.remove(node) class HandleCodeBlocks(Transform): """ Move doctest blocks out of blockquotes. """ default_priority = 210 def apply(self): for node in self.document.traverse(nodes.block_quote): if len(node.children) == 1 and isinstance(node.children[0], nodes.doctest_block): node.replace_self(node.children[0]) class CitationReferences(Transform): """ Handle citation references before the default docutils transform does. """ default_priority = 619 def apply(self): for citnode in self.document.traverse(nodes.citation_reference): cittext = citnode.astext() refnode = addnodes.pending_xref(cittext, reftype='citation', reftarget=cittext) refnode += nodes.Text('[' + cittext + ']') citnode.parent.replace(citnode, refnode) class SphinxStandaloneReader(standalone.Reader): """ Add our own transforms. """ transforms = [CitationReferences, DefaultSubstitutions, MoveModuleTargets, HandleCodeBlocks] def get_transforms(self): return standalone.Reader.get_transforms(self) + self.transforms class SphinxDummyWriter(UnfilteredWriter): supported = ('html',) # needed to keep "meta" nodes def translate(self): pass class SphinxContentsFilter(ContentsFilter): """ Used with BuildEnvironment.add_toc_from() to discard cross-file links within table-of-contents link nodes. """ def visit_pending_xref(self, node): text = node.astext() self.parent.append(nodes.literal(text, text)) raise nodes.SkipNode class BuildEnvironment: """ The environment in which the ReST files are translated. Stores an inventory of cross-file targets and provides doctree transformations to resolve links to them. """ # --------- ENVIRONMENT PERSISTENCE ---------------------------------------- @staticmethod def frompickle(config, filename): picklefile = open(filename, 'rb') try: env = pickle.load(picklefile) finally: picklefile.close() env.config.values = config.values if env.version != ENV_VERSION: raise IOError('env version not current') return env def topickle(self, filename): # remove unpicklable attributes warnfunc = self._warnfunc self.set_warnfunc(None) values = self.config.values del self.config.values # first write to a temporary file, so that if dumping fails, the existing # environment won't be overwritten picklefile = open(filename + '.tmp', 'wb') # remove potentially pickling-problematic values from config for key, val in vars(self.config).items(): if key.startswith('_') or \ isinstance(val, types.ModuleType) or \ isinstance(val, types.FunctionType) or \ isinstance(val, (type, types.ClassType)): del self.config[key] try: pickle.dump(self, picklefile, pickle.HIGHEST_PROTOCOL) finally: picklefile.close() os.rename(filename + '.tmp', filename) # reset attributes self.config.values = values self.set_warnfunc(warnfunc) # --------- ENVIRONMENT INITIALIZATION ------------------------------------- def __init__(self, srcdir, doctreedir, config): self.doctreedir = doctreedir self.srcdir = srcdir self.config = config # the application object; only set while update() runs self.app = None # the docutils settings for building self.settings = default_settings.copy() self.settings['env'] = self # the function to write warning messages with self._warnfunc = None # this is to invalidate old pickles self.version = ENV_VERSION # All "docnames" here are /-separated and relative and exclude the source suffix. self.found_docs = set() # contains all existing docnames self.all_docs = {} # docname -> mtime at the time of build # contains all built docnames self.dependencies = {} # docname -> set of dependent file names, relative to # documentation root # File metadata self.metadata = {} # docname -> dict of metadata items # TOC inventory self.titles = {} # docname -> title node self.tocs = {} # docname -> table of contents nodetree self.toc_num_entries = {} # docname -> number of real entries # used to determine when to show the TOC in a sidebar # (don't show if it's only one item) self.toctree_includes = {} # docname -> list of toctree includefiles self.files_to_rebuild = {} # docname -> set of files (containing its TOCs) # to rebuild too self.glob_toctrees = set() # docnames that have :glob: toctrees # X-ref target inventory self.descrefs = {} # fullname -> docname, desctype self.filemodules = {} # docname -> [modules] self.modules = {} # modname -> docname, synopsis, platform, deprecated self.labels = {} # labelname -> docname, labelid, sectionname self.anonlabels = {} # labelname -> docname, labelid self.progoptions = {} # (program, name) -> docname, labelid self.reftargets = {} # (type, name) -> docname, labelid # where type is term, token, envvar, citation # Other inventories self.indexentries = {} # docname -> list of # (type, string, target, aliasname) self.versionchanges = {} # version -> list of # (type, docname, lineno, module, descname, content) self.images = {} # absolute path -> (docnames, unique filename) # These are set while parsing a file self.docname = None # current document name self.currmodule = None # current module name self.currclass = None # current class name self.currdesc = None # current descref name self.currprogram = None # current program name self.index_num = 0 # autonumber for index targets self.gloss_entries = set() # existing definition labels # Some magically present labels self.labels['genindex'] = ('genindex', '', _('Index')) self.labels['modindex'] = ('modindex', '', _('Module Index')) self.labels['search'] = ('search', '', _('Search Page')) def set_warnfunc(self, func): self._warnfunc = func self.settings['warning_stream'] = RedirStream(func) def warn(self, docname, msg, lineno=None): if docname: if lineno is None: lineno = '' self._warnfunc('%s:%s: %s' % (self.doc2path(docname), lineno, msg)) else: self._warnfunc('GLOBAL:: ' + msg) def clear_doc(self, docname): """Remove all traces of a source file in the inventory.""" if docname in self.all_docs: self.all_docs.pop(docname, None) self.metadata.pop(docname, None) self.dependencies.pop(docname, None) self.titles.pop(docname, None) self.tocs.pop(docname, None) self.toc_num_entries.pop(docname, None) self.toctree_includes.pop(docname, None) self.filemodules.pop(docname, None) self.indexentries.pop(docname, None) self.glob_toctrees.discard(docname) for subfn, fnset in self.files_to_rebuild.items(): fnset.discard(docname) if not fnset: del self.files_to_rebuild[subfn] for fullname, (fn, _) in self.descrefs.items(): if fn == docname: del self.descrefs[fullname] for modname, (fn, _, _, _) in self.modules.items(): if fn == docname: del self.modules[modname] for labelname, (fn, _, _) in self.labels.items(): if fn == docname: del self.labels[labelname] for key, (fn, _) in self.reftargets.items(): if fn == docname: del self.reftargets[key] for key, (fn, _) in self.progoptions.items(): if fn == docname: del self.progoptions[key] for version, changes in self.versionchanges.items(): new = [change for change in changes if change[1] != docname] changes[:] = new for fullpath, (docs, _) in self.images.items(): docs.discard(docname) if not docs: del self.images[fullpath] def doc2path(self, docname, base=True, suffix=None): """ Return the filename for the document name. If base is True, return absolute path under self.srcdir. If base is None, return relative path to self.srcdir. If base is a path string, return absolute path under that. If suffix is not None, add it instead of config.source_suffix. """ suffix = suffix or self.config.source_suffix if base is True: return path.join(self.srcdir, docname.replace(SEP, path.sep)) + suffix elif base is None: return docname.replace(SEP, path.sep) + suffix else: return path.join(base, docname.replace(SEP, path.sep)) + suffix def find_files(self, config): """ Find all source files in the source dir and put them in self.found_docs. """ exclude_dirs = [d.replace(SEP, path.sep) for d in config.exclude_dirs] exclude_trees = [d.replace(SEP, path.sep) for d in config.exclude_trees] self.found_docs = set(get_matching_docs( self.srcdir, config.source_suffix, exclude_docs=set(config.unused_docs), exclude_dirs=exclude_dirs, exclude_trees=exclude_trees, exclude_dirnames=['_sources'] + config.exclude_dirnames)) def get_outdated_files(self, config_changed): """ Return (added, changed, removed) sets. """ # clear all files no longer present removed = set(self.all_docs) - self.found_docs added = set() changed = set() if config_changed: # config values affect e.g. substitutions added = self.found_docs else: for docname in self.found_docs: if docname not in self.all_docs: added.add(docname) continue # if the doctree file is not there, rebuild if not path.isfile(self.doc2path(docname, self.doctreedir, '.doctree')): changed.add(docname) continue # check the mtime of the document mtime = self.all_docs[docname] newmtime = path.getmtime(self.doc2path(docname)) if newmtime > mtime: changed.add(docname) continue # finally, check the mtime of dependencies for dep in self.dependencies.get(docname, ()): try: # this will do the right thing when dep is absolute too deppath = path.join(self.srcdir, dep) if not path.isfile(deppath): changed.add(docname) break depmtime = path.getmtime(deppath) if depmtime > mtime: changed.add(docname) break except EnvironmentError: # give it another chance changed.add(docname) break return added, changed, removed def update(self, config, srcdir, doctreedir, app=None): """(Re-)read all files new or changed since last update. Yields a summary and then docnames as it processes them. Store all environment docnames in the canonical format (ie using SEP as a separator in place of os.path.sep).""" config_changed = False if self.config is None: msg = '[new config] ' config_changed = True else: # check if a config value was changed that affects how doctrees are read for key, descr in config.config_values.iteritems(): if not descr[1]: continue if self.config[key] != config[key]: msg = '[config changed] ' config_changed = True break else: msg = '' # this value is not covered by the above loop because it is handled # specially by the config class if self.config.extensions != config.extensions: msg = '[extensions changed] ' config_changed = True # the source and doctree directories may have been relocated self.srcdir = srcdir self.doctreedir = doctreedir self.find_files(config) added, changed, removed = self.get_outdated_files(config_changed) # if files were added or removed, all documents with globbed toctrees # must be reread if added or removed: changed.update(self.glob_toctrees) msg += '%s added, %s changed, %s removed' % (len(added), len(changed), len(removed)) yield msg self.config = config self.app = app # clear all files no longer present for docname in removed: if app: app.emit('env-purge-doc', self, docname) self.clear_doc(docname) # read all new and changed files for docname in sorted(added | changed): yield docname self.read_doc(docname, app=app) if config.master_doc not in self.all_docs: self.warn(None, 'master file %s not found' % self.doc2path(config.master_doc)) self.app = None # remove all non-existing images from inventory for imgsrc in self.images.keys(): if not os.access(path.join(self.srcdir, imgsrc), os.R_OK): del self.images[imgsrc] if app: app.emit('env-updated', self) # --------- SINGLE FILE READING -------------------------------------------- def read_doc(self, docname, src_path=None, save_parsed=True, app=None): """ Parse a file and add/update inventory entries for the doctree. If srcpath is given, read from a different source file. """ # remove all inventory entries for that file if app: app.emit('env-purge-doc', self, docname) self.clear_doc(docname) if src_path is None: src_path = self.doc2path(docname) if self.config.default_role: role_fn, messages = roles.role(self.config.default_role, english, 0, dummy_reporter) if role_fn: roles._roles[''] = role_fn else: self.warn(docname, 'default role %s not found' % self.config.default_role) self.docname = docname self.settings['input_encoding'] = self.config.source_encoding class SphinxSourceClass(FileInput): def read(self): data = FileInput.read(self) if app: arg = [data] app.emit('source-read', docname, arg) data = arg[0] return data # publish manually pub = Publisher(reader=SphinxStandaloneReader(), writer=SphinxDummyWriter(), source_class=SphinxSourceClass, destination_class=NullOutput) pub.set_components(None, 'restructuredtext', None) pub.process_programmatic_settings(None, self.settings, None) pub.set_source(None, src_path) pub.set_destination(None, None) try: pub.publish() doctree = pub.document except UnicodeError, err: from sphinx.application import SphinxError raise SphinxError(err.message) self.filter_messages(doctree) self.process_dependencies(docname, doctree) self.process_images(docname, doctree) self.process_metadata(docname, doctree) self.create_title_from(docname, doctree) self.note_labels_from(docname, doctree) self.note_indexentries_from(docname, doctree) self.note_citations_from(docname, doctree) self.build_toc_from(docname, doctree) # store time of reading, used to find outdated files self.all_docs[docname] = time.time() if app: app.emit('doctree-read', doctree) # make it picklable doctree.reporter = None doctree.transformer = None doctree.settings.warning_stream = None doctree.settings.env = None doctree.settings.record_dependencies = None for metanode in doctree.traverse(MetaBody.meta): # docutils' meta nodes aren't picklable because the class is nested metanode.__class__ = addnodes.meta # cleanup self.docname = None self.currmodule = None self.currclass = None self.gloss_entries = set() if save_parsed: # save the parsed doctree doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree') dirname = path.dirname(doctree_filename) if not path.isdir(dirname): os.makedirs(dirname) f = open(doctree_filename, 'wb') try: pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL) finally: f.close() else: return doctree def filter_messages(self, doctree): """ Filter system messages from a doctree. """ filterlevel = self.config.keep_warnings and 2 or 5 for node in doctree.traverse(nodes.system_message): if node['level'] < filterlevel: node.parent.remove(node) def process_dependencies(self, docname, doctree): """ Process docutils-generated dependency info. """ deps = doctree.settings.record_dependencies if not deps: return docdir = path.dirname(self.doc2path(docname, base=None)) for dep in deps.list: dep = path.join(docdir, dep) self.dependencies.setdefault(docname, set()).add(dep) def process_images(self, docname, doctree): """ Process and rewrite image URIs. """ existing_names = set(v[1] for v in self.images.itervalues()) docdir = path.dirname(self.doc2path(docname, base=None)) for node in doctree.traverse(nodes.image): # Map the mimetype to the corresponding image. The writer may # choose the best image from these candidates. The special key * is # set if there is only single candiate to be used by a writer. # The special key ? is set for nonlocal URIs. node['candidates'] = candidates = {} imguri = node['uri'] if imguri.find('://') != -1: self.warn(docname, 'Nonlocal image URI found: %s' % imguri, node.line) candidates['?'] = imguri continue # imgpath is the image path *from srcdir* imgpath = path.normpath(path.join(docdir, imguri)) # set imgpath as default URI node['uri'] = imgpath if imgpath.endswith(os.extsep + '*'): for filename in glob(path.join(self.srcdir, imgpath)): new_imgpath = relative_path(self.srcdir, filename) if filename.lower().endswith('.pdf'): candidates['application/pdf'] = new_imgpath elif filename.lower().endswith('.svg'): candidates['image/svg+xml'] = new_imgpath else: try: f = open(filename, 'rb') try: imgtype = imghdr.what(f) finally: f.close() except (OSError, IOError): self.warn(docname, 'Image file %s not readable' % filename) if imgtype: candidates['image/' + imgtype] = new_imgpath else: candidates['*'] = imgpath # map image paths to unique image names (so that they can be put # into a single directory) for imgpath in candidates.itervalues(): self.dependencies.setdefault(docname, set()).add(imgpath) if not os.access(path.join(self.srcdir, imgpath), os.R_OK): self.warn(docname, 'Image file not readable: %s' % imgpath, node.line) if imgpath in self.images: self.images[imgpath][0].add(docname) continue uniquename = path.basename(imgpath) base, ext = path.splitext(uniquename) i = 0 while uniquename in existing_names: i += 1 uniquename = '%s%s%s' % (base, i, ext) self.images[imgpath] = (set([docname]), uniquename) existing_names.add(uniquename) def process_metadata(self, docname, doctree): """ Process the docinfo part of the doctree as metadata. """ self.metadata[docname] = md = {} try: docinfo = doctree[0] except IndexError: # probably an empty document return if docinfo.__class__ is not nodes.docinfo: # nothing to see here return for node in docinfo: if node.__class__ is nodes.author: # handled specially by docutils md['author'] = node.astext() elif node.__class__ is nodes.field: name, body = node md[name.astext()] = body.astext() del doctree[0] def create_title_from(self, docname, document): """ Add a title node to the document (just copy the first section title), and store that title in the environment. """ for node in document.traverse(nodes.section): titlenode = nodes.title() visitor = SphinxContentsFilter(document) node[0].walkabout(visitor) titlenode += visitor.get_entry_text() self.titles[docname] = titlenode return def note_labels_from(self, docname, document): for name, explicit in document.nametypes.iteritems(): if not explicit: continue labelid = document.nameids[name] if labelid is None: continue node = document.ids[labelid] if name.isdigit() or node.has_key('refuri') or \ node.tagname.startswith('desc_'): # ignore footnote labels, labels automatically generated from a # link and description units continue if name in self.labels: self.warn(docname, 'duplicate label %s, ' % name + 'other instance in %s' % self.doc2path(self.labels[name][0]), node.line) self.anonlabels[name] = docname, labelid if node.tagname == 'section': sectname = node[0].astext() # node[0] == title node elif node.tagname == 'figure': for n in node: if n.tagname == 'caption': sectname = n.astext() break else: continue else: # anonymous-only labels continue self.labels[name] = docname, labelid, sectname def note_indexentries_from(self, docname, document): entries = self.indexentries[docname] = [] for node in document.traverse(addnodes.index): entries.extend(node['entries']) def note_citations_from(self, docname, document): for node in document.traverse(nodes.citation): label = node[0].astext() if ('citation', label) in self.reftargets: self.warn(docname, 'duplicate citation %s, ' % label + 'other instance in %s' % self.doc2path( self.reftargets['citation', label][0]), node.line) self.reftargets['citation', label] = (docname, node['ids'][0]) def note_toctree(self, docname, toctreenode): """Note a TOC tree directive in a document and gather information about file relations from it.""" if toctreenode['glob']: self.glob_toctrees.add(docname) includefiles = toctreenode['includefiles'] for includefile in includefiles: # note that if the included file is rebuilt, this one must be # too (since the TOC of the included file could have changed) self.files_to_rebuild.setdefault(includefile, set()).add(docname) self.toctree_includes.setdefault(docname, []).extend(includefiles) def build_toc_from(self, docname, document): """Build a TOC from the doctree and store it in the inventory.""" numentries = [0] # nonlocal again... try: maxdepth = int(self.metadata[docname].get('tocdepth', 0)) except ValueError: maxdepth = 0 def build_toc(node, depth=1): entries = [] for subnode in node: if isinstance(subnode, addnodes.toctree): # just copy the toctree node which is then resolved # in self.get_and_resolve_doctree item = subnode.copy() entries.append(item) # do the inventory stuff self.note_toctree(docname, subnode) continue if not isinstance(subnode, nodes.section): continue title = subnode[0] # copy the contents of the section title, but without references # and unnecessary stuff visitor = SphinxContentsFilter(document) title.walkabout(visitor) nodetext = visitor.get_entry_text() if not numentries[0]: # for the very first toc entry, don't add an anchor # as it is the file's title anyway anchorname = '' else: anchorname = '#' + subnode['ids'][0] numentries[0] += 1 reference = nodes.reference('', '', refuri=docname, anchorname=anchorname, *nodetext) para = addnodes.compact_paragraph('', '', reference) item = nodes.list_item('', para) if maxdepth == 0 or depth < maxdepth: item += build_toc(subnode, depth+1) entries.append(item) if entries: return nodes.bullet_list('', *entries) return [] toc = build_toc(document) if toc: self.tocs[docname] = toc else: self.tocs[docname] = nodes.bullet_list('') self.toc_num_entries[docname] = numentries[0] def get_toc_for(self, docname): """Return a TOC nodetree -- for use on the same page only!""" toc = self.tocs[docname].deepcopy() for node in toc.traverse(nodes.reference): node['refuri'] = node['anchorname'] return toc # ------- # these are called from docutils directives and therefore use self.docname # def note_descref(self, fullname, desctype, line): if fullname in self.descrefs: self.warn(self.docname, 'duplicate canonical description name %s, ' % fullname + 'other instance in %s' % self.doc2path(self.descrefs[fullname][0]), line) self.descrefs[fullname] = (self.docname, desctype) def note_module(self, modname, synopsis, platform, deprecated): self.modules[modname] = (self.docname, synopsis, platform, deprecated) self.filemodules.setdefault(self.docname, []).append(modname) def note_progoption(self, optname, labelid): self.progoptions[self.currprogram, optname] = (self.docname, labelid) def note_reftarget(self, type, name, labelid): self.reftargets[type, name] = (self.docname, labelid) def note_versionchange(self, type, version, node, lineno): self.versionchanges.setdefault(version, []).append( (type, self.docname, lineno, self.currmodule, self.currdesc, node.astext())) def note_dependency(self, filename): basename = path.dirname(self.doc2path(self.docname, base=None)) # this will do the right thing when filename is absolute too filename = path.join(basename, filename) self.dependencies.setdefault(self.docname, set()).add(filename) # ------- # --------- RESOLVING REFERENCES AND TOCTREES ------------------------------ def get_doctree(self, docname): """Read the doctree for a file from the pickle and return it.""" doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree') f = open(doctree_filename, 'rb') try: doctree = pickle.load(f) finally: f.close() doctree.settings.env = self doctree.reporter = Reporter(self.doc2path(docname), 2, 4, stream=RedirStream(self._warnfunc)) return doctree def get_and_resolve_doctree(self, docname, builder, doctree=None, prune_toctrees=True): """Read the doctree from the pickle, resolve cross-references and toctrees and return it.""" if doctree is None: doctree = self.get_doctree(docname) # resolve all pending cross-references self.resolve_references(doctree, docname, builder) # now, resolve all toctree nodes for toctreenode in doctree.traverse(addnodes.toctree): result = self.resolve_toctree(docname, builder, toctreenode, prune=prune_toctrees) if result is None: toctreenode.replace_self([]) else: toctreenode.replace_self(result) return doctree def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0, titles_only=False): """ Resolve a *toctree* node into individual bullet lists with titles as items, returning None (if no containing titles are found) or a new node. If *prune* is True, the tree is pruned to *maxdepth*, or if that is 0, to the value of the *maxdepth* option on the *toctree* node. If *titles_only* is True, only toplevel document titles will be in the resulting tree. """ def _walk_depth(node, depth, maxdepth, titleoverrides): """Utility: Cut a TOC at a specified depth.""" for subnode in node.children[:]: if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)): subnode['classes'].append('toctree-l%d' % (depth-1)) _walk_depth(subnode, depth, maxdepth, titleoverrides) elif isinstance(subnode, nodes.bullet_list): if maxdepth > 0 and depth > maxdepth: subnode.parent.replace(subnode, []) else: _walk_depth(subnode, depth+1, maxdepth, titleoverrides) def _entries_from_toctree(toctreenode, separate=False): """Return TOC entries for a toctree node.""" includefiles = map(str, toctreenode['includefiles']) entries = [] for includefile in includefiles: try: toc = self.tocs[includefile].deepcopy() if not toc.children: # empty toc means: no titles will show up in the toctree self.warn(docname, 'toctree contains reference to document ' '%r that doesn\'t have a title: no link will be ' 'generated' % includefile) except KeyError: # this is raised if the included file does not exist self.warn(docname, 'toctree contains reference to nonexisting ' 'document %r' % includefile) else: # if titles_only is given, only keep the main title and # sub-toctrees if titles_only: # delete everything but the toplevel title(s) and toctrees for toplevel in toc: # nodes with length 1 don't have any children anyway if len(toplevel) > 1: subtoctrees = toplevel.traverse(addnodes.toctree) toplevel[1][:] = subtoctrees # resolve all sub-toctrees for toctreenode in toc.traverse(addnodes.toctree): i = toctreenode.parent.index(toctreenode) + 1 for item in _entries_from_toctree(toctreenode): toctreenode.parent.insert(i, item) i += 1 toctreenode.parent.remove(toctreenode) if separate: entries.append(toc) else: entries.extend(toc.children) return entries maxdepth = maxdepth or toctree.get('maxdepth', -1) titleoverrides = toctree.get('includetitles', {}) tocentries = _entries_from_toctree(toctree, separate=True) if not tocentries: return None newnode = addnodes.compact_paragraph('', '', *tocentries) newnode['toctree'] = True # prune the tree to maxdepth and replace titles, also set level classes _walk_depth(newnode, 1, prune and maxdepth or 0, titleoverrides) # replace titles, if needed, and set the target paths in the # toctrees (they are not known at TOC generation time) for refnode in newnode.traverse(nodes.reference): refnode['refuri'] = builder.get_relative_uri( docname, refnode['refuri']) + refnode['anchorname'] if titleoverrides and not refnode['anchorname'] \ and refnode['refuri'] in titleoverrides: newtitle = titleoverrides[refnode['refuri']] refnode.children = [nodes.Text(newtitle)] return newnode descroles = frozenset(('data', 'exc', 'func', 'class', 'const', 'attr', 'obj', 'meth', 'cfunc', 'cmember', 'cdata', 'ctype', 'cmacro')) def resolve_references(self, doctree, fromdocname, builder): reftarget_roles = set(('token', 'term', 'citation')) # add all custom xref types too reftarget_roles.update(i[0] for i in additional_xref_types.values()) for node in doctree.traverse(addnodes.pending_xref): contnode = node[0].deepcopy() newnode = None typ = node['reftype'] target = node['reftarget'] try: if typ == 'ref': if node['refcaption']: # reference to anonymous label; the reference uses the supplied # link caption docname, labelid = self.anonlabels.get(target, ('','')) sectname = node.astext() if not docname: newnode = doctree.reporter.system_message( 2, 'undefined label: %s' % target) else: # reference to the named label; the final node will contain the # section name after the label docname, labelid, sectname = self.labels.get(target, ('','','')) if not docname: newnode = doctree.reporter.system_message( 2, 'undefined label: %s -- if you don\'t ' % target + 'give a link caption the label must precede a section ' 'header.') if docname: newnode = nodes.reference('', '') innernode = nodes.emphasis(sectname, sectname) if docname == fromdocname: newnode['refid'] = labelid else: # set more info in contnode in case the get_relative_uri call # raises NoUri, the builder will then have to resolve these contnode = addnodes.pending_xref('') contnode['refdocname'] = docname contnode['refsectname'] = sectname newnode['refuri'] = builder.get_relative_uri( fromdocname, docname) if labelid: newnode['refuri'] += '#' + labelid newnode.append(innernode) elif typ == 'keyword': # keywords are referenced by named labels docname, labelid, _ = self.labels.get(target, ('','','')) if not docname: #self.warn(fromdocname, 'unknown keyword: %s' % target) newnode = contnode else: newnode = nodes.reference('', '') if docname == fromdocname: newnode['refid'] = labelid else: newnode['refuri'] = builder.get_relative_uri( fromdocname, docname) + '#' + labelid newnode.append(contnode) elif typ == 'option': progname = node['refprogram'] docname, labelid = self.progoptions.get((progname, target), ('', '')) if not docname: newnode = contnode else: newnode = nodes.reference('', '') if docname == fromdocname: newnode['refid'] = labelid else: newnode['refuri'] = builder.get_relative_uri( fromdocname, docname) + '#' + labelid newnode.append(contnode) elif typ in reftarget_roles: docname, labelid = self.reftargets.get((typ, target), ('', '')) if not docname: if typ == 'term': self.warn(fromdocname, 'term not in glossary: %s' % target, node.line) elif typ == 'citation': self.warn(fromdocname, 'citation not found: %s' % target, node.line) newnode = contnode else: newnode = nodes.reference('', '') if docname == fromdocname: newnode['refid'] = labelid else: newnode['refuri'] = builder.get_relative_uri( fromdocname, docname, typ) + '#' + labelid newnode.append(contnode) elif typ == 'mod': docname, synopsis, platform, deprecated = \ self.modules.get(target, ('','','', '')) if not docname: newnode = builder.app.emit_firstresult('missing-reference', self, node, contnode) if not newnode: newnode = contnode elif docname == fromdocname: # don't link to self newnode = contnode else: newnode = nodes.reference('', '') newnode['refuri'] = builder.get_relative_uri( fromdocname, docname) + '#module-' + target newnode['reftitle'] = '%s%s%s' % ( (platform and '(%s) ' % platform), synopsis, (deprecated and ' (deprecated)' or '')) newnode.append(contnode) elif typ in self.descroles: # "descrefs" modname = node['modname'] clsname = node['classname'] searchorder = node.hasattr('refspecific') and 1 or 0 name, desc = self.find_desc(modname, clsname, target, typ, searchorder) if not desc: newnode = builder.app.emit_firstresult('missing-reference', self, node, contnode) if not newnode: newnode = contnode else: newnode = nodes.reference('', '') if desc[0] == fromdocname: newnode['refid'] = name else: newnode['refuri'] = ( builder.get_relative_uri(fromdocname, desc[0]) + '#' + name) newnode['reftitle'] = name newnode.append(contnode) else: raise RuntimeError('unknown xfileref node encountered: %s' % node) except NoUri: newnode = contnode if newnode: node.replace_self(newnode) # allow custom references to be resolved builder.app.emit('doctree-resolved', doctree, fromdocname) def create_index(self, builder, _fixre=re.compile(r'(.*) ([(][^()]*[)])')): """Create the real index from the collected index entries.""" new = {} def add_entry(word, subword, dic=new): entry = dic.get(word) if not entry: dic[word] = entry = [[], {}] if subword: add_entry(subword, '', dic=entry[1]) else: try: entry[0].append(builder.get_relative_uri('genindex', fn) + '#' + tid) except NoUri: pass for fn, entries in self.indexentries.iteritems(): # new entry types must be listed in directives/other.py! for type, string, tid, alias in entries: if type == 'single': try: entry, subentry = string.split(';', 1) except ValueError: entry, subentry = string, '' if not entry: self.warn(fn, 'invalid index entry %r' % string) continue add_entry(entry.strip(), subentry.strip()) elif type == 'pair': try: first, second = map(lambda x: x.strip(), string.split(';', 1)) if not first or not second: raise ValueError except ValueError: self.warn(fn, 'invalid pair index entry %r' % string) continue add_entry(first, second) add_entry(second, first) elif type == 'triple': try: first, second, third = map(lambda x: x.strip(), string.split(';', 2)) if not first or not second or not third: raise ValueError except ValueError: self.warn(fn, 'invalid triple index entry %r' % string) continue add_entry(first, second+' '+third) add_entry(second, third+', '+first) add_entry(third, first+' '+second) else: self.warn(fn, 'unknown index entry type %r' % type) newlist = new.items() newlist.sort(key=lambda t: t[0].lower()) # fixup entries: transform # func() (in module foo) # func() (in module bar) # into # func() # (in module foo) # (in module bar) oldkey = '' oldsubitems = None i = 0 while i < len(newlist): key, (targets, subitems) = newlist[i] # cannot move if it hassubitems; structure gets too complex if not subitems: m = _fixre.match(key) if m: if oldkey == m.group(1): # prefixes match: add entry as subitem of the previous entry oldsubitems.setdefault(m.group(2), [[], {}])[0].extend(targets) del newlist[i] continue oldkey = m.group(1) else: oldkey = key oldsubitems = subitems i += 1 # group the entries by letter def keyfunc((k, v), ltrs=uppercase+'_'): # hack: mutate the subitems dicts to a list in the keyfunc v[1] = sorted((si, se) for (si, (se, void)) in v[1].iteritems()) # now calculate the key letter = k[0].upper() if letter in ltrs: return letter else: # get all other symbols under one heading return 'Symbols' return [(key, list(group)) for (key, group) in groupby(newlist, keyfunc)] def collect_relations(self): relations = {} getinc = self.toctree_includes.get def collect(parents, docname, previous, next): includes = getinc(docname) # previous if not previous: # if no previous sibling, go to parent previous = parents[0][0] else: # else, go to previous sibling, or if it has children, to # the last of its children, or if that has children, to the # last of those, and so forth while 1: previncs = getinc(previous) if previncs: previous = previncs[-1] else: break # next if includes: # if it has children, go to first of them next = includes[0] elif next: # else, if next sibling, go to it pass else: # else, go to the next sibling of the parent, if present, # else the grandparent's sibling, if present, and so forth for parname, parindex in parents: parincs = getinc(parname) if parincs and parindex + 1 < len(parincs): next = parincs[parindex+1] break # else it will stay None # same for children if includes: for subindex, args in enumerate(izip(includes, [None] + includes, includes[1:] + [None])): collect([(docname, subindex)] + parents, *args) relations[docname] = [parents[0][0], previous, next] collect([(None, 0)], self.config.master_doc, None, None) return relations def check_consistency(self): """Do consistency checks.""" for docname in sorted(self.all_docs): if docname not in self.files_to_rebuild: if docname == self.config.master_doc: # the master file is not included anywhere ;) continue self.warn(docname, 'document isn\'t included in any toctree') # --------- QUERYING ------------------------------------------------------- def find_desc(self, modname, classname, name, type, searchorder=0): """Find a description node matching "name", perhaps using the given module and/or classname.""" # skip parens if name[-2:] == '()': name = name[:-2] if not name: return None, None # don't add module and class names for C things if type[0] == 'c' and type not in ('class', 'const'): # skip trailing star and whitespace name = name.rstrip(' *') if name in self.descrefs and self.descrefs[name][1][0] == 'c': return name, self.descrefs[name] return None, None newname = None if searchorder == 1: if modname and classname and \ modname + '.' + classname + '.' + name in self.descrefs: newname = modname + '.' + classname + '.' + name elif modname and modname + '.' + name in self.descrefs: newname = modname + '.' + name elif name in self.descrefs: newname = name else: if name in self.descrefs: newname = name elif modname and modname + '.' + name in self.descrefs: newname = modname + '.' + name elif modname and classname and \ modname + '.' + classname + '.' + name in self.descrefs: newname = modname + '.' + classname + '.' + name # special case: builtin exceptions have module "exceptions" set elif type == 'exc' and '.' not in name and \ 'exceptions.' + name in self.descrefs: newname = 'exceptions.' + name # special case: object methods elif type in ('func', 'meth') and '.' not in name and \ 'object.' + name in self.descrefs: newname = 'object.' + name if newname is None: return None, None return newname, self.descrefs[newname] def find_keyword(self, keyword, avoid_fuzzy=False, cutoff=0.6, n=20): """ Find keyword matches for a keyword. If there's an exact match, just return it, else return a list of fuzzy matches if avoid_fuzzy isn't True. Keywords searched are: first modules, then descrefs. Returns: None if nothing found (type, docname, anchorname) if exact match found list of (quality, type, docname, anchorname, description) if fuzzy """ if keyword in self.modules: docname, title, system, deprecated = self.modules[keyword] return 'module', docname, 'module-' + keyword if keyword in self.descrefs: docname, ref_type = self.descrefs[keyword] return ref_type, docname, keyword # special cases if '.' not in keyword: # exceptions are documented in the exceptions module if 'exceptions.'+keyword in self.descrefs: docname, ref_type = self.descrefs['exceptions.'+keyword] return ref_type, docname, 'exceptions.'+keyword # special methods are documented as object methods if 'object.'+keyword in self.descrefs: docname, ref_type = self.descrefs['object.'+keyword] return ref_type, docname, 'object.'+keyword if avoid_fuzzy: return # find fuzzy matches s = difflib.SequenceMatcher() s.set_seq2(keyword.lower()) def possibilities(): for title, (fn, desc, _, _) in self.modules.iteritems(): yield ('module', fn, 'module-'+title, desc) for title, (fn, desctype) in self.descrefs.iteritems(): yield (desctype, fn, title, '') def dotsearch(string): parts = string.lower().split('.') for idx in xrange(0, len(parts)): yield '.'.join(parts[idx:]) result = [] for type, docname, title, desc in possibilities(): best_res = 0 for part in dotsearch(title): s.set_seq1(part) if s.real_quick_ratio() >= cutoff and \ s.quick_ratio() >= cutoff and \ s.ratio() >= cutoff and \ s.ratio() > best_res: best_res = s.ratio() if best_res: result.append((best_res, type, docname, title, desc)) return heapq.nlargest(n, result)