diff --git a/CHANGES b/CHANGES index 0c280a67a5b..1ae36d21be7 100644 --- a/CHANGES +++ b/CHANGES @@ -22,6 +22,7 @@ Bugs fixed * #5508: ``linenothreshold`` option for ``highlight`` directive was ignored * texinfo: ``make install-info`` causes syntax error * texinfo: ``make install-info`` fails on macOS +* #2155: Support ``code`` directive Testing -------- diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index 8dbb1cec6e8..99d579863a7 100644 --- a/sphinx/directives/__init__.py +++ b/sphinx/directives/__init__.py @@ -19,18 +19,6 @@ from sphinx.util.docfields import DocFieldTransformer from sphinx.util.docutils import SphinxDirective -# import all directives sphinx provides -from sphinx.directives.code import ( # noqa - Highlight, CodeBlock, LiteralInclude -) -from sphinx.directives.other import ( # noqa - TocTree, Author, Index, VersionChange, SeeAlso, - TabularColumns, Centered, Acks, HList, Only, Include, Class -) -from sphinx.directives.patches import ( # noqa - Figure, Meta -) - if False: # For type annotation from typing import Any, Dict # NOQA @@ -46,6 +34,19 @@ strip_backslash_re = re.compile(r'\\(.)') +def optional_int(argument): + """ + Check for an integer argument or None value; raise ``ValueError`` if not. + """ + if argument is None: + return None + else: + value = int(argument) + if value < 0: + raise ValueError('negative value; must be positive or zero') + return value + + class ObjectDescription(SphinxDirective): """ Directive to describe a class, function or similar object. Not used @@ -243,6 +244,18 @@ def run(self): self.env.temp_data['default_domain'] = self.env.domains.get(domain_name) return [] +# import all directives sphinx provides (for compatibility) +from sphinx.directives.code import ( # noqa + Highlight, CodeBlock, LiteralInclude +) +from sphinx.directives.other import ( # noqa + TocTree, Author, Index, VersionChange, SeeAlso, + TabularColumns, Centered, Acks, HList, Only, Include, Class +) +from sphinx.directives.patches import ( # noqa + Figure, Meta +) + def setup(app): # type: (Sphinx) -> Dict[str, Any] diff --git a/sphinx/directives/patches.py b/sphinx/directives/patches.py index 3c31571ac1c..9d339e5a58f 100644 --- a/sphinx/directives/patches.py +++ b/sphinx/directives/patches.py @@ -14,6 +14,7 @@ from docutils.parsers.rst.directives import images, html, tables from sphinx import addnodes +from sphinx.directives import optional_int from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import set_source_info @@ -110,6 +111,52 @@ def make_title(self): return title, message +class Code(SphinxDirective): + """Parse and mark up content of a code block. + + This is compatible with docutils' :rst:dir:`code` directive. + """ + optional_arguments = 1 + option_spec = { + 'class': directives.class_option, + 'name': directives.unchanged, + 'number-lines': optional_int, + } + has_content = True + + def run(self): + # type: () -> List[nodes.Node] + self.assert_has_content() + + code = '\n'.join(self.content) + node = nodes.literal_block(code, code, + classes=self.options.get('classes', []), + highlight_args={}) + self.add_name(node) + set_source_info(self, node) + + if self.arguments: + # highlight language specified + node['language'] = self.arguments[0] + node['force_highlighting'] = True + else: + # no highlight language specified. Then this directive refers the current + # highlight setting via ``highlight`` directive or ``highlight_language`` + # configuration. + node['language'] = self.env.temp_data.get('highlight_language', + self.config.highlight_language) + node['force_highlighting'] = False + + if 'number-lines' in self.options: + node['linenos'] = True + + # if number given, treat as lineno-start. + if self.options['number-lines']: + node['highlight_args']['linenostart'] = self.options['number-lines'] + + return [node] + + class MathDirective(SphinxDirective): has_content = True required_arguments = 0 @@ -171,6 +218,7 @@ def setup(app): directives.register_directive('table', RSTTable) directives.register_directive('csv-table', CSVTable) directives.register_directive('list-table', ListTable) + directives.register_directive('code', Code) directives.register_directive('math', MathDirective) return { diff --git a/tests/test_directive_patch.py b/tests/test_directive_patch.py new file mode 100644 index 00000000000..4f61f2d0be7 --- /dev/null +++ b/tests/test_directive_patch.py @@ -0,0 +1,54 @@ +""" + test_directive_patch + ~~~~~~~~~~~~~~~~~~~ + + Test the patched directives. + + :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +from docutils import nodes + +from sphinx.testing import restructuredtext +from sphinx.testing.util import assert_node + + +def test_code_directive(app): + # normal case + text = ('.. code::\n' + '\n' + ' print("hello world")\n') + + doctree = restructuredtext.parse(app, text) + assert_node(doctree, [nodes.document, nodes.literal_block, 'print("hello world")']) + assert_node(doctree[0], language="default", highlight_args={}) + + # with language + text = ('.. code:: python\n' + '\n' + ' print("hello world")\n') + + doctree = restructuredtext.parse(app, text) + assert_node(doctree, [nodes.document, nodes.literal_block, 'print("hello world")']) + assert_node(doctree[0], language="python", highlight_args={}) + + # :number-lines: option + text = ('.. code:: python\n' + ' :number-lines:\n' + '\n' + ' print("hello world")\n') + + doctree = restructuredtext.parse(app, text) + assert_node(doctree, [nodes.document, nodes.literal_block, 'print("hello world")']) + assert_node(doctree[0], language="python", linenos=True, highlight_args={}) + + # :number-lines: option + text = ('.. code:: python\n' + ' :number-lines: 5\n' + '\n' + ' print("hello world")\n') + + doctree = restructuredtext.parse(app, text) + assert_node(doctree, [nodes.document, nodes.literal_block, 'print("hello world")']) + assert_node(doctree[0], language="python", linenos=True, highlight_args={'linenostart': 5})