coc-esbonio

yaegassy

esbonio ([Sphinx] Python Documentation Generator) language server extension for coc.nvim

Installation CommandVim prompt

:CocInstall coc-esbonio

GitHub owner

yaegassy

Version

v0.14.4

npm package

coc-esbonio

Requirements

coc ^0.0.80

License

MIT

Repository

GitHub

npm latest published 2024-01-12Registry checked 2026-08-23Registry summary

Published Package Summary

coc-esbonio

esbonio ([Sphinx] Python Documentation Generator) language server extension for coc.nvim

Features

Completion
- The language server implements textDocument/completion and can offer suggestions in a variety of contexts.
Definition
- The language server implements textDocument/definition to provide the location of objects linked to by certain roles. Currently only the :ref: and :doc: roles are supported.
Diagnostics
- Using textDocument/publishDiagnostics the language server is able to report Sphinx errors that are reported during builds.
Document Symbols
- The language server implements textDocument/documentSymbol which powers features like the "Outline" view in coc.nvim.
Hover
- The language server implements textDocument/hover to provide easy access to documentation for roles and directives.
Implementation
- The language server implements textDocument/implementation so you can easily find the implementation of a given role or directive.
Code Action by client side feature
- Section builder feature. DEMO
- Insert link feature. DEMO
Built-in installer by client side feature
- See:
  - https://github.com/yaegassy/coc-esbonio#detect-esbonio
  - https://github.com/yaegassy/coc-esbonio#bult-in-install

Install

CocInstall:

:CocInstall coc-esbonio

vim-plug:

Plug 'yaegassy/coc-esbonio', {'do': 'yarn install --frozen-lockfile'}

Detect: esbonio

esbonio.server.pythonPath setting
Current python3 environment (e.g. venv or system global)
builtin venv/bin/python or venv/Scripts/python.exe (Installation commands are also provided)

Bult-in install

coc-esbonio allows you to create an extension-only "venv" and install "esbonio".

The first time you use coc-esbonio, if esbonio is not detected, you will be prompted to do a built-in installation.

You can also run the installation command manually.

:CocCommand esbonio.languageServer.install

TIPS

esbonio's language server can also handle python file docstrings. coc-esbonio will activate the extension when the rst file is opened. If you want coc-esbonio to work with python file as well, you must first open the rst file.

Code Actions

Example key mapping (Code Action related):

nmap <silent> ga <Plug>(coc-codeaction-line)
xmap <silent> ga <Plug>(coc-codeaction-selected)
nmap <silent> <leader>a <Plug>(coc-codeaction-cursor)

Actions:

Section builder (level1)
Section builder (level2)
Section builder (level3)
Insert Link (cursol)
Insert Inline Link (cursol)
Insert Link (selected)
Insert Inline Link (selected)

Thanks

swyddfa/esbonio

License

MIT

This extension is built with create-coc-extension

Read the complete README

esbonio ([Sphinx] Python Documentation Generator) language server extension for coc.nvim

Activation Events

onLanguage:rst

Developer Resources

Want to build, test, or contribute to coc.nvim extensions? Explore our official SDK and testing toolkits.

Open Developer Guide

This published npm package does not include a history.md or changelog.md file. Browse its npm versions or repository releases for available release information.

All contributes.commands entries from the published package manifest for coc-esbonio@0.14.4.

Command (:CocCommand)	Description
esbonio.languageServer.install	Install/Upgrade Language Server
esbonio.languageServer.restart	Restart Language Server

All contributes.configuration entries from the published package manifest, including each raw property schema for coc-settings.json.

esbonio.enableboolean

Enable coc-esbonio extension

Default: true

Raw JSON Schema

{
  "type": "boolean",
  "default": true,
  "description": "Enable coc-esbonio extension"
}

esbonio.sphinx.tagsarray

Tags to enable during a build.

Default: []

Raw JSON Schema

{
  "type": "array",
  "scope": "window",
  "default": [],
  "description": "Tags to enable during a build."
}

esbonio.sphinx.quietboolean

Hide standard Sphinx output messages

Default: false

Raw JSON Schema

{
  "type": "boolean",
  "scope": "window",
  "default": false,
  "description": "Hide standard Sphinx output messages"
}

esbonio.trace.serverstring

Traces the communication between coc.nvim and the esbonio language server.

Default: "off"

Raw JSON Schema

{
  "enum": [
    "off",
    "messages",
    "verbose"
  ],
  "type": "string",
  "default": "off",
  "description": "Traces the communication between coc.nvim and the esbonio language server."
}

esbonio.sphinx.silentboolean

Hide all Sphinx output

Default: false

Raw JSON Schema

{
  "type": "boolean",
  "scope": "window",
  "default": false,
  "description": "Hide all Sphinx output"
}

esbonio.sphinx.srcDirstring

The directory containing your rst source files. By default the Language Server will assume this is the same as `#esbonio.sphinx.confDir#` but this opton can override this if necessary.

Default: ""

Raw JSON Schema

{
  "type": "string",
  "scope": "window",
  "default": "",
  "description": "The directory containing your rst source files. By default the Language Server will assume this is the same as `esbonio.sphinx.confDir` but this opton can override this if necessary.",
  "markdownDescription": "The directory containing your rst source files. By default the Language Server will assume this is the same as `#esbonio.sphinx.confDir#` but this opton can override this if necessary."
}

esbonio.server.enabledboolean

Enable/Disable the language server

Default: true

Raw JSON Schema

{
  "type": "boolean",
  "scope": "window",
  "default": true,
  "description": "Enable/Disable the language server"
}

esbonio.sphinx.confDirstring

The Language Server should be able to automatically find the folder containing your project's 'conf.py' file. However this setting can be used to force the Language Server to use a particular directory if required.

Default: ""

Raw JSON Schema

{
  "type": "string",
  "scope": "window",
  "default": "",
  "description": "The Language Server should be able to automatically find the folder containing your project's 'conf.py' file. However this setting can be used to force the Language Server to use a particular directory if required."
}

esbonio.sphinx.numJobsinteger

The number of parallel jobs to use during a Sphinx build. - A value of `0` is equivalent to passing `-j auto` to a `sphinx-build` command. - A value of `1` will disable parallel processing.

Default: 1

Raw JSON Schema

{
  "type": "integer",
  "scope": "window",
  "default": 1,
  "markdownDescription": "The number of parallel jobs to use during a Sphinx build.\n\n- A value of `0` is equivalent to passing `-j auto` to a `sphinx-build` command.\n- A value of `1` will disable parallel processing."
}

esbonio.server.logLevelstring

The level of log message to show in the log

Default: "error"

Raw JSON Schema

{
  "enum": [
    "debug",
    "info",
    "error"
  ],
  "type": "string",
  "scope": "application",
  "default": "error",
  "description": "The level of log message to show in the log"
}

esbonio.sphinx.buildDirstring

The directory in which to store Sphinx's build output. By default the Language Server will store any build files in a storage area provided by coc.nvim, this option allows you to override this to be a directory of your choosing e.g. your local `_build/` directory.

Default: null

Raw JSON Schema

{
  "type": "string",
  "scope": "window",
  "default": null,
  "description": "The directory in which to store Sphinx's build output.\n\nBy default the Language Server will store any build files in a storage area provided by coc.nvim, this option allows you to override this to be a directory of your choosing e.g. your local _build/ directory.",
  "markdownDescription": "The directory in which to store Sphinx's build output.\n\nBy default the Language Server will store any build files in a storage area provided by coc.nvim, this option allows you to override this to be a directory of your choosing e.g. your local `_build/` directory."
}

esbonio.sphinx.makeModeboolean

Flag indicating if the language server should be have like a sphinx-build -M ... command

Default: true

Raw JSON Schema

{
  "type": "boolean",
  "scope": "window",
  "default": true,
  "description": "Flag indicating if the language server should be have like a sphinx-build -M ... command"
}

esbonio.server.logFilterarray

A list of logger names to limit output from

Default: null

Raw JSON Schema

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "scope": "application",
  "default": null,
  "description": "A list of logger names to limit output from"
}

esbonio.sphinx.keepGoingboolean

Continue building when errors generated from warnings are encountered

Default: false

Raw JSON Schema

{
  "type": "boolean",
  "scope": "window",
  "default": false,
  "description": "Continue building when errors generated from warnings are encountered"
}

esbonio.sphinx.verbosityinteger

The verbosity of Sphinx's output

Default: 0

Raw JSON Schema

{
  "type": "integer",
  "scope": "window",
  "default": 0,
  "description": "The verbosity of Sphinx's output"
}

esbonio.server.pythonPathstring

The path to the Python interpreter to use when running the Langague Server. By default this extension will try to use the interpreter configured via the Python Extension. If you do not use the Python Extension or you wish to use a different environment, then this option can be used to override the default behavior.

Default: ""

Raw JSON Schema

{
  "type": "string",
  "scope": "window",
  "default": "",
  "description": "The path to the Python interpreter to use when running the Langague Server.\n\nBy default this extension will try to use the interpreter configured via the Python Extension. If you do not use the Python Extension or you wish to use a different environment, then this option can be used to override the default behavior."
}

esbonio.sphinx.doctreeDirstring

The directory in which to store Sphinx's doctree cache.

Default: null

Raw JSON Schema

{
  "type": "string",
  "scope": "window",
  "default": null,
  "description": "The directory in which to store Sphinx's doctree cache."
}

esbonio.sphinx.builderNamestring

The builder to use when building the documentation. **Note:** While many builders will work fine, many features (such as previews) will only work with the `html` builder.

Default: "html"

Raw JSON Schema

{
  "type": "string",
  "scope": "window",
  "default": "html",
  "description": "The builder to use when building the documentation.",
  "markdownDescription": "The builder to use when building the documentation. **Note:** While many builders will work fine, many features (such as previews) will only work with the `html` builder."
}

esbonio.server.startupModulestring

The module (or script) to use to launch the server.

Default: "esbonio"

Raw JSON Schema

{
  "type": "string",
  "scope": "window",
  "default": "esbonio",
  "description": "The module (or script) to use to launch the server."
}

esbonio.sphinx.forceFullBuildboolean

Force a full build of the documentation project on server startup.

Default: false

Raw JSON Schema

{
  "type": "boolean",
  "scope": "window",
  "default": false,
  "description": "Force a full build of the documentation project on server startup."
}

esbonio.sphinx.warningIsErrorboolean

Treat any warnings as errors.

Default: false

Raw JSON Schema

{
  "type": "boolean",
  "scope": "window",
  "default": false,
  "description": "Treat any warnings as errors."
}

esbonio.server.excludedModulesarray

A list of modules to exclude from the server's configuration

Default: []

Raw JSON Schema

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "scope": "window",
  "default": [],
  "description": "A list of modules to exclude from the server's configuration"
}

esbonio.server.includedModulesarray

A list of additional modules to include in the server's configuration

Default: []

Raw JSON Schema

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "scope": "window",
  "default": [],
  "description": "A list of additional modules to include in the server's configuration"
}

esbonio.sphinx.configOverridesobject

Any conf.py options to override.

Default: {}

Raw JSON Schema

{
  "type": "object",
  "scope": "window",
  "default": {},
  "description": "Any conf.py options to override."
}

esbonio.server.enabledInPyFilesboolean

Enable/Disable the language server in Python files.

Default: true

Raw JSON Schema

{
  "type": "boolean",
  "scope": "window",
  "default": true,
  "description": "Enable/Disable the language server in Python files."
}

esbonio.server.hideSphinxOutputboolean

Hide Sphinx build output from the Language Server log.

Default: false

Deprecated: This option will be removed when the language server reaches v1.0. The esbonio.sphinx.quiet and esbonio.sphinx.silent options should be used instead.

Raw JSON Schema

{
  "type": "boolean",
  "scope": "application",
  "default": false,
  "description": "Hide Sphinx build output from the Language Server log.",
  "deprecationMessage": "This option will be removed when the language server reaches v1.0. The esbonio.sphinx.quiet and esbonio.sphinx.silent options should be used instead."
}

esbonio.enableFixDirectiveCompletionboolean

Enable fix patch for `Directive` completion issue

Default: true

Raw JSON Schema

{
  "type": "boolean",
  "default": true,
  "description": "Enable fix patch for `Directive` completion issue"
}

esbonio.client.sectionCharacterLevel1string

Character to be used in the Section builder (level1) of the code action

Default: "="

Raw JSON Schema

{
  "enum": [
    "=",
    "-",
    ":",
    "~",
    ".",
    "^",
    "_",
    "*",
    "+",
    "#",
    "\"",
    "'",
    "`"
  ],
  "type": "string",
  "default": "=",
  "description": "Character to be used in the Section builder (level1) of the code action"
}

esbonio.client.sectionCharacterLevel2string

Character to be used in the Section builder (level2) of the code action

Default: "-"

Raw JSON Schema

{
  "enum": [
    "=",
    "-",
    ":",
    "~",
    ".",
    "^",
    "_",
    "*",
    "+",
    "#",
    "\"",
    "'",
    "`"
  ],
  "type": "string",
  "default": "-",
  "description": "Character to be used in the Section builder (level2) of the code action"
}

esbonio.client.sectionCharacterLevel3string

Character to be used in the Section builder (level3) of the code action

Default: "~"

Raw JSON Schema

{
  "enum": [
    "=",
    "-",
    ":",
    "~",
    ".",
    "^",
    "_",
    "*",
    "+",
    "#",
    "\"",
    "'",
    "`"
  ],
  "type": "string",
  "default": "~",
  "description": "Character to be used in the Section builder (level3) of the code action"
}

esbonio.server.showDeprecationWarningsboolean

Developer flag to enable deprecation warnings.

Default: false

Raw JSON Schema

{
  "type": "boolean",
  "scope": "window",
  "default": false,
  "description": "Developer flag to enable deprecation warnings."
}

esbonio.server.completion.preferredInsertBehaviorstring

Indicate to the server how you would prefer completions to behave when accepted.

Default: "replace"

Raw JSON Schema

{
  "enum": [
    "insert",
    "replace"
  ],
  "type": "string",
  "scope": "window",
  "default": "replace",
  "description": "Indicate to the server how you would prefer completions to behave when accepted.",
  "enumDescriptions": [
    "Completions will only append to existing text. Server will only provide suggestions compatible with existing text.",
    "Completions will replace existing text, allowing for complete rewrites of existing items. Server will respond with all valid options."
  ]
}

coc-esbonio

Published Package Summary

coc-esbonio

Features

Install

Detect: esbonio

Bult-in install

TIPS

Code Actions

Thanks

License

Version History

Contributed Commands

Configuration Schema