Features

Autocompletion of title adornments

Sections reported as symbols in the editor outline

Comparison to other projects

rst-mode is part of the docutils project. It provides a lot of rst-related functionality, such as operations on text blocks or helpers for indentation and section titles. However, rst-mode is exclusive to Emacs.

chrisjsewell/rst-language-server is much more fully featured than this project. It provides diagnostic messages, navigation to references and definitions etc.

However, there seems to be no versioning, releases, or packages that can be simply installed by a user. Moreover, Chris’s implementation targets Visual Studio Code only, whereas this project tries to support various editors.

lextm/restructuredtext-antlr was an attempt to use ANTLR to parse reStructuredText into a custom syntax tree. The project is discontinued and archived.

RST Language Server relies on docutils for parsing and its Abstract Syntax Tree.

Installation and Setup

RST Language Server is available as a package on PyPI and can be installed via pip:

$ pip install --user rst-language-server

{
    "servers": {
        "rst": {
            "command": ["rst-ls", "--client-insert-text-interpretation=false"],
            "highlightingModeRegex": "^reStructuredText$"
        }
    }
}

-- Register rst-ls with lspconfig
local configs = require "lspconfig/configs"
local util = require "lspconfig/util"

configs.rst_language_server = {
  default_config = {
    cmd = { "rst-ls" },
    filetypes = { "rst" },
    root_dir = util.path.dirname,
  },
  docs = {
    description = [[
https://github.com/digitalernachschub/rst-language-server
Server implementation of the Language Server Protocol for reStructuredText.
]],
    default_config = {
      root_dir = [[root_pattern(".git")]],
    },
  },
}

(with-eval-after-load 'lsp-mode
  (add-to-list 'lsp-language-id-configuration
    '(rst-mode . "rst")))

(defcustom lsp-rst-ls-command '("rst-ls")
  "Command to start the RST Language Server."
  :type 'string)

(require 'lsp-mode)

(lsp-register-client
  (make-lsp-client :new-connection (lsp-stdio-connection (lambda () lsp-rst-ls-command))
                   :major-modes '(rst-mode)
                   :server-id 'rst-ls))

Is my editor supported?

RST Language Server can be used with any text editor that implements a Language Client. See this list of Language Client implementations.

Development configuration with Kate

The RST Language Server is executed as a subprocess of the Language Client. Therefore, if we want to see log output in Kate we need to write the logs to a file using the –log-file command line option. We also set the log level to debug in order to view the JSON-RPC messages exchanged between client and server. Lastly, we configure the root (i.e. the working directory of the executed command) to the directory where our source code lives in and use poetry run to execute the code in the Git repository:

{
    "servers": {
        "rst": {
            "command": ["poetry", "run", "rst-ls", "--log-file=/tmp/rst-ls.log", "--log-level=debug", "--client-insert-text-interpretation=false"],
            "root": "/path/to/rst-language-server-repo",
            "highlightingModeRegex": "^reStructuredText$"
        }
    }
}