""" Add links to module code in Python object descriptions. :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ import posixpath import traceback import warnings from os import path from typing import Any, Dict, Generator, Iterable, Optional, Set, Tuple, cast from docutils import nodes from docutils.nodes import Element, Node import sphinx from sphinx import addnodes from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.deprecation import RemovedInSphinx50Warning from sphinx.environment import BuildEnvironment from sphinx.locale import _, __ from sphinx.pycode import ModuleAnalyzer from sphinx.transforms.post_transforms import SphinxPostTransform from sphinx.util import get_full_modname, logging, status_iterator from sphinx.util.nodes import make_refnode logger = logging.getLogger(__name__) OUTPUT_DIRNAME = '_modules' class viewcode_anchor(Element): """Node for viewcode anchors. This node will be processed in the resolving phase. For viewcode supported builders, they will be all converted to the anchors. For not supported builders, they will be removed. """ def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str]: try: return get_full_modname(modname, attribute) except AttributeError: # sphinx.ext.viewcode can't follow class instance attribute # then AttributeError logging output only verbose mode. logger.verbose('Didn\'t find %s in %s', attribute, modname) return None except Exception as e: # sphinx.ext.viewcode follow python domain directives. # because of that, if there are no real modules exists that specified # by py:function or other directives, viewcode emits a lot of warnings. # It should be displayed only verbose mode. logger.verbose(traceback.format_exc().rstrip()) logger.verbose('viewcode can\'t import %s, failed with error "%s"', modname, e) return None def is_supported_builder(builder: Builder) -> bool: if builder.format != 'html': return False elif builder.name == 'singlehtml': return False elif builder.name.startswith('epub') and not builder.config.viewcode_enable_epub: return False else: return True def doctree_read(app: Sphinx, doctree: Node) -> None: env = app.builder.env if not hasattr(env, '_viewcode_modules'): env._viewcode_modules = {} # type: ignore def has_tag(modname: str, fullname: str, docname: str, refname: str) -> bool: entry = env._viewcode_modules.get(modname, None) # type: ignore if entry is False: return False code_tags = app.emit_firstresult('viewcode-find-source', modname) if code_tags is None: try: analyzer = ModuleAnalyzer.for_module(modname) analyzer.find_tags() except Exception: env._viewcode_modules[modname] = False # type: ignore return False code = analyzer.code tags = analyzer.tags else: code, tags = code_tags if entry is None or entry[0] != code: entry = code, tags, {}, refname env._viewcode_modules[modname] = entry # type: ignore _, tags, used, _ = entry if fullname in tags: used[fullname] = docname return True return False for objnode in list(doctree.findall(addnodes.desc)): if objnode.get('domain') != 'py': continue names: Set[str] = set() for signode in objnode: if not isinstance(signode, addnodes.desc_signature): continue modname = signode.get('module') fullname = signode.get('fullname') refname = modname if env.config.viewcode_follow_imported_members: new_modname = app.emit_firstresult( 'viewcode-follow-imported', modname, fullname, ) if not new_modname: new_modname = _get_full_modname(app, modname, fullname) modname = new_modname if not modname: continue fullname = signode.get('fullname') if not has_tag(modname, fullname, env.docname, refname): continue if fullname in names: # only one link per name, please continue names.add(fullname) pagename = posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/')) signode += viewcode_anchor(reftarget=pagename, refid=fullname, refdoc=env.docname) def env_merge_info(app: Sphinx, env: BuildEnvironment, docnames: Iterable[str], other: BuildEnvironment) -> None: if not hasattr(other, '_viewcode_modules'): return # create a _viewcode_modules dict on the main environment if not hasattr(env, '_viewcode_modules'): env._viewcode_modules = {} # type: ignore # now merge in the information from the subprocess for modname, entry in other._viewcode_modules.items(): # type: ignore if modname not in env._viewcode_modules: # type: ignore env._viewcode_modules[modname] = entry # type: ignore else: if env._viewcode_modules[modname]: # type: ignore used = env._viewcode_modules[modname][2] # type: ignore for fullname, docname in entry[2].items(): if fullname not in used: used[fullname] = docname def env_purge_doc(app: Sphinx, env: BuildEnvironment, docname: str) -> None: modules = getattr(env, '_viewcode_modules', {}) for modname, entry in list(modules.items()): if entry is False: continue code, tags, used, refname = entry for fullname in list(used): if used[fullname] == docname: used.pop(fullname) if len(used) == 0: modules.pop(modname) class ViewcodeAnchorTransform(SphinxPostTransform): """Convert or remove viewcode_anchor nodes depends on builder.""" default_priority = 100 def run(self, **kwargs: Any) -> None: if is_supported_builder(self.app.builder): self.convert_viewcode_anchors() else: self.remove_viewcode_anchors() def convert_viewcode_anchors(self) -> None: for node in self.document.findall(viewcode_anchor): anchor = nodes.inline('', _('[source]'), classes=['viewcode-link']) refnode = make_refnode(self.app.builder, node['refdoc'], node['reftarget'], node['refid'], anchor) node.replace_self(refnode) def remove_viewcode_anchors(self) -> None: for node in list(self.document.findall(viewcode_anchor)): node.parent.remove(node) def missing_reference(app: Sphinx, env: BuildEnvironment, node: Element, contnode: Node ) -> Optional[Node]: # resolve our "viewcode" reference nodes -- they need special treatment if node['reftype'] == 'viewcode': warnings.warn('viewcode extension is no longer use pending_xref node. ' 'Please update your extension.', RemovedInSphinx50Warning) return make_refnode(app.builder, node['refdoc'], node['reftarget'], node['refid'], contnode) return None def get_module_filename(app: Sphinx, modname: str) -> Optional[str]: """Get module filename for *modname*.""" source_info = app.emit_firstresult('viewcode-find-source', modname) if source_info: return None else: try: filename, source = ModuleAnalyzer.get_module_source(modname) return filename except Exception: return None def should_generate_module_page(app: Sphinx, modname: str) -> bool: """Check generation of module page is needed.""" module_filename = get_module_filename(app, modname) if module_filename is None: # Always (re-)generate module page when module filename is not found. return True builder = cast(StandaloneHTMLBuilder, app.builder) basename = modname.replace('.', '/') + builder.out_suffix page_filename = path.join(app.outdir, '_modules/', basename) try: if path.getmtime(module_filename) <= path.getmtime(page_filename): # generation is not needed if the HTML page is newer than module file. return False except IOError: pass return True def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], None, None]: env = app.builder.env if not hasattr(env, '_viewcode_modules'): return if not is_supported_builder(app.builder): return highlighter = app.builder.highlighter # type: ignore urito = app.builder.get_relative_uri modnames = set(env._viewcode_modules) # type: ignore for modname, entry in status_iterator( sorted(env._viewcode_modules.items()), # type: ignore __('highlighting module code... '), "blue", len(env._viewcode_modules), # type: ignore app.verbosity, lambda x: x[0]): if not entry: continue if not should_generate_module_page(app, modname): continue code, tags, used, refname = entry # construct a page name for the highlighted source pagename = posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/')) # highlight the source using the builder's highlighter if env.config.highlight_language in ('python3', 'default', 'none'): lexer = env.config.highlight_language else: lexer = 'python' highlighted = highlighter.highlight_block(code, lexer, linenos=False) # split the code into lines lines = highlighted.splitlines() # split off wrap markup from the first line of the actual code before, after = lines[0].split('
') lines[0:1] = [before + '', after] # nothing to do for the last line; it always starts withanyway # now that we have code lines (starting at index 1), insert anchors for # the collected tags (HACK: this only works if the tag boundaries are # properly nested!) maxindex = len(lines) - 1 for name, docname in used.items(): type, start, end = tags[name] backlink = urito(pagename, docname) + '#' + refname + '.' + name lines[start] = ( '%s' % (name, backlink, _('[docs]')) + lines[start]) lines[min(end, maxindex)] += '' # try to find parents (for submodules) parents = [] parent = modname while '.' in parent: parent = parent.rsplit('.', 1)[0] if parent in modnames: parents.append({ 'link': urito(pagename, posixpath.join(OUTPUT_DIRNAME, parent.replace('.', '/'))), 'title': parent}) parents.append({'link': urito(pagename, posixpath.join(OUTPUT_DIRNAME, 'index')), 'title': _('Module code')}) parents.reverse() # putting it all together context = { 'parents': parents, 'title': modname, 'body': (_('Source code for %s
') % modname + '\n'.join(lines)), } yield (pagename, context, 'page.html') if not modnames: return html = ['\n'] # the stack logic is needed for using nested lists for submodules stack = [''] for modname in sorted(modnames): if modname.startswith(stack[-1]): stack.append(modname + '.') html.append('