/Doc/tools/sphinxext/pyspecific.py

Relevant Search: With Applications for Solr and Elasticsearch

For more in depth reading about search, ranking and generally everything you could ever want to know about how lucene, elasticsearch or solr work under the hood I highly suggest this book. Easily one of the most interesting technical books I have read in a long time. If you are tasked with solving search relevance problems even if not in Solr or Elasticsearch it should be your first reference. Amazon Affiliate Link

  1# -*- coding: utf-8 -*-
  2"""
  3    pyspecific.py
  4    ~~~~~~~~~~~~~
  5
  6    Sphinx extension with Python doc-specific markup.
  7
  8    :copyright: 2008, 2009 by Georg Brandl.
  9    :license: Python license.
 10"""
 11
 12ISSUE_URI = 'http://bugs.python.org/issue%s'
 13
 14from docutils import nodes, utils
 15
 16# monkey-patch reST parser to disable alphabetic and roman enumerated lists
 17from docutils.parsers.rst.states import Body
 18Body.enum.converters['loweralpha'] = \
 19    Body.enum.converters['upperalpha'] = \
 20    Body.enum.converters['lowerroman'] = \
 21    Body.enum.converters['upperroman'] = lambda x: None
 22
 23
 24def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
 25    issue = utils.unescape(text)
 26    text = 'issue ' + issue
 27    refnode = nodes.reference(text, text, refuri=ISSUE_URI % issue)
 28    return [refnode], []
 29
 30
 31# Support for building "topic help" for pydoc
 32
 33pydoc_topic_labels = [
 34    'assert', 'assignment', 'atom-identifiers', 'atom-literals',
 35    'attribute-access', 'attribute-references', 'augassign', 'binary',
 36    'bitwise', 'bltin-code-objects', 'bltin-ellipsis-object',
 37    'bltin-file-objects', 'bltin-null-object', 'bltin-type-objects', 'booleans',
 38    'break', 'callable-types', 'calls', 'class', 'coercion-rules',
 39    'comparisons', 'compound', 'context-managers', 'continue', 'conversions',
 40    'customization', 'debugger', 'del', 'dict', 'dynamic-features', 'else',
 41    'exceptions', 'exec', 'execmodel', 'exprlists', 'floating', 'for',
 42    'formatstrings', 'function', 'global', 'id-classes', 'identifiers', 'if',
 43    'imaginary', 'import', 'in', 'integers', 'lambda', 'lists', 'naming',
 44    'numbers', 'numeric-types', 'objects', 'operator-summary', 'pass', 'power',
 45    'print', 'raise', 'return', 'sequence-methods', 'sequence-types',
 46    'shifting', 'slicings', 'specialattrs', 'specialnames',
 47    'string-conversions', 'string-methods', 'strings', 'subscriptions', 'truth',
 48    'try', 'types', 'typesfunctions', 'typesmapping', 'typesmethods',
 49    'typesmodules', 'typesseq', 'typesseq-mutable', 'unary', 'while', 'with',
 50    'yield'
 51]
 52
 53from os import path
 54from time import asctime
 55from pprint import pformat
 56from docutils.io import StringOutput
 57from docutils.utils import new_document
 58
 59try:
 60    from sphinx.builders import Builder
 61except ImportError:
 62    # using Sphinx < 0.6, which has a different package layout
 63    from sphinx.builder import Builder
 64    # monkey-patch toctree directive to accept (and ignore) the :numbered: flag
 65    from sphinx.directives.other import toctree_directive
 66    toctree_directive.options['numbered'] = toctree_directive.options['glob']
 67
 68try:
 69    from sphinx.writers.text import TextWriter
 70except ImportError:
 71    from sphinx.textwriter import TextWriter
 72
 73
 74class PydocTopicsBuilder(Builder):
 75    name = 'pydoc-topics'
 76
 77    def init(self):
 78        self.topics = {}
 79
 80    def get_outdated_docs(self):
 81        return 'all pydoc topics'
 82
 83    def get_target_uri(self, docname, typ=None):
 84        return ''  # no URIs
 85
 86    def write(self, *ignored):
 87        writer = TextWriter(self)
 88        for label in self.status_iterator(pydoc_topic_labels, 'building topics... '):
 89            if label not in self.env.labels:
 90                self.warn('label %r not in documentation' % label)
 91                continue
 92            docname, labelid, sectname = self.env.labels[label]
 93            doctree = self.env.get_and_resolve_doctree(docname, self)
 94            document = new_document('<section node>')
 95            document.append(doctree.ids[labelid])
 96            destination = StringOutput(encoding='utf-8')
 97            writer.write(document, destination)
 98            self.topics[label] = writer.output
 99
100    def finish(self):
101        f = open(path.join(self.outdir, 'pydoc_topics.py'), 'w')
102        try:
103            f.write('# Autogenerated by Sphinx on %s\n' % asctime())
104            f.write('topics = ' + pformat(self.topics) + '\n')
105        finally:
106            f.close()
107
108# Support for checking for suspicious markup
109
110import suspicious
111
112# Support for documenting Opcodes
113
114import re
115from sphinx import addnodes
116
117opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)\s*\((.*)\)')
118
119def parse_opcode_signature(env, sig, signode):
120    """Transform an opcode signature into RST nodes."""
121    m = opcode_sig_re.match(sig)
122    if m is None:
123        raise ValueError
124    opname, arglist = m.groups()
125    signode += addnodes.desc_name(opname, opname)
126    paramlist = addnodes.desc_parameterlist()
127    signode += paramlist
128    paramlist += addnodes.desc_parameter(arglist, arglist)
129    return opname.strip()
130
131
132def setup(app):
133    app.add_role('issue', issue_role)
134    app.add_builder(PydocTopicsBuilder)
135    app.add_builder(suspicious.CheckSuspiciousMarkupBuilder)
136    app.add_description_unit('opcode', 'opcode', '%s (opcode)',
137                             parse_opcode_signature)