← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/tools/sphinxext/pyspecific.py

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/tools/sphinxext/pyspecific.py
 
1
# -*- coding: utf-8 -*-
 
2
"""
 
3
    pyspecific.py
 
4
    ~~~~~~~~~~~~~
 
5
 
 
6
    Sphinx extension with Python doc-specific markup.
 
7
 
 
8
    :copyright: 2008 by Georg Brandl.
 
9
    :license: Python license.
 
10
"""
 
11
 
 
12
ISSUE_URI = 'http://bugs.python.org/issue%s'
 
13
 
 
14
from docutils import nodes, utils
 
15
 
 
16
# monkey-patch reST parser to disable alphabetic and roman enumerated lists
 
17
from docutils.parsers.rst.states import Body
 
18
Body.enum.converters['loweralpha'] = \
 
19
    Body.enum.converters['upperalpha'] = \
 
20
    Body.enum.converters['lowerroman'] = \
 
21
    Body.enum.converters['upperroman'] = lambda x: None
 
22
 
 
23
 
 
24
def 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
 
 
33
pydoc_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', 'comparisons', 'compound',
 
39
    'context-managers', 'continue', 'conversions', 'customization', 'debugger',
 
40
    'del', 'dict', 'dynamic-features', 'else', 'exceptions', 'execmodel',
 
41
    'exprlists', 'floating', 'for', 'formatstrings', 'function', 'global',
 
42
    'id-classes', 'identifiers', 'if', 'imaginary', 'import', 'in', 'integers',
 
43
    'lambda', 'lists', 'naming', 'numbers', 'numeric-types', 'objects',
 
44
    'operator-summary', 'pass', 'power', 'raise', 'return', 'sequence-types',
 
45
    'shifting', 'slicings', 'specialattrs', 'specialnames', 'string-methods',
 
46
    'strings', 'subscriptions', 'truth', 'try', 'types', 'typesfunctions',
 
47
    'typesmapping', 'typesmethods', 'typesmodules', 'typesseq',
 
48
    'typesseq-mutable', 'unary', 'while', 'with', 'yield'
 
49
]
 
50
 
 
51
from os import path
 
52
from time import asctime
 
53
from pprint import pformat
 
54
from docutils.io import StringOutput
 
55
from docutils.utils import new_document
 
56
 
 
57
from sphinx.builders import Builder
 
58
from sphinx.writers.text import TextWriter
 
59
 
 
60
 
 
61
class PydocTopicsBuilder(Builder):
 
62
    name = 'pydoc-topics'
 
63
 
 
64
    def init(self):
 
65
        self.topics = {}
 
66
 
 
67
    def get_outdated_docs(self):
 
68
        return 'all pydoc topics'
 
69
 
 
70
    def get_target_uri(self, docname, typ=None):
 
71
        return ''  # no URIs
 
72
 
 
73
    def write(self, *ignored):
 
74
        writer = TextWriter(self)
 
75
        for label in self.status_iterator(pydoc_topic_labels, 'building topics... '):
 
76
            if label not in self.env.labels:
 
77
                self.warn('label %r not in documentation' % label)
 
78
                continue
 
79
            docname, labelid, sectname = self.env.labels[label]
 
80
            doctree = self.env.get_and_resolve_doctree(docname, self)
 
81
            document = new_document('<section node>')
 
82
            document.append(doctree.ids[labelid])
 
83
            destination = StringOutput(encoding='utf-8')
 
84
            writer.write(document, destination)
 
85
            self.topics[label] = str(writer.output)
 
86
 
 
87
    def finish(self):
 
88
        f = open(path.join(self.outdir, 'pydoc_topics.py'), 'w')
 
89
        try:
 
90
            f.write('# Autogenerated by Sphinx on %s\n' % asctime())
 
91
            f.write('topics = ' + pformat(self.topics) + '\n')
 
92
        finally:
 
93
            f.close()
 
94
 
 
95
# Support for checking for suspicious markup
 
96
 
 
97
import suspicious
 
98
 
 
99
# Support for documenting Opcodes
 
100
 
 
101
import re
 
102
from sphinx import addnodes
 
103
 
 
104
opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)\s*\((.*)\)')
 
105
 
 
106
def parse_opcode_signature(env, sig, signode):
 
107
    """Transform an opcode signature into RST nodes."""
 
108
    m = opcode_sig_re.match(sig)
 
109
    if m is None:
 
110
        raise ValueError
 
111
    opname, arglist = m.groups()
 
112
    signode += addnodes.desc_name(opname, opname)
 
113
    paramlist = addnodes.desc_parameterlist()
 
114
    signode += paramlist
 
115
    paramlist += addnodes.desc_parameter(arglist, arglist)
 
116
    return opname.strip()
 
117
 
 
118
 
 
119
def setup(app):
 
120
    app.add_role('issue', issue_role)
 
121
    app.add_builder(PydocTopicsBuilder)
 
122
    app.add_builder(suspicious.CheckSuspiciousMarkupBuilder)
 
123
    app.add_description_unit('opcode', 'opcode', '%s (opcode)',
 
124
                             parse_opcode_signature)
 
125
    app.add_description_unit('2to3fixer', '2to3fixer', '%s (2to3 fixer)')