Open lextm opened 1 month ago
Thanks for writing these up, I keep meaning to put something like this together in #665... :sweat_smile: 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?
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.
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.
@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.
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
Demo Source Code
/Users/lextm/esbonio
)./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
:This is not enough, and Esbonio won't work as expected yet.
Virtual Environment
I choose Pyenv and Pipenv to prepare the virtual environment:
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:
.vscode/settings.json
Testing
Now it's time to play with Esbonio features, such as live preview and sync scrolling.
Live Preview
rst/domains/python.rst
.Auto Completion
Open any
.rst
file, and addPlace the cursor behind
/
and trigger auto completion.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.
You might review
esbonio.sphinx.pythonCommand
to make sure it is correctly configured.