From 5de2784a9e6c6e39a11551de6c6840624205f16a Mon Sep 17 00:00:00 2001 From: Alex Carney Date: Thu, 14 Sep 2023 10:50:55 +0100 Subject: [PATCH] docs: Create a dedicated nvim + lspconfig guide --- docs/lsp/configuration.rst | 2 +- docs/lsp/editors/_installation.rst | 6 ++ docs/lsp/editors/nvim-lspconfig.rst | 74 +++++++++++++++++++ .../editors/nvim-lspconfig/_configuration.rst | 16 ---- .../lsp/editors/nvim-lspconfig/_debugging.rst | 10 --- docs/lsp/editors/nvim-lspconfig/_examples.rst | 17 ----- .../editors/nvim-lspconfig/_installation.rst | 25 ------- docs/lsp/getting-started.rst | 5 ++ 8 files changed, 86 insertions(+), 69 deletions(-) create mode 100644 docs/lsp/editors/nvim-lspconfig.rst delete mode 100644 docs/lsp/editors/nvim-lspconfig/_configuration.rst delete mode 100644 docs/lsp/editors/nvim-lspconfig/_debugging.rst delete mode 100644 docs/lsp/editors/nvim-lspconfig/_examples.rst delete mode 100644 docs/lsp/editors/nvim-lspconfig/_installation.rst diff --git a/docs/lsp/configuration.rst b/docs/lsp/configuration.rst index dec5f98bd..cc80c719a 100644 --- a/docs/lsp/configuration.rst +++ b/docs/lsp/configuration.rst @@ -14,7 +14,7 @@ The following options control the creation of the Sphinx application object mana The ``sphinx-build`` command to use when invoking the Sphinx subprocess. -.. confval:: esbonio.sphinx.pythonCommand (string []) +.. confval:: esbonio.sphinx.pythonCommand (string[]) The command to use when launching the Python interpreter for the process hosting the Sphinx application. Use this to select the Python environment you want to use when building your documentation. diff --git a/docs/lsp/editors/_installation.rst b/docs/lsp/editors/_installation.rst index 30a4e36e9..e99899845 100644 --- a/docs/lsp/editors/_installation.rst +++ b/docs/lsp/editors/_installation.rst @@ -7,6 +7,12 @@ The language server can be installed using pip, or if you prefer, conda. $ pip install esbonio + + .. tip:: + + Use `pipx `__ + to have an isolated, easy to upgrade installation of the language server that you can reuse across projects. + If you want to try the latest developments before they are released you can use ``pip`` to install from the development branch. .. code-block:: console diff --git a/docs/lsp/editors/nvim-lspconfig.rst b/docs/lsp/editors/nvim-lspconfig.rst new file mode 100644 index 000000000..78066894e --- /dev/null +++ b/docs/lsp/editors/nvim-lspconfig.rst @@ -0,0 +1,74 @@ +Neovim (nvim-lspconfig) +======================= + +.. figure:: /images/nvim-lspconfig.png + :align: center + + Using esbonio with Neovim's built in language client + +This guide covers how to setup ``esbonio`` with Neovim's built-in language client. + +.. highlight:: none + +Installation +------------ + +.. include:: ./_installation.rst + + +Configuration +------------- + +`Basic configuration `__ +for the language server is available through the +`nvim-lspconfig `_ +plugin. + + +Configuration settings are provided via the ``settings`` table passed to ``lspconfig.esbonio.setup {}``. +Perhaps the most important setting is :confval:`esbonio.sphinx.pythonCommand (string[])` which tells the server which Python envrionment to use when building your documentation. + +Another important setting is :confval:`esbonio.sphinx.buildCommand (string[])` which tells the server the command you use to build your documentation. + +.. code-block:: lua + + lspconfig.esbonio.setup { + settings = { + sphinx = { + pythonCommand = { "/path/to/project/.venv/bin/python" }, + buildCommand = { "sphinx-build", "-M", "html", "docs", "docs/_build" }, + } + } + +See :ref:`lsp-configuration` for a complete reference of all configuration options supported by the server. + +Examples +-------- + +.. admonition:: Do you use Nix? + + If you have the `Nix `__ package manager on your machine you can try out our example configuration with the following command:: + + nix run github:swyddfa/esbonio/beta#nvim-lspconfig + +To try the example configuration on your machine. + +#. Download :download:`init.vim ` to a folder of your choosing. +#. Ensure you have the `nvim-lspconfig`_ plugin installed. +#. Open a terminal in the directory containing this file and run the following command to load this config isolated from your existing configuration:: + + nvim -u init.vim + +Troubleshooting +--------------- + +You will also have to increase the LSP logging level in Neovim itself. + +.. code-block:: vim + + lua << EOF + vim.lsp.set_log_level("debug") + EOF + +You can then open the log file with the command ``:LspLog``. +See `here `_ for more details. diff --git a/docs/lsp/editors/nvim-lspconfig/_configuration.rst b/docs/lsp/editors/nvim-lspconfig/_configuration.rst deleted file mode 100644 index 7d4fe67b2..000000000 --- a/docs/lsp/editors/nvim-lspconfig/_configuration.rst +++ /dev/null @@ -1,16 +0,0 @@ -The language server's configuration options are passed as ``init_options`` during the server's setup e.g. - -.. code-block:: lua - - lspconfig.esbonio.setup { - init_options = { - server = { - logLevel = "debug" - }, - sphinx = { - confDir = "/path/to/docs", - srcDir = "${confDir}/../docs-src" - } - } - -Here are all the options supported by the server. diff --git a/docs/lsp/editors/nvim-lspconfig/_debugging.rst b/docs/lsp/editors/nvim-lspconfig/_debugging.rst deleted file mode 100644 index f96fb10d2..000000000 --- a/docs/lsp/editors/nvim-lspconfig/_debugging.rst +++ /dev/null @@ -1,10 +0,0 @@ -You will also have to increase the LSP logging level in Neovim itself. - -.. code-block:: vim - - lua << EOF - vim.lsp.set_log_level("debug") - EOF - -You can then open the log file with the command ``:lua vim.cmd('e'..vim.lsp.get_log_path())``. -See `here `_ for more details. diff --git a/docs/lsp/editors/nvim-lspconfig/_examples.rst b/docs/lsp/editors/nvim-lspconfig/_examples.rst deleted file mode 100644 index 2918c639e..000000000 --- a/docs/lsp/editors/nvim-lspconfig/_examples.rst +++ /dev/null @@ -1,17 +0,0 @@ -To try the example configuration on your machine. - -#. Download :download:`init.vim ` to a folder - of your choosing. -#. Ensure you have vim-plug's ``plug.vim`` file installed in your autoload - directory. See - `this guide `_ for - details. -#. Open a terminal in the directory containing this file and run the - following command to load this config isolated from your existing - configuration:: - - nvim -u init.vim - -#. Install the ``nvim-lspconfig`` plugin:: - - :PlugInstall diff --git a/docs/lsp/editors/nvim-lspconfig/_installation.rst b/docs/lsp/editors/nvim-lspconfig/_installation.rst deleted file mode 100644 index 03696da0a..000000000 --- a/docs/lsp/editors/nvim-lspconfig/_installation.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. highlight:: none - -Basic configuration for the language server is provided through the -`nvim-lspconfig `_ plugin - -.. literalinclude:: ./editors/nvim-lspconfig/init.vim - :language: vim - :start-at: set expandtab - -As mentioned above the language server works best -when it's run from the same Python environment as the one used to build your documentation. The -easiest way to make sure ``nvim`` uses the right Python interpreter, is to activate your environment -before launching ``nvim``:: - - $ source .env/bin/activate - (.env) $ nvim - -Alternatively, you can change the default command to launch the language sever with a particular -interpreter - -.. code-block:: lua - - lspconfig.esbonio.setup { - cmd = { '/path/to/virtualenv/bin/python', '-m', 'esbonio' } - } diff --git a/docs/lsp/getting-started.rst b/docs/lsp/getting-started.rst index 6741c36ea..73bf9b283 100644 --- a/docs/lsp/getting-started.rst +++ b/docs/lsp/getting-started.rst @@ -38,6 +38,11 @@ This section contains notes on how to use the language server with your text edi :link-type: doc :text-align: center + .. grid-item-card:: Neovim (nvim-lspconfig) + :link: editors/nvim-lspconfig + :link-type: doc + :text-align: center + .. grid-item-card:: Sublime Text :link: editors/sublime :link-type: doc