Offering a completions for the :doc: role need a little more intelligence behind them. Consider the following hierarchy

docs
|- a
|   |- x.rst
|   \- y.rst
\- b
    \- z.rst

Typing :doc:`b/z` in a/x.rst will result in Sphinx not being able to resolve the reference.
It either needs to be

• a relative reference to the a/x.rst file (:doc:`../b/z` )
• an "absolute" reference, relative to the project's conf.py (:doc:`/b/z` )

The insert_text for the target's CompletionItem needs to be tweaked to fix this

When the LSP is first initialized, the workspace root is sent over as a URI. In VSCode's case at least this means directory labels are url encoded C: -> C%3A and there is an extra leading '/' character.

This appears to cause pathlib some problems and crashes the server.

Otherwise the server cannot refresh properly when changes are made to the configuration

If all else fails and the "auto-detect the conf.py" logic isn't smart enough to determine the correct file. It should be possible for clients to force the path to use via a config option

Currently the language server does have general support for Sphinx domains. There are a number of places where support has been hardcoded for the std and python domains.

There are a number of things we need in order to claim "proper" support

• Being able to suggest roles and directives for all domains under the correct prefix (#101, #104)
• Respect the primary_domain setting (#101, #104)
• Ensure the intersphinx completions support domains (#106)

The language server requires Python 3.6+, it would be good to ensure that the configured Python environment matches this and warn the user if it does not

• ale?, perhaps this could be used as a starting point?
• coc.nvim See this comment
• neovim's built-in LSP client
• vim-lsp See this comment

When restarting the Language Server in VSCode the Output window switches to another entry - but the content remains...
Add a check to the restart logic to see if the LSP's output window was selected and auto select the new instance's output if that's the case

For example the reference :ref:`not-a-valid-reference` is not flagged as an issue
Not sure if this should be solved by running more of the Sphinx build process (current we only read the sources) or if there should be a dedicated feature that checks for this kind of thing

If nothing else, it should make development workflows nicer.

• If Sphinx throws an error while building, the language server does not report it.
• This subsequently prevents the Language Server from offering any help to the user.

Will result in a smaller packaged extension

I recently tried the language server in a project that contained a number of virtualenvs under a .tox directory in the root of the project. One of these envs happened to contain a conf.py file that was discovered before the conf.py that should've been chosen.

One quick fix would be to ignore conf.py files that live under certain directories e.g. .tox, site-packages etc

It would be good to ensure we don't include anything that's not necessary in the packaged extension

It appears that they are off by one

Now that the Language Client is listening to changes in Python files, we need the server to notice a change in conf.py and have it create a new app and re-index everything

This will allow us to catch broken links etc as they happen

• There are a number of situations where a user may be referencing a file, it would be good to offer completion suggestions
  • figure:: <filename>
  • include:: <filename>
  • image:: <filename>
  • literalinclude:: <filename>
  • :download:`<filename>`
  • toctree:: entries (Now in #151)

While #51 technically resolved #33, all it does is send a notification saying "Hey, something went wrong".
It would be good if the language server could report what the problem actually was, preferably publishing it as a diagnostic

We already have towncrier generating a CHANGES.rst that we commit to the repo and will eventually pull into the docs. However to populate the changelog tab in VSCode, it looks like we need a CHANGELOG.md file.

It should be enough to have it present at the time of calling vsce package/publish, without committing it to the repo

As of nbformat v5.1 cells now require mandatory id fields which broke the tests around the nbtutorial Sphinx extension. Currently this has been worked around by pinning the version of nbformat we depend on to be <5.1. At some point it will be worth finding out what the idea behind this id field is, and figure out the best way to make use of it.

Using something like "workspaceContains:conf.py" in our activation events should do it

Failed to handle notification $/setTraceNotification: Object(value='off')
Traceback (most recent call last):
  File "/home/alex/Projects/esbonio/.env/lib/python3.8/site-packages/pygls/protocol.py", line 309, in _get_handler
    return self.fm.builtin_features[feature_name]
KeyError: '$/setTraceNotification'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/alex/Projects/esbonio/.env/lib/python3.8/site-packages/pygls/protocol.py", line 312, in _get_handler
    return self.fm.features[feature_name]
KeyError: '$/setTraceNotification'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/alex/Projects/esbonio/.env/lib/python3.8/site-packages/pygls/protocol.py", line 337, in _handle_notification
    handler = self._get_handler(method_name)
  File "/home/alex/Projects/esbonio/.env/lib/python3.8/site-packages/pygls/protocol.py", line 314, in _get_handler
    raise JsonRpcMethodNotFound.of(feature_name)
pygls.exceptions.JsonRpcMethodNotFound

I think it should be possible for us to provide even a dummy implementation to suppress this

The language server can now offer completions for directives themselves. but it would be good to take that further to cover

• A directive's arguments (#58)
• A directive's options (#78)
• The actual directive's documentation (#284)

The grammar incorrectly sees this as a comment

default_role allows "naked references" e.g. `example.func` to have a role automatically applied to them

When restarting the language server, clear the output to the existing window to make it clear that the action has taken place.

• One easy way to start publishing diagnostics to the Language client would be to parse the errors that Sphinx spits out when it does a build.

• prompt, prompt before updating
• auto, automatically install updates

never, monthly, weekly, daily

This is so that the client can control the verbosity of the log output

There's basic install prompts now in place in the extension. However it's clear the logic needs a lot of refinement so that it's more useful. It would be good if we can test this somehow as its expanded upon

When working on a document they user may want to insert links to other sites using a URL. It would be nice if there way a way to highlight some text, do some key combo and have the extension automatically do the link syntax. Either inline

`some text <https://...>`_

Or as a named reference

`somte text`_

.. _some text: https://...

See the leading space? According to the documentation this is invalid markup and therefore should not be highlighted as a code literal.

I assume that the grammar has similar issues for italics and bold also

https://github.com/alcarney/esbonio/blob/4759db6f15c0549e44acb234287297b07518e37f/lib/esbonio/esbonio/lsp.py#L81-L84

If someone installs the vscode extension and the python package is not installed, the extension should prompt to install it using the configured python

The way directive options for the autoxxxx family of directives are registered does not fit into the "standard" way options are handled and so the language server does not know what they are. Is there an easy way to figure out what options they accept?

I think it's useful to have the ability to use a python that's potentially different from the active python project (or there may not be a python project at all!)

However I think by default the extension should use the configured python.pythonPath option - if available.

Intersphinx is amazing, however it can be difficult/tedious to figure out what the references are called. It would be great if we could offer completion suggestions for them

e.g.

checking consistency... /home/alex/Projects/esbonio/docs/lsp/editors/vscode_changelog.rst: WARNING: document isn't included in any toctree