epydoc.markup.restructuredtext

1 # 2 # rst.py: ReStructuredText docstring parsing 3 # Edward Loper 4 # 5 # Created [06/28/03 02:52 AM] 6 # $Id: restructuredtext.py 1661 2007-11-07 12:59:34Z dvarrazzo $ 7 # 8 9 """ 10 Epydoc parser for ReStructuredText strings. ReStructuredText is the 11 standard markup language used by the Docutils project. 12 L{parse_docstring()} provides the primary interface to this module; it 13 returns a L{ParsedRstDocstring}, which supports all of the methods 14 defined by L{ParsedDocstring}. 15 16 L{ParsedRstDocstring} is basically just a L{ParsedDocstring} wrapper 17 for the C{docutils.nodes.document} class. 18 19 Creating C{ParsedRstDocstring}s 20 =============================== 21 22 C{ParsedRstDocstring}s are created by the C{parse_document} function, 23 using the C{docutils.core.publish_string()} method, with the following 24 helpers: 25 26 - An L{_EpydocReader} is used to capture all error messages as it 27 parses the docstring. 28 - A L{_DocumentPseudoWriter} is used to extract the document itself, 29 without actually writing any output. The document is saved for 30 further processing. The settings for the writer are copied from 31 C{docutils.writers.html4css1.Writer}, since those settings will 32 be used when we actually write the docstring to html. 33 34 Using C{ParsedRstDocstring}s 35 ============================ 36 37 C{ParsedRstDocstring}s support all of the methods defined by 38 C{ParsedDocstring}; but only the following four methods have 39 non-default behavior: 40 41 - L{to_html()<ParsedRstDocstring.to_html>} uses an 42 L{_EpydocHTMLTranslator} to translate the C{ParsedRstDocstring}'s 43 document into an HTML segment. 44 - L{split_fields()<ParsedRstDocstring.split_fields>} uses a 45 L{_SplitFieldsTranslator} to divide the C{ParsedRstDocstring}'s 46 document into its main body and its fields. Special handling 47 is done to account for consolidated fields. 48 - L{summary()<ParsedRstDocstring.summary>} uses a 49 L{_SummaryExtractor} to extract the first sentence from 50 the C{ParsedRstDocstring}'s document. 51 - L{to_plaintext()<ParsedRstDocstring.to_plaintext>} uses 52 C{document.astext()} to convert the C{ParsedRstDocstring}'s 53 document to plaintext. 54 55 @todo: Add ParsedRstDocstring.to_latex() 56 @var CONSOLIDATED_FIELDS: A dictionary encoding the set of 57 'consolidated fields' that can be used. Each consolidated field is 58 marked by a single tag, and contains a single bulleted list, where 59 each list item starts with an identifier, marked as interpreted text 60 (C{`...`}). This module automatically splits these consolidated 61 fields into individual fields. The keys of C{CONSOLIDATED_FIELDS} are 62 the names of possible consolidated fields; and the values are the 63 names of the field tags that should be used for individual entries in 64 the list. 65 """ 66 __docformat__ = 'epytext en' 67 68 # Imports 69 import re, os, os.path 70 from xml.dom.minidom import * 71 72 from docutils.core import publish_string 73 from docutils.writers import Writer 74 from docutils.writers.html4css1 import HTMLTranslator, Writer as HTMLWriter 75 from docutils.writers.latex2e import LaTeXTranslator, Writer as LaTeXWriter 76 from docutils.readers.standalone import Reader as StandaloneReader 77 from docutils.utils import new_document 78 from docutils.nodes import NodeVisitor, Text, SkipChildren 79 from docutils.nodes import SkipNode, TreeCopyVisitor 80 from docutils.frontend import OptionParser 81 from docutils.parsers.rst import directives, roles 82 import docutils.nodes 83 import docutils.transforms.frontmatter 84 import docutils.transforms 85 import docutils.utils 86 87 from epydoc.compat import * # Backwards compatibility 88 from epydoc.markup import * 89 from epydoc.apidoc import ModuleDoc, ClassDoc 90 from epydoc.docwriter.dotgraph import * 91 from epydoc.docwriter.xlink import ApiLinkReader 92 from epydoc.markup.doctest import doctest_to_html, doctest_to_latex, \ 93 HTMLDoctestColorizer 94 95 #: A dictionary whose keys are the "consolidated fields" that are 96 #: recognized by epydoc; and whose values are the corresponding epydoc 97 #: field names that should be used for the individual fields. 98 CONSOLIDATED_FIELDS = { 99 'parameters': 'param', 100 'arguments': 'arg', 101 'exceptions': 'except', 102 'variables': 'var', 103 'ivariables': 'ivar', 104 'cvariables': 'cvar', 105 'groups': 'group', 106 'types': 'type', 107 'keywords': 'keyword', 108 } 109 110 #: A list of consolidated fields whose bodies may be specified using a 111 #: definition list, rather than a bulleted list. For these fields, the 112 #: 'classifier' for each term in the definition list is translated into 113 #: a @type field. 114 CONSOLIDATED_DEFLIST_FIELDS = ['param', 'arg', 'var', 'ivar', 'cvar', 'keyword'] 115

116 -def parse_docstring(docstring, errors, **options):

117 """ 118 Parse the given docstring, which is formatted using 119 ReStructuredText; and return a L{ParsedDocstring} representation 120 of its contents. 121 @param docstring: The docstring to parse 122 @type docstring: C{string} 123 @param errors: A list where any errors generated during parsing 124 will be stored. 125 @type errors: C{list} of L{ParseError} 126 @param options: Extra options. Unknown options are ignored. 127 Currently, no extra options are defined. 128 @rtype: L{ParsedDocstring} 129 """ 130 writer = _DocumentPseudoWriter() 131 reader = _EpydocReader(errors) # Outputs errors to the list. 132 publish_string(docstring, writer=writer, reader=reader, 133 settings_overrides={'report_level':10000, 134 'halt_level':10000, 135 'warning_stream':None}) 136 return ParsedRstDocstring(writer.document)

137

138 -class OptimizedReporter(docutils.utils.Reporter):

139 """A reporter that ignores all debug messages. This is used to 140 shave a couple seconds off of epydoc's run time, since docutils 141 isn't very fast about processing its own debug messages."""

142 - def debug(self, *args, **kwargs): pass

143

144 -class ParsedRstDocstring(ParsedDocstring):

145 """ 146 An encoded version of a ReStructuredText docstring. The contents 147 of the docstring are encoded in the L{_document} instance 148 variable. 149 150 @ivar _document: A ReStructuredText document, encoding the 151 docstring. 152 @type _document: C{docutils.nodes.document} 153 """

154 - def __init__(self, document):

155 """ 156 @type document: C{docutils.nodes.document} 157 """ 158 self._document = document 159 160 # The default document reporter and transformer are not 161 # pickle-able; so replace them with stubs that are. 162 document.reporter = OptimizedReporter( 163 document.reporter.source, 'SEVERE', 'SEVERE', '') 164 document.transformer = docutils.transforms.Transformer(document)

165

166 - def split_fields(self, errors=None):

167 # Inherit docs 168 if errors is None: errors = [] 169 visitor = _SplitFieldsTranslator(self._document, errors) 170 self._document.walk(visitor) 171 if len(self._document.children) > 0: 172 return self, visitor.fields 173 else: 174 return None, visitor.fields

175

176 - def summary(self):

177 # Inherit docs 178 visitor = _SummaryExtractor(self._document) 179 try: self._document.walk(visitor) 180 except docutils.nodes.NodeFound: pass 181 return visitor.summary, bool(visitor.other_docs)

182 183 # def concatenate(self, other): 184 # result = self._document.copy() 185 # for child in (self._document.get_children() + 186 # other._document.get_children()): 187 # visitor = TreeCopyVisitor(self._document) 188 # child.walkabout(visitor) 189 # result.append(visitor.get_tree_copy()) 190 # return ParsedRstDocstring(result) 191

192 - def to_html(self, docstring_linker, directory=None, 193 docindex=None, context=None, **options):

194 # Inherit docs 195 visitor = _EpydocHTMLTranslator(self._document, docstring_linker, 196 directory, docindex, context) 197 self._document.walkabout(visitor) 198 return ''.join(visitor.body)

199

200 - def to_latex(self, docstring_linker, **options):

201 # Inherit docs 202 visitor = _EpydocLaTeXTranslator(self._document, docstring_linker) 203 self._document.walkabout(visitor) 204 return ''.join(visitor.body)

205

206 - def to_plaintext(self, docstring_linker, **options):

207 # This is should be replaced by something better: 208 return self._document.astext()

209

210 - def __repr__(self): return '<ParsedRstDocstring: ...>'

211

212 - def index_terms(self):

213 visitor = _TermsExtractor(self._document) 214 self._document.walkabout(visitor) 215 return visitor.terms

216

217 -class _EpydocReader(ApiLinkReader):

218 """ 219 A reader that captures all errors that are generated by parsing, 220 and appends them to a list. 221 """ 222 # Remove the DocInfo transform, to ensure that :author: fields are 223 # correctly handled. This needs to be handled differently 224 # depending on the version of docutils that's being used, because 225 # the default_transforms attribute was deprecated & replaced by 226 # get_transforms(). 227 version = [int(v) for v in docutils.__version__.split('.')] 228 version += [ 0 ] * (3 - len(version)) 229 if version < [0,4,0]: 230 default_transforms = list(ApiLinkReader.default_transforms) 231 try: default_transforms.remove(docutils.transforms.frontmatter.DocInfo) 232 except ValueError: pass 233 else:

234 - def get_transforms(self):

235 return [t for t in ApiLinkReader.get_transforms(self) 236 if t != docutils.transforms.frontmatter.DocInfo]

237 del version 238

239 - def __init__(self, errors):

240 self._errors = errors 241 ApiLinkReader.__init__(self)

242

243 - def new_document(self):

244 document = new_document(self.source.source_path, self.settings) 245 # Capture all warning messages. 246 document.reporter.attach_observer(self.report) 247 # These are used so we know how to encode warning messages: 248 self._encoding = document.reporter.encoding 249 self._error_handler = document.reporter.error_handler 250 # Return the new document. 251 return document

252

253 - def report(self, error):

254 try: is_fatal = int(error['level']) > 2 255 except: is_fatal = 1 256 try: linenum = int(error['line']) 257 except: linenum = None 258 259 msg = ''.join([c.astext().encode(self._encoding, self._error_handler) 260 for c in error]) 261 262 self._errors.append(ParseError(msg, linenum, is_fatal))

263

264 -class _DocumentPseudoWriter(Writer):

265 """ 266 A pseudo-writer for the docutils framework, that can be used to 267 access the document itself. The output of C{_DocumentPseudoWriter} 268 is just an empty string; but after it has been used, the most 269 recently processed document is available as the instance variable 270 C{document} 271 272 @type document: C{docutils.nodes.document} 273 @ivar document: The most recently processed document. 274 """

275 - def __init__(self):

276 self.document = None 277 Writer.__init__(self)

278

279 - def translate(self):

280 self.output = ''

281

282 -class _SummaryExtractor(NodeVisitor):

283 """ 284 A docutils node visitor that extracts the first sentence from 285 the first paragraph in a document. 286 """

287 - def __init__(self, document):

288 NodeVisitor.__init__(self, document) 289 self.summary = None 290 self.other_docs = None

291

292 - def visit_document(self, node):

293 self.summary = None

294 295 _SUMMARY_RE = re.compile(r'(\s*[\w\W]*?\.)(\s|$)')

296 - def visit_paragraph(self, node):

297 if self.summary is not None: 298 # found a paragraph after the first one 299 self.other_docs = True 300 raise docutils.nodes.NodeFound('Found summary') 301 302 summary_pieces = [] 303 304 # Extract the first sentence. 305 for child in node: 306 if isinstance(child, docutils.nodes.Text): 307 m = self._SUMMARY_RE.match(child.data) 308 if m: 309 summary_pieces.append(docutils.nodes.Text(m.group(1))) 310 other = child.data[m.end():] 311 if other and not other.isspace(): 312 self.other_docs = True 313 break 314 summary_pieces.append(child) 315 316 summary_doc = self.document.copy() # shallow copy 317 summary_para = node.copy() # shallow copy 318 summary_doc[:] = [summary_para] 319 summary_para[:] = summary_pieces 320 self.summary = ParsedRstDocstring(summary_doc)

321

322 - def visit_field(self, node):

323 raise SkipNode

324

325 - def unknown_visit(self, node):

326 'Ignore all unknown nodes'

327

328 -class _TermsExtractor(NodeVisitor):

329 """ 330 A docutils node visitor that extracts the terms from documentation. 331 332 Terms are created using the C{:term:} interpreted text role. 333 """

334 - def __init__(self, document):

335 NodeVisitor.__init__(self, document) 336 337 self.terms = None 338 """ 339 The terms currently found. 340 @type: C{list} 341 """

342

343 - def visit_document(self, node):

344 self.terms = [] 345 self._in_term = False

346

347 - def visit_emphasis(self, node):

348 if 'term' in node.get('classes'): 349 self._in_term = True

350

351 - def depart_emphasis(self, node):

def depart_emphasis(self, node):

Source Code for Module epydoc.markup.restructuredtext