Roles#

How To Guides#

The following guides outlne how to extens the language server to add support for your custom roles.

Supporting Custom Role Registries

API Reference#

class esbonio.lsp.roles.Roles(*args, **kwargs)[source]#

Role support for the language server.

add_documentation(documentation)[source]#

documentation should be a dictionary of the form

documentation = {
    "raw(docutils.parsers.rst.roles.raw_role)": {
        "is_markdown": true,
        "license": "https://...",
        "source": "https://...",
        "description": [
            "# :raw:",
            "The raw role is used for...",
            ...
        ]
    }
}

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

This means the key has to be a combination of the name the user writes in an reStructuredText document and dotted_name is the fully qualified name of the role’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 role’s usage.
is_markdown: A boolean flag used to indicate whether the description is 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 (RoleLanguageFeature) – The role language feature

add_target_completion_provider(provider)[source]#

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

Parameters:: provider (TargetCompletion) – The provider to register

add_target_definition_provider(provider)[source]#

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

Parameters:: provider (TargetDefinition) – The provider to register

add_target_link_provider(provider)[source]#

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

Parameters:: provider (TargetLink) – The provider to register

get_documentation(label, implementation)[source]#

Return the documentation for the given role, 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 role, as the user would type in an reStructuredText file.
implementation (str) – The full dotted name of the role’s implementation.

get_implementation(role, domain)[source]#

Return the implementation of a role given its name

Parameters:

role (str) – The name of the role.
domain (str) – The domain of the role, if applicable.

get_roles()[source]#

Return a dictionary of all known roles.

resolve_target_link(context, name, domain, label)[source]#

Resolve a given document link.

suggest_roles(context)[source]#

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

Parameters:: context (CompletionContext) – The completion context

class esbonio.lsp.roles.RoleLanguageFeature[source]#

Base class for role language features.

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

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

Parameters:

context (CompletionContext) – The completion context
name (str) – The name of the role to generate completion suggestions for.
domain (str) – The name of the domain the role is a member of

find_target_definitions(context, name, domain, label)[source]#

Return a list of locations representing the definition of the given role target.

Parameters:

doc – The document containing the match
match – The match object that triggered the definition request
name (str) – The name of the role
domain (str) – The domain the role is part of, if applicable.

get_implementation(role, domain)[source]#

Return the implementation for the given role name.

Parameters:

role (str) – The name of the role
domain (str) – The domain the role belongs to, if any

index_roles()[source]#

Return all known roles.

resolve_target_link(context, name, domain, label)[source]#

Return a link corresponding to the given target.

Parameters:

context (DocumentLinkContext) – The document link context
domain (str | None) – The name (if applicable) of the domain the role is a member of
name (str) – The name of the role to generate completion suggestions for.
label (str) – The label of the target to provide the link for

suggest_roles(context)[source]#

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

esbonio.lsp.util.patterns.ROLE#

A regular expression to detect and parse parial and complete roles.

I’m not sure if there are offical names for the components of a role, but the language server breaks a role down into a number of parts:

              vvvvvv label
             v modifier(optional)
            vvvvvvvv target
:c:function:`!malloc`
^^^^^^^^^^^^ role
   ^^^^^^^^ name
 ^ domain (optional)

The language server sometimes refers to the above as a “plain” role, in that the role’s target contains just the label of the object it is linking to. However it’s also possible to define “aliased” roles, where the link text in the final document is overriden, for example:

             vvvvvvvvvvvvvvvvvvvvvvvv alias
                                       vvvvvv label
                                      v modifier (optional)
            vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv target
:c:function:`used to allocate memory <~malloc>`
^^^^^^^^^^^^ role
   ^^^^^^^^ name
 ^ domain (optional)

See tests.test_roles.test_role_regex() for a list of example strings this pattern is expected to match.

esbonio.lsp.util.patterns.DEFAULT_ROLE#

A regular expression to detect and parse parial and complete “default” roles.

A “default” role is the target part of a normal role - but without the :name: part.

class esbonio.lsp.roles.TargetDefinition(*args, **kwargs)[source]#

A definition provider for role targets.

Deprecated since version 0.15.0: This will be removed in v1.0, use a subclass of RoleLanguageFeature instead.

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

Return a list of locations representing the definition of the given role target.

Parameters:

doc – The document containing the match
match – The match object that triggered the definition request
name (str) – The name of the role
domain (str | None) – The domain the role is part of, if applicable.

class esbonio.lsp.roles.TargetCompletion(*args, **kwargs)[source]#

A completion provider for role targets.

Deprecated since version 0.15.0: This will be removed in v1.0, use a subclass of RoleLanguageFeature instead.

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

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

Parameters:

context (CompletionContext) – The completion context
domain (str | None) – The name of the domain the role is a member of
name (str) – The name of the role to generate completion suggestions for.

class esbonio.lsp.roles.TargetLink(*args, **kwargs)[source]#

A document link provider for role targets.

Deprecated since version 0.15.0: This will be removed in v1.0, use a subclass of RoleLanguageFeature instead.

resolve_link(context, name, domain, label)[source]#

Return a link corresponding to the given target.

Parameters:

context (DocumentLinkContext) – The document link context
domain (str | None) – The name (if applicable) of the domain the role is a member of
name (str) – The name of the role to generate completion suggestions for.
label (str) – The label of the target to provide the link for