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.
• Document Symbols
  • The language server implements textDocument/documentSymbol which powers features like the “Outline” view in coc.nvim.
• Diagnostics
  • Using textDocument/publishDiagnostics the language server is able to report Sphinx errors that are reported during builds.
• Goto 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.
• 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

1. esbonio.server.pythonPath setting
2. Current python3 environment (e.g. venv or system global)
3. 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.

:CocComannd esbonio.languageServer.install

Activation Events

• "onLanguage:rst"
• "workspaceContains:**/conf.py"

Configuration options

• esbonio.enable: Enable coc-esbonio extension, default: true
• esbonio.client.sectionCharacterLevel1: Character to be used in the Section builder (level1) of the code action, default: "=",
• esbonio.client.sectionCharacterLevel2: Character to be used in the Section builder (level2) of the code action, default: "-",
• esbonio.client.sectionCharacterLevel3: Character to be used in the Section builder (level3) of the code action, default: "~",
• esbonio.server.enabled: Enable/Disable the language server, default: true
• esbonio.server.pythonPath: 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: ""
• esbonio.server.logLevel: The level of log message to show in the log, default: "error"
• esbonio.server.logFilter: A list of logger names to limit output from, type: array, default: null
• esbonio.server.hideSphinxOutput: Hide Sphinx build output from the Language Server log, default: false
• esbonio.sphinx.buildDir: 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
• esbonio.sphinx.confDir: 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: ""
• esbonio.sphinx.srcDir: 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: ""

Commands

• esbonio.languageServer.install: Install/Upgrade Language Server
• esbonio.languageServer.restart: Restart Language Server

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)

Other Vim plugins for sphinx

• stsewd/sphinx.nvim

Thanks

• swyddfa/esbonio

License

MIT

---

This extension is built with create-coc-extension