def setup(app):
# If a minigallery directive has already been registered, do nothing.
# It's probably that we are on a version of sphinx-gallery with the directive
if sphinx_docutils.is_directive_registered("minigallery"):
print("Not using sunpy.util.sphinx.minigallery as a minigallery "
"directive has already been registered.")
return
app.add_directive('minigallery', MiniGallery)
def add_directive(self,
name: str,
cls: Type[Directive],
override: bool = False) -> None:
"""
Register a Docutils directive.
"""
if not override and docutils.is_directive_registered(name):
raise ValueError(
f"directive {name!r} is already registered, it will be overridden"
)
docutils.register_directive(name, cls)
def add_directive(self,
name: str,
cls: "Type[Directive]",
override: bool = False) -> None:
"""Register a Docutils directive.
*name* must be the prospective directive name. *cls* is a directive
class which inherits ``docutils.parsers.rst.Directive``. For more
details, see `the Docutils docs
<http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_ .
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, cls))
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')
docutils.register_directive(name, cls)
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)
