/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 LinkPython | 137 lines | 96 code | 24 blank | 17 comment | 3 complexity | 7e6212487d26dd98dd04e325731b1d0c MD5 | raw file
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)