Esbonio VS Code Reviewer's Guide

[lextm]

I think it is crucial to give all users a starting point when they first install this extension and want to make sure they know how to use each of the features. Thus, I am writing this guide as an introduction for new users. You can later incorporate the contents to Esbonio documentation if needed. It should be easier to understand than the migration article.

Environment Setup

• macOS 15.0
• VS Code 1.93.1
• Esbonio extension 0.95.2

Demo Source Code

1. Clone from https://github.com/swyddfa/esbonio.git to your local drive (mine is /Users/lextm/esbonio).
2. Open the demo directory (mine is /Users/lextm/esbonio/lib/esbonio/tests/workspaces/demo).

Preparation

Now Esbonio VS Code extension requires many settings to be manually configured instead of automatic detecting, and the demo source code only has one setting in pyproject.toml:

[tool.esbonio.sphinx]
buildCommand = ["sphinx-build", "-M", "dirhtml", ".", "./_build"]

This is not enough, and Esbonio won't work as expected yet.

Virtual Environment

I choose Pyenv and Pipenv to prepare the virtual environment:

pyenv local 3.12
pipenv install "sphinx>=7.0.0,<8.0.0" sphinx-design myst-parser furo
pipenv --venv

Sphinx 8 wasn't yet supported by Esbonio right now. Others are dependencies of this demo project. (Tracked in #890)

Note that you must use Python 3.9+ as older Python releases are no longer supported.

Also note that esbonio isn't used as a dependency in this virtual environment because the extension itself bundles a version of esbonio already. So, if you used to install esbonio with your virtual environment, delete it there to avoid conflicts.

In VS Code, open conf.py and select this pipenv environment (mine is /Users/lextm/.local/share/virtualenvs/demo-2cFbohxa).

Extra Esbonio Settings

Now you need to configure other Esbonio settings:

1. Create .vscode/settings.json
2. In its content, use

   {
     "esbonio.logging.level": "debug",
     "esbonio.sphinx.pythonCommand": ["/Users/lextm/.local/share/virtualenvs/demo-2cFbohxa/bin/python"],
   }

I prefer putting settings in VS Code settings file due to IntelliSense instead of pyproject.toml.

esbonio.server.pythonPath might be useful in rare cases, but usually you should remove it.

Testing

Now it's time to play with Esbonio features, such as live preview and sync scrolling.

Live Preview

1. Open a source file, like rst/domains/python.rst.
2. Click "Preview Documentation" button on the right top corner of the opened file section.
3. (Resize VS Code if needed) scroll the previewed contents and see how the source file scrolled along too.

If you scroll the source code, the preview contents don't follow. (Tracked in #875)

Auto Completion

1. Open any .rst file, and add

   :doc:`/`

2. Place the cursor behind / and trigger auto completion.

3. Select a suggested item from the popup list.

Typical Errors

No Applicable Project

The actual error messages might occur when you try to preview a file.

[esbonio.ProjectManager] No applicable project for uri: file:///Users/lextm/esbonio/lib/esbonio/tests/workspaces/demo/rst/roles.rst

You might review esbonio.sphinx.pythonCommand to make sure it is correctly configured.

[alcarney]

Thanks for writing these up, I keep meaning to put something like this together in #665... 😅
Just a couple of notes/thoughts

Clone from https://github.com/swyddfa/esbonio.git to your local drive

There is a repo containing just the demo code at https://github.com/swyddfa/esbonio-demo, with a scheduled job to keep in sync with the main copy in this repo.

"esbonio.sphinx.pythonCommand": ["/Users/lextm/.local/share/virtualenvs/demo-2cFbohxa/bin/python"]

Does it work if you change it to ["pipenv", "run", "python"]? If so we could update this page to also mention pipenv

esbonio.server.pythonPath is somehow necessary.

It shouldn't be... are you running into issues with it unset?

[lextm]

Thanks for the hints. I need to find a clean machine to restart and record more errors. Then I will go back and update this.

[FrightRisk]

Isn't this valueError what I am reporting in the other issue? What is "properly configured" for the esbonio.server.pythonPath? My regular path is users/fred/appdata/local/programs/pythong/python310. The other path is /users/fred/documents/platformio/projects/project-name/venv/scripts". I tried putting them both in and it makes things worse for then I don't have the venv enabled.

[lextm]

@FrightRisk Can you run the exact steps to test out the demo docs, not your own sphinx docs? That can help rule out if you are hitting a more complex situation.