docs: Create a dedicated nvim + lspconfig guide

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.

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 <https://pypa.github.io/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

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 <https://github.com/neovim/nvim-lspconfig/blob/master/lua/lspconfig/server_configurations/esbonio.lua>`__
+for the language server is available through the
+`nvim-lspconfig <https://github.com/neovim/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 <https://nixos.org/>`__ 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 <nvim-lspconfig/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 <https://github.com/neovim/nvim-lspconfig/#troubleshooting>`_ for more details.

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