mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Close #2155: Support `code
` directive
This commit is contained in:
parent
bde9cab7fe
commit
c4a45b4a01
1
CHANGES
1
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
|
||||
--------
|
||||
|
@ -19,18 +19,6 @@ from sphinx.util import docutils
|
||||
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 @@ nl_escape_re = re.compile(r'\\\n')
|
||||
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 @@ class DefaultDomain(SphinxDirective):
|
||||
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]
|
||||
|
@ -14,6 +14,7 @@ from docutils.parsers.rst import directives
|
||||
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 @@ class ListTable(tables.ListTable):
|
||||
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 {
|
||||
|
54
tests/test_directive_patch.py
Normal file
54
tests/test_directive_patch.py
Normal file
@ -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})
|
Loading…
Reference in New Issue
Block a user