Close #2155: Support code directive

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
 --------

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]

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 {

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})