Directives#

How To Guides#

The following guides outline how to extend the language server to add support for your custom directives.

Supporting Custom Directive Registries

API Reference#

class esbonio.lsp.directives.Directives(*args, **kwargs)[source]#

Directive support for the language server.

add_argument_completion_provider(provider)[source]#

Deprecated since version 0.14.2: This will be removed in v1.0, use add_feature() with a DirectiveLanguageFeature subclass instead.

Parameters:: provider (ArgumentCompletion) – The provider to register.

add_argument_definition_provider(provider)[source]#

Deprecated since version 0.14.2: This will be removed in v1.0, use add_feature() with a DirectiveLanguageFeature subclass instead.

Parameters:: provider (ArgumentDefinition) – The provider to register.

add_argument_link_provider(provider)[source]#

Deprecated since version 0.14.2: This will be removed in v1.0, use add_feature() with a DirectiveLanguageFeature subclass instead.

Parameters:: provider (ArgumentLink) – The provider to register.

add_documentation(documentation)[source]#

documentation should be a dictionary with the following structure

documentation = {
    "raw(docutils.parsers.rst.directives.misc.Raw)": {
        "is_markdown": true,
        "license": "https://...",
        "source": "https://...",
        "description": [
            "# .. raw::",
            "The raw directive is used for...",
            ...
         ]
        "options": {
            "file": "The file option allows...",
            ...
        }
    }
}

where the key has the form name(dotted_name). There are cases where a directive’s implementation is not sufficient to uniquely identify it as multiple directives can be provided by a single class.

This means the key has to be a combination of the name the user writes in a reStructuredText document and dotted_name is the fully qualified class name of the directive’s implementation.

Note

If there is a clash with an existing key, the existing value will be overwritten with the new value.

The values in this dictionary are themselves dictionaries with the following fields.

description: A list of strings for the directive’s main documentation.
options,: A dictionary, with a field for the documentaton of each of the directive’s options.
is_markdown: A boolean flag used to indicate whether the description and options are written in plain text or markdown.
source: The url to the documentation’s source
license: The url to the documentation’s license

Parameters:: documentation (Dict[str, Dict[str, Any]]) – The documentation to register.

add_feature(feature)[source]#

Parameters:: feature (DirectiveLanguageFeature) – The directive language feature

get_directives()[source]#

Return a dictionary of all known directives.

get_documentation(label, implementation)[source]#

Return the documentation for the given directive, if available.

If documentation for the given label cannot be found, this function will also look for the label under the project’s primary_domain followed by the std domain.

Parameters:

label (str) – The name of the directive, as the user would type in an reStructuredText file.
implementation (str) – The full dotted name of the directive’s implementation.

get_implementation(directive, domain)[source]#

Return the implementation of a directive given its name

Parameters:

directive (str) – The name of the directive.
domain (str | None) – The domain of the directive, if applicable.

suggest_directives(context)[source]#

Suggest directives that may be used, given a completion context.

Parameters:: context (CompletionContext) – The CompletionContext.

suggest_options(context, directive, domain)[source]#

Suggest directive options that may be used, given a completion context.

class esbonio.lsp.directives.DirectiveLanguageFeature[source]#

Base class for directive language features.

complete_arguments(context, domain, name)[source]#

Return a list of completion items representing valid targets for the given directive.

Parameters:

context (CompletionContext) – The completion context
domain (str) – The name of the domain the directive is a member of
name (str) – The name of the domain

find_argument_definitions(context, directive, domain, argument)[source]#

Return a list of locations representing definitions of the given argument.

Parameters:

context (DefinitionContext) – The context of the definition request.
directive (str) – The name of the directive the argument is associated with.
domain (str | None) – The name of the domain the directive belongs to, if applicable.
argument (str) – The argument to find the definition of.

get_implementation(directive, domain)[source]#

Return the implementation for the given directive name.

index_directives()[source]#

Return all known directives.

resolve_argument_link(context, directive, domain, argument)[source]#

Resolve a document link request for the given argument.

Parameters:

context (DocumentLinkContext) – The context of the document link request.
directive (str) – The name of the directive the argument is associated with.
domain (str | None) – The name of the domain the directive belongs to, if applicable.
argument (str) – The argument to resolve the link for.

suggest_directives(context)[source]#

Suggest directives that may be used, given a completion context.

suggest_options(context, directive, domain)[source]#

Suggest options that may be used, given a completion context.

esbonio.lsp.util.patterns.DIRECTIVE: Pattern#

A regular expression to detect and parse partial and complete directives.

This does not include any options or content that may be included underneath the initial declaration. A number of named capture groups are available.

name: The name of the directive, not including the domain prefix.
domain: The domain prefix
directive: Everything that makes up a directive, from the initial .. up to and including the :: characters.
argument: All argument text.
substitution: If the directive is part of a substitution definition, this group will contain

Example

Here is an example with a “standard” directive

>>> from esbonio.lsp.util.patterns import DIRECTIVE
>>> match = DIRECTIVE.match(".. py:function:: print")

>>> match.group("name")
'function'

>>> match.group("domain")
'py'

>>> match.group("directive")
'.. py:function::'

>>> match.group("argument")
'print'

And here is an example with a substitution definition

>>> from esbonio.lsp.util.patterns import DIRECTIVE
>>> match = DIRECTIVE.match(".. |example| replace:: this is an example")

>>> match.group("name")
'replace'

>>> match.group("domain") is None
True

>>> match.group("substitution")
'|example|'

>>> match.group("substitution_text")
'example'

>>> match.group("directive")
'.. |example| replace::'

>>> match.group("argument")
'this is an example'

esbonio.lsp.util.patterns.DIRECTIVE_OPTION: Pattern#

A regular expression used to detect and parse partial and complete directive options.

A number of named capture groups are available

name: The name of the option
option: The name of the option including the surrounding : characters.
indent: The whitespace characters making preceeding the initial : character
value: The value passed to the option

Example

>>> from esbonio.lsp.util.patterns import DIRECTIVE_OPTION
>>> match = DIRECTIVE_OPTION.match("   :align: center")

>>> match.group("name")
'align'

>>> match.group("option")
':align:'

>>> match.group("indent")
'   '

>>> match.group("value")
'center'

class esbonio.lsp.directives.ArgumentCompletion(*args, **kwargs)[source]#

A completion provider for directive arguments.

Deprecated since version 0.14.2: This will be removed in v1.0, use subclasses of DirectiveLanguageFeature instead.

complete_arguments(context, domain, name)[source]#

Return a list of completion items representing valid targets for the given directive.

Parameters:

context (CompletionContext) – The completion context
domain (str) – The name of the domain the directive is a member of
name (str) – The name of the domain

class esbonio.lsp.directives.ArgumentDefinition(*args, **kwargs)[source]#

A definition provider for directive arguments.

Deprecated since version 0.14.2: This will be removed in v1.0, use subclasses of DirectiveLanguageFeature instead.

find_definitions(context, directive, domain, argument)[source]#

Return a list of locations representing definitions of the given argument.

Parameters:

context (DefinitionContext) – The context of the definition request.
directive (str) – The name of the directive the argument is associated with.
domain (str | None) – The name of the domain the directive belongs to, if applicable.
argument (str) – The argument to find the definition of.

class esbonio.lsp.directives.ArgumentLink(*args, **kwargs)[source]#

A document link resolver for directive arguments.

Deprecated since version 0.14.2: This will be removed in v1.0, use subclasses of DirectiveLanguageFeature instead.

resolve_link(context, directive, domain, argument)[source]#

Resolve a document link request for the given argument.

Parameters:

context (DocumentLinkContext) – The context of the document link request.
directive (str) – The name of the directive the argument is associated with.
domain (str | None) – The name of the domain the directive belongs to, if applicable.
argument (str) – The argument to resolve the link for.