Roles¶

This page provides an overview of the features Esbonio provides to make working with reStructuredText Roles easier.

Completion¶

The most obvious feature is the completion suggestions, try inserting a :ref: role on the next line that links to the rst-roles-completion label defined above.

In addition to :ref: labels, esbonio supports suggesting values for manny other types of target

Local docnames for the doc role
Local filenames for the download role
Python objects for roles like py:class, py:func and more!
Targets defined in other Sphinx documentation sites for the external role! See sphinx.ext.intersphinx – Link to other projects’ documentation for more details

Feel free to experiment with each of the roles mentioned above!

Document Links¶

Many text editors will automatically detect links to webpages e.g. https://sphinx-doc.org and make them clickable. The textDocument/documentLink request allows language servers to do the same.

When it makes sense to, esbonio will add clickable links to many role targets, including

Local docname references
Local files ./roles.rst
Intersphinx references e.g. Exceptions raised during logging

See for yourself by Ctrl+Clicking one of the above references

GoTo …¶

… Definition¶

Esbonio supports GoTo Definition requests for role targets, including

Local files ./roles.rst
Documents Roles
References Completion
Python objects counters.pattern.PatternCounter

Try invoking GoTo Definition on any of the above targets

Hover¶

Esbonio provides documentation hovers for role targets, including

Local Python objects, for example

Hover over any of the above targets to see their associated content