diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Makefile | 5 | ||||
| -rw-r--r-- | Doc/README.txt | 5 | ||||
| -rw-r--r-- | Doc/tools/sphinxext/pyspecific.py | 66 |
3 files changed, 76 insertions, 0 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index 9795315..68da4f7 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -98,6 +98,11 @@ doctest: build @echo "Testing of doctests in the sources finished, look at the " \ "results in build/doctest/output.txt" +pydoc-topics: BUILDER = pydoc-topics +pydoc-topics: build + @echo "Building finished; now copy build/pydoc-topics/pydoc_topics.py " \ + "into the Lib/ directory" + clean: -rm -rf build/* -rm -rf tools/sphinx diff --git a/Doc/README.txt b/Doc/README.txt index aea9b20..8ae3579 100644 --- a/Doc/README.txt +++ b/Doc/README.txt @@ -64,6 +64,11 @@ Available make targets are: * "coverage", which builds a coverage overview for standard library modules and C API. + * "pydoc-topics", which builds a Python module containing a dictionary + with plain text documentation for the labels defined in + `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic + and keyword help. + A "make update" updates the Subversion checkouts in `tools/`. diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py index f7c0daa..568a6a1 100644 --- a/Doc/tools/sphinxext/pyspecific.py +++ b/Doc/tools/sphinxext/pyspecific.py @@ -20,5 +20,71 @@ def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): return [refnode], [] +# Support for building "topic help" for pydoc + +pydoc_topic_labels = [ + 'assert', 'assignment', 'atom-identifiers', 'atom-literals', + 'attribute-access', 'attribute-references', 'augassign', 'binary', + 'bitwise', 'bltin-code-objects', 'bltin-ellipsis-object', + 'bltin-file-objects', 'bltin-null-object', 'bltin-type-objects', 'booleans', + 'break', 'callable-types', 'calls', 'class', 'coercion-rules', + 'comparisons', 'compound', 'context-managers', 'continue', 'conversions', + 'customization', 'debugger', 'del', 'dict', 'dynamic-features', 'else', + 'exceptions', 'exec', 'execmodel', 'exprlists', 'floating', 'for', + 'formatstrings', 'function', 'global', 'id-classes', 'identifiers', 'if', + 'imaginary', 'import', 'in', 'integers', 'lambda', 'lists', 'naming', + 'numbers', 'numeric-types', 'objects', 'operator-summary', 'pass', 'power', + 'print', 'raise', 'return', 'sequence-methods', 'sequence-types', + 'shifting', 'slicings', 'specialattrs', 'specialnames', + 'string-conversions', 'string-methods', 'strings', 'subscriptions', 'truth', + 'try', 'types', 'typesfunctions', 'typesmapping', 'typesmethods', + 'typesmodules', 'typesseq', 'typesseq-mutable', 'unary', 'while', 'with', + 'yield' +] + +from os import path +from time import asctime +from pprint import pformat +from docutils.io import StringOutput +from docutils.utils import new_document +from sphinx.builder import Builder +from sphinx.textwriter import TextWriter + +class PydocTopicsBuilder(Builder): + name = 'pydoc-topics' + + def init(self): + self.topics = {} + + def get_outdated_docs(self): + return 'all pydoc topics' + + def get_target_uri(self, docname, typ=None): + return '' # no URIs + + def write(self, *ignored): + writer = TextWriter(self) + for label in self.status_iterator(pydoc_topic_labels, 'building topics... '): + if label not in self.env.labels: + self.warn('label %r not in documentation' % label) + continue + docname, labelid, sectname = self.env.labels[label] + doctree = self.env.get_and_resolve_doctree(docname, self) + document = new_document('<section node>') + document.append(doctree.ids[labelid]) + destination = StringOutput(encoding='utf-8') + writer.write(document, destination) + self.topics[label] = writer.output + + def finish(self): + f = open(path.join(self.outdir, 'pydoc_topics.py'), 'w') + try: + f.write('# Autogenerated by Sphinx on %s\n' % asctime()) + f.write('topics = ' + pformat(self.topics) + '\n') + finally: + f.close() + + def setup(app): app.add_role('issue', issue_role) + app.add_builder(PydocTopicsBuilder) |