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)