sphinx.nvim

Sphinx integrations for Neovim.

This plugin is still under development, many things may and will change.

Contents

• Installation
• Available integrations
  • coc.nvim
  • nvim-treesitter
  • fzf
• Coming soon
• Configuration

Installation

Install using vim-plug. Put this in your init.vim.

Plug 'stsewd/sphinx.nvim', { 'do': ':UpdateRemotePlugins' }

Available integrations

coc.nvim

Source for cross-referencing roles, i.e :ref:, :doc:, py:func, etc.

Note: this plugin makes use of the inventory file from Sphinx, so you need to have built your docs at least once to get suggestions, and rebuild when your docs change to get the up to date suggestions. You can use sphinx-autobuild to rebuild your docs automatically when there is a change.

fzf

• List and open files with SphinxFiles.
• List all references with :SphinxRefs or :SphinxRefs {role-name} (tab completion supported!). Copy the reference name with Enter or copy the link with Ctrl-F (they are copied to the default register ", just press p to paste).

Note If you have fzf.vim installed, this plugin will respect your g:fzf_command_prefix setting.

nvim-treesitter

Extra queries for rst. This includes highlights for Sphinx directives and roles, and injections for directives from Sphinx and popular extensions (like code-block or tabs).

Coming soon

• Completion for roles and directives names.

Configuration

Default values are shown in the code blocks.

General settings

g:sphinx_default_role

Default role (words surrounded by `single back-quotes`).

let g:sphinx_default_role = 'any'

g:sphinx_html_output_dirs

Where to search for the local inventory file (objects.inv). The directories are relative to the conf.py file.

let g:sphinx_html_output_dirs = [
      \ '_build/html', 'build/html',
      \ '../_build/html', '../build/html',
      \ '_build/dirhtml', 'build/dirhtml',
      \ '../_build/dirhtml', '../build/dirhtml',
      \]

g:sphinx_default_dirs

If you want to extend the defaults values from g:sphinx_html_output_dirs and g:sphinx_doctrees_output_dirs instead of replacing them.

let g:sphinx_default_dirs = 1

Intersphinx related settings

g:sphinx_include_intersphinx_data

If results should include information from Intersphinx.

let g:sphinx_include_intersphinx_data = 1

g:sphinx_doctrees_output_dirs

Where to search for the environment file (environment.pickle), this file contains the inventories from Intersphinx. The directories are relative to the conf.py file.

let g:sphinx_doctrees_output_dirs = [
      \ '_build/doctrees', 'build/doctrees',
      \ '../_build/doctrees', '../build/doctrees',
      \ '_build/html/.doctrees', 'build/html/.doctrees',
      \ '../_build/html/.doctrees', '../build/html/.doctrees',
      \ '_build/dirhtml/.doctrees', 'build/dirhtml/.doctrees',
      \ '../_build/dirhtml/.doctrees', '../build/dirhtml/.doctrees',
      \]

g:sphinx_always_use_scoped_targets

Always prefix the reference with the name of the target, i.e use :ref:`<python:comparisons>` instead of :ref:`<comparisons>` to link to the label “comparisons” in the doc set “python”.

let g:sphinx_always_use_scoped_targets = 1