def add_directive(self,
name,
obj,
content=None,
arguments=None,
**options):
# type: (unicode, Any, bool, Tuple[int, int, bool], Any) -> None
"""Register a Docutils directive.
*name* must be the prospective directive name. There are two possible
ways to write a directive:
- In the docutils 0.4 style, *obj* is the directive function.
*content*, *arguments* and *options* are set as attributes on the
function and determine whether the directive has content, arguments
and options, respectively. **This style is deprecated.**
- In the docutils 0.5 style, *directiveclass* is the directive class.
It must already have attributes named *has_content*,
*required_arguments*, *optional_arguments*,
*final_argument_whitespace* and *option_spec* that correspond to the
options for the function way. See `the Docutils docs
<http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_
for details.
The directive class must inherit from the class
``docutils.parsers.rst.Directive``.
For example, the (already existing) :rst:dir:`literalinclude` directive
would be added like this:
.. code-block:: python
from docutils.parsers.rst import directives
add_directive('literalinclude', literalinclude_directive,
content = 0, arguments = (1, 0, 0),
linenos = directives.flag,
language = directives.unchanged,
encoding = directives.encoding)
.. versionchanged:: 0.6
Docutils 0.5-style directive classes are now supported.
.. deprecated:: 1.8
Docutils 0.4-style (function based) directives support is deprecated.
"""
logger.debug('[app] adding directive: %r',
(name, obj, content, arguments, options))
if name in directives._directives:
logger.warning(__('while setting up extension %s: directive %r is '
'already registered, it will be overridden'),
self._setting_up_extension[-1],
name,
type='app',
subtype='add_directive')
if not isclass(obj) or not issubclass(obj, Directive):
directive = directive_helper(obj, content, arguments, **options)
directives.register_directive(name, directive)
else:
directives.register_directive(name, obj)
def add_directive_to_domain(self,
domain,
name,
obj,
has_content=None,
argument_spec=None,
override=False,
**option_spec):
# type: (unicode, unicode, Any, bool, Any, bool, Any) -> None
logger.debug(
'[app] adding directive to domain: %r',
(domain, name, obj, has_content, argument_spec, option_spec))
if domain not in self.domains:
raise ExtensionError(__('domain %s not yet registered') % domain)
directives = self.domain_directives.setdefault(domain, {})
if name in directives and not override:
raise ExtensionError(
__('The %r directive is already registered to %d domain') %
(name, domain))
if not isclass(obj) or not issubclass(obj, Directive):
directives[name] = directive_helper(obj, has_content,
argument_spec, **option_spec)
else:
directives[name] = obj
def add_directive_to_domain(self, domain, name, obj,
has_content=None, argument_spec=None, **option_spec):
# type: (unicode, unicode, Any, bool, Any, Any) -> None
if domain not in self.domains:
raise ExtensionError(_('domain %s not yet registered') % domain)
directive = directive_helper(obj, has_content, argument_spec, **option_spec)
self.domains[domain].directives[name] = directive
def add_directive_to_domain(self, domain, name, obj,
has_content=None, argument_spec=None, **option_spec):
# type: (unicode, unicode, Any, bool, Any, Any) -> None
logger.debug('[app] adding directive to domain: %r',
(domain, name, obj, has_content, argument_spec, option_spec))
if domain not in self.domains:
raise ExtensionError(__('domain %s not yet registered') % domain)
directives = self.domain_directives.setdefault(domain, {})
directives[name] = directive_helper(obj, has_content, argument_spec, **option_spec)
def add_directive(self, name, obj, content=None, arguments=None, **options):
# type: (unicode, Any, bool, Tuple[int, int, bool], Any) -> None
logger.debug('[app] adding directive: %r',
(name, obj, content, arguments, options))
if name in directives._directives:
logger.warning(_('while setting up extension %s: directive %r is '
'already registered, it will be overridden'),
self._setting_up_extension[-1], name,
type='app', subtype='add_directive')
directive = directive_helper(obj, content, arguments, **options)
directives.register_directive(name, directive)
def _directive_helper(self,
obj,
has_content=None,
argument_spec=None,
**option_spec):
# type: (Any, bool, Tuple[int, int, bool], Any) -> Any
warnings.warn(
'_directive_helper() is now deprecated. '
'Please use sphinx.util.docutils.directive_helper() instead.',
RemovedInSphinx17Warning)
return directive_helper(obj, has_content, argument_spec, **option_spec)
def add_directive(self, name, obj, content=None, arguments=None, **options):
# type: (unicode, Any, bool, Tuple[int, int, bool], Any) -> None
logger.debug('[app] adding directive: %r',
(name, obj, content, arguments, options))
if name in directives._directives:
logger.warning(__('while setting up extension %s: directive %r is '
'already registered, it will be overridden'),
self._setting_up_extension[-1], name,
type='app', subtype='add_directive')
directive = directive_helper(obj, content, arguments, **options)
directives.register_directive(name, directive)
def add_directive_to_domain(self, domain, name, obj,
has_content=None, argument_spec=None, **option_spec):
# type: (unicode, unicode, Any, bool, Any, Any) -> None
logger.debug('[app] adding directive to domain: %r',
(domain, name, obj, has_content, argument_spec, option_spec))
if domain not in self.domains:
raise ExtensionError(__('domain %s not yet registered') % domain)
directives = self.domain_directives.setdefault(domain, {})
if not isclass(obj) or not issubclass(obj, Directive):
directives[name] = directive_helper(obj, has_content, argument_spec, **option_spec)
else:
directives[name] = obj
def add_directive_to_domain(self,
domain,
name,
obj,
has_content=None,
argument_spec=None,
**option_spec):
# type: (unicode, unicode, Any, bool, Any, Any) -> None
if domain not in self.domains:
raise ExtensionError(_('domain %s not yet registered') % domain)
directive = directive_helper(obj, has_content, argument_spec,
**option_spec)
self.domains[domain].directives[name] = directive
def add_directive_to_domain(self, domain, name, obj, has_content=None, argument_spec=None,
override=False, **option_spec):
# type: (str, str, Any, bool, Any, bool, Any) -> None
logger.debug('[app] adding directive to domain: %r',
(domain, name, obj, has_content, argument_spec, option_spec))
if domain not in self.domains:
raise ExtensionError(__('domain %s not yet registered') % domain)
directives = self.domain_directives.setdefault(domain, {})
if name in directives and not override:
raise ExtensionError(__('The %r directive is already registered to domain %s') %
(name, domain))
if not isclass(obj) or not issubclass(obj, Directive):
directives[name] = directive_helper(obj, has_content, argument_spec, **option_spec)
else:
directives[name] = obj
def _directive_helper(self, obj, has_content=None, argument_spec=None, **option_spec):
# type: (Any, bool, Tuple[int, int, bool], Any) -> Any
warnings.warn('_directive_helper() is now deprecated. '
'Please use sphinx.util.docutils.directive_helper() instead.',
RemovedInSphinx17Warning)
return directive_helper(obj, has_content, argument_spec, **option_spec)
def add_directive(self, name, obj, content=None, arguments=None, override=False, **options): # NOQA
# type: (str, Any, bool, Tuple[int, int, bool], bool, Any) -> None
"""Register a Docutils directive.
*name* must be the prospective directive name. There are two possible
ways to write a directive:
- In the docutils 0.4 style, *obj* is the directive function.
*content*, *arguments* and *options* are set as attributes on the
function and determine whether the directive has content, arguments
and options, respectively. **This style is deprecated.**
- In the docutils 0.5 style, *obj* is the directive class.
It must already have attributes named *has_content*,
*required_arguments*, *optional_arguments*,
*final_argument_whitespace* and *option_spec* that correspond to the
options for the function way. See `the Docutils docs
<http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_
for details.
The directive class must inherit from the class
``docutils.parsers.rst.Directive``.
For example, the (already existing) :rst:dir:`literalinclude` directive
would be added like this:
.. code-block:: python
from docutils.parsers.rst import Directive, directives
class LiteralIncludeDirective(Directive):
has_content = True
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = True
option_spec = {
'class': directives.class_option,
'name': directives.unchanged,
}
def run(self):
...
add_directive('literalinclude', LiteralIncludeDirective)
.. versionchanged:: 0.6
Docutils 0.5-style directive classes are now supported.
.. deprecated:: 1.8
Docutils 0.4-style (function based) directives support is deprecated.
.. versionchanged:: 1.8
Add *override* keyword.
"""
logger.debug('[app] adding directive: %r',
(name, obj, content, arguments, options))
if not override and docutils.is_directive_registered(name):
logger.warning(__('directive %r is already registered, it will be overridden'),
name, type='app', subtype='add_directive')
if not isclass(obj) or not issubclass(obj, Directive):
directive = directive_helper(obj, content, arguments, **options)
docutils.register_directive(name, directive)
else:
docutils.register_directive(name, obj)
def add_directive(self, name, obj, content=None, arguments=None, override=False, **options): # NOQA
# type: (str, Any, bool, Tuple[int, int, bool], bool, Any) -> None
"""Register a Docutils directive.
*name* must be the prospective directive name. There are two possible
ways to write a directive:
- In the docutils 0.4 style, *obj* is the directive function.
*content*, *arguments* and *options* are set as attributes on the
function and determine whether the directive has content, arguments
and options, respectively. **This style is deprecated.**
- In the docutils 0.5 style, *obj* is the directive class.
It must already have attributes named *has_content*,
*required_arguments*, *optional_arguments*,
*final_argument_whitespace* and *option_spec* that correspond to the
options for the function way. See `the Docutils docs
<http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_
for details.
The directive class must inherit from the class
``docutils.parsers.rst.Directive``.
For example, the (already existing) :rst:dir:`literalinclude` directive
would be added like this:
.. code-block:: python
from docutils.parsers.rst import Directive, directives
class LiteralIncludeDirective(Directive):
has_content = True
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = True
option_spec = {
'class': directives.class_option,
'name': directives.unchanged,
}
def run(self):
...
add_directive('literalinclude', LiteralIncludeDirective)
.. versionchanged:: 0.6
Docutils 0.5-style directive classes are now supported.
.. deprecated:: 1.8
Docutils 0.4-style (function based) directives support is deprecated.
.. versionchanged:: 1.8
Add *override* keyword.
"""
logger.debug('[app] adding directive: %r',
(name, obj, content, arguments, options))
if not override and docutils.is_directive_registered(name):
logger.warning(__('directive %r is already registered, it will be overridden'),
name, type='app', subtype='add_directive')
if not isclass(obj) or not issubclass(obj, Directive):
directive = directive_helper(obj, content, arguments, **options)
docutils.register_directive(name, directive)
else:
docutils.register_directive(name, obj)