Skip to content

Esbonio VS Code Reviewer's Guide #899

Closed
@lextm

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions