Directives#

How To Guides#

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

API Reference#

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

Directive support for the language server.

add_argument_completion_provider(provider)[source]#

Register an ArgumentCompletion provider.

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]#

Register an ArgumentDefinition provider.

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.

Register an ArgumentLink provider.

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]#

Register directive documentation.

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]#

Register a directive language feature.

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 (Optional[str]) – 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 (Optional[str]) – 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 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 (Optional[str]) – 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 (Optional[str]) – The name of the domain the directive belongs to, if applicable.

  • argument (str) – The argument to find the definition of.

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 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 (Optional[str]) – The name of the domain the directive belongs to, if applicable.

  • argument (str) – The argument to resolve the link for.