diff options
Diffstat (limited to 'sphinx/directives/code.py')
| -rw-r--r-- | sphinx/directives/code.py | 233 |
1 files changed, 155 insertions, 78 deletions
diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 8ce2eed9..645bc784 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -7,6 +7,7 @@ :license: BSD, see LICENSE for details. """ +import os import sys import codecs from os import path @@ -15,85 +16,161 @@ from docutils import nodes from docutils.parsers.rst import directives from sphinx import addnodes - - -# ------ highlight directive -------------------------------------------------------- - -def highlightlang_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - if 'linenothreshold' in options: +from sphinx.util import parselinenos +from sphinx.util.compat import Directive, directive_dwim + + +class Highlight(Directive): + """ + Directive to set the highlighting language for code blocks, as well + as the threshold for line numbers. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'linenothreshold': directives.unchanged, + } + + def run(self): + if 'linenothreshold' in self.options: + try: + linenothreshold = int(self.options['linenothreshold']) + except Exception: + linenothreshold = 10 + else: + linenothreshold = sys.maxint + return [addnodes.highlightlang(lang=self.arguments[0].strip(), + linenothreshold=linenothreshold)] + + +class CodeBlock(Directive): + """ + Directive for a code block with special highlighting or line numbering + settings. + """ + + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'linenos': directives.flag, + } + + def run(self): + code = u'\n'.join(self.content) + literal = nodes.literal_block(code, code) + literal['language'] = self.arguments[0] + literal['linenos'] = 'linenos' in self.options + return [literal] + + +class LiteralInclude(Directive): + """ + Like ``.. include:: :literal:``, but only warns if the include file is + not found, and does not raise errors. Also has several options for + selecting what to include. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'linenos': directives.flag, + 'language': directives.unchanged_required, + 'encoding': directives.encoding, + 'pyobject': directives.unchanged_required, + 'lines': directives.unchanged_required, + 'start-after': directives.unchanged_required, + 'end-before': directives.unchanged_required, + } + + def run(self): + document = self.state.document + filename = self.arguments[0] + if not document.settings.file_insertion_enabled: + return [document.reporter.warning('File insertion disabled', + line=self.lineno)] + env = document.settings.env + if filename.startswith('/') or filename.startswith(os.sep): + rel_fn = filename[1:] + else: + docdir = path.dirname(env.doc2path(env.docname, base=None)) + rel_fn = path.normpath(path.join(docdir, filename)) + fn = path.join(env.srcdir, rel_fn) + + if 'pyobject' in self.options and 'lines' in self.options: + return [document.reporter.warning( + 'Cannot use both "pyobject" and "lines" options', + line=self.lineno)] + + encoding = self.options.get('encoding', env.config.source_encoding) try: - linenothreshold = int(options['linenothreshold']) - except Exception: - linenothreshold = 10 - else: - linenothreshold = sys.maxint - return [addnodes.highlightlang(lang=arguments[0].strip(), - linenothreshold=linenothreshold)] - -highlightlang_directive.content = 0 -highlightlang_directive.arguments = (1, 0, 0) -highlightlang_directive.options = {'linenothreshold': directives.unchanged} -directives.register_directive('highlight', highlightlang_directive) -directives.register_directive('highlightlang', highlightlang_directive) # old name - - -# ------ code-block directive ------------------------------------------------------- - -def codeblock_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - code = u'\n'.join(content) - literal = nodes.literal_block(code, code) - literal['language'] = arguments[0] - literal['linenos'] = 'linenos' in options - return [literal] - -codeblock_directive.content = 1 -codeblock_directive.arguments = (1, 0, 0) -codeblock_directive.options = {'linenos': directives.flag} -directives.register_directive('code-block', codeblock_directive) -directives.register_directive('sourcecode', codeblock_directive) - - -# ------ literalinclude directive --------------------------------------------------- - -def literalinclude_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Like .. include:: :literal:, but only warns if the include file is not found.""" - if not state.document.settings.file_insertion_enabled: - return [state.document.reporter.warning('File insertion disabled', line=lineno)] - env = state.document.settings.env - rel_fn = arguments[0] - source_dir = path.dirname(path.abspath(state_machine.input_lines.source( - lineno - state_machine.input_offset - 1))) - fn = path.normpath(path.join(source_dir, rel_fn)) - - encoding = options.get('encoding', env.config.source_encoding) - try: - f = codecs.open(fn, 'rU', encoding) - text = f.read() - f.close() - except (IOError, OSError): - retnode = state.document.reporter.warning( - 'Include file %r not found or reading it failed' % arguments[0], line=lineno) - except UnicodeError: - retnode = state.document.reporter.warning( - 'Encoding %r used for reading included file %r seems to ' - 'be wrong, try giving an :encoding: option' % - (encoding, arguments[0])) - else: + f = codecs.open(fn, 'rU', encoding) + lines = f.readlines() + f.close() + except (IOError, OSError): + return [document.reporter.warning( + 'Include file %r not found or reading it failed' % filename, + line=self.lineno)] + except UnicodeError: + return [document.reporter.warning( + 'Encoding %r used for reading included file %r seems to ' + 'be wrong, try giving an :encoding: option' % + (encoding, filename))] + + objectname = self.options.get('pyobject') + if objectname is not None: + from sphinx.pycode import ModuleAnalyzer + analyzer = ModuleAnalyzer.for_file(fn, '') + tags = analyzer.find_tags() + if objectname not in tags: + return [document.reporter.warning( + 'Object named %r not found in include file %r' % + (objectname, filename), line=self.lineno)] + else: + lines = lines[tags[objectname][1]-1 : tags[objectname][2]-1] + + linespec = self.options.get('lines') + if linespec is not None: + try: + linelist = parselinenos(linespec, len(lines)) + except ValueError, err: + return [document.reporter.warning(str(err), line=self.lineno)] + lines = [lines[i] for i in linelist] + + startafter = self.options.get('start-after') + endbefore = self.options.get('end-before') + if startafter is not None or endbefore is not None: + use = not startafter + res = [] + for line in lines: + if not use and startafter in line: + use = True + elif use and endbefore in line: + use = False + break + elif use: + res.append(line) + lines = res + + text = ''.join(lines) retnode = nodes.literal_block(text, text, source=fn) retnode.line = 1 - if options.get('language', ''): - retnode['language'] = options['language'] - if 'linenos' in options: + if self.options.get('language', ''): + retnode['language'] = self.options['language'] + if 'linenos' in self.options: retnode['linenos'] = True - state.document.settings.env.note_dependency(rel_fn) - return [retnode] - -literalinclude_directive.options = {'linenos': directives.flag, - 'language': directives.unchanged, - 'encoding': directives.encoding} -literalinclude_directive.content = 0 -literalinclude_directive.arguments = (1, 0, 0) -directives.register_directive('literalinclude', literalinclude_directive) + document.settings.env.note_dependency(rel_fn) + return [retnode] + + +directives.register_directive('highlight', directive_dwim(Highlight)) +directives.register_directive('highlightlang', directive_dwim(Highlight)) # old +directives.register_directive('code-block', directive_dwim(CodeBlock)) +directives.register_directive('sourcecode', directive_dwim(CodeBlock)) +directives.register_directive('literalinclude', directive_dwim(LiteralInclude)) |