-
Notifications
You must be signed in to change notification settings - Fork 22
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Feedback for the Esbonio VSCode extension v0.92.1
#609
Comments
This is the VSCode output for esbonio set to debug. I only changed my username to xxxxx:
No html files were generated. After switching back to the esbonio normal release version, everything worked OK. |
Thank you for taking the time to try it! :)
Ah, something I forgot to mention in the original write up - the only build trigger currently implemented is saving a file. If you make some changes and save, once the build finishes the preview should hopefully work then 🤞
Good to know. While multi-root will be a headline feature, the architecture should eventually be an improvement even for single root projects. Since the Sphinx app has been offloaded to another process, work can be done in parallel and the main language server is free to do other things during builds etc. |
Indeed, after saving and opening the html preview it works, and scrolling either the editor or preview causes the preview or editor to scroll sync perfectly. Nice! One thing that does not work, when clicking on another rst file of the same website, the preview panel does not update, it stays at the same preview of the old rst file. Editing and saving does not make any difference. The debug output stops at this line after the new rst file is opened:
After closing and reopening the preview window, the correct preview appears:
|
I also noticed that editing and saving does not trigger scroll sync. The only way I found to force scroll sync is scroll a tiny bit, then immediately, editor and preview go to the same synced position. |
Multi-root also appears to work: I opened two projects in the same VSCode workspace and I could open a previewer on a document from the first project. When I then close the preview and open a document from the second project, edit and save it, and then open the previewer again, I see the correct preview of that document. |
Awesome, thank you for the feedback! :) |
I'm on Windows and got the following traceback when trying to save or open the preview pane: Output: Esbonio
[esbonio.SphinxManager] Saved document 'file:///f%3A/python-pdm/docs/index.rst'
[client] workspace/configuration: {
"items": [
{
"scopeUri": "file:///f%3A/python-pdm/docs/index.rst",
"section": "esbonio.sphinx"
}
]
}
[client] Python extension is available
[client] Python extension is active
[client] Using environment F:\PYTHON-PDM\.VENV\SCRIPTS\PYTHON.EXE: f:\python-pdm\.venv\Scripts\python.exe
[esbonio.SphinxManager] User config: SphinxConfig(enable_dev_tools=False, enable_sync_scrolling=True, python_command=['f:\\python-pdm\\.venv\\Scripts\\python.exe'], build_command=['sphinx-build -b html docs/ docs/_build'], cwd='', python_path=[])
[esbonio.SphinxManager] Cwd: f:\python-pdm
[esbonio.SphinxManager] Sphinx agent env: {
"PYTHONPATH": "c:\\Users\\me\\.vscode\\extensions\\swyddfa.esbonio-0.90.1\\bundled\\libs\\esbonio"
}
[esbonio.SphinxManager] Starting sphinx agent: f:\python-pdm\.venv\Scripts\python.exe -m sphinx_agent
[esbonio.SphinxManager] Starting sphinx: sphinx-build -b html docs/ docs/_build
[esbonio.SphinxManager] Process exited with code: 1
[esbonio.SphinxManager] Stderr:
Traceback (most recent call last):
File "<frozen runpy>", line 198, in _run_module_as_main
File "<frozen runpy>", line 88, in _run_code
File "c:\Users\me\.vscode\extensions\swyddfa.esbonio-0.90.1\bundled\libs\esbonio\sphinx_agent\__main__.py", line 1, in <module>
import asyncio
File "C:\Users\me\AppData\Local\Programs\Python\Python311-32\Lib\asyncio\__init__.py", line 42, in <module>
from .windows_events import *
File "C:\Users\me\AppData\Local\Programs\Python\Python311-32\Lib\asyncio\windows_events.py", line 8, in <module>
import _overlapped
OSError: [WinError 10106] Der angeforderte Dienstanbieter konnte nicht geladen oder initialisiert werden Notes:
|
Interesting that you got a traceback! I had a quick play around with this on Windows the other day and couldn’t even get the Sphinx process to launch - there was some cryptic error about not being able to generate random numbers. I was eventually able to fix it by making the sure the server passes through the I also encountered a bunch of issues caused by Window’s use of Thank you for the feedback! 🙂 |
So, soonTM is further off than I anticipated, but I've been using On the plus side, the new preview approach is proving to be much more flexible! It should be possible to support previews in any editor - not just VSCode. If you are interested, clicking the image below will take you to a short clip showing that previews can even work over your LAN - here I'm using an iPad to preview documentation being built by a raspberry pi on my local network! Previews
Sphinx Agent
Misc
|
Thanks for the update and for all the time you put into perfecting this beautiful tool. A lot of work that still needs to be done! |
I've just pushed the next pre-release version of the Esbonio VSCode extension - What to expect
What not to expect
What to test
|
v0.90.1
v0.91.0
Thanks for the quick feedback! Glad to hear that things appear to be (mostly!) working
Ooh interesting, hadn't considered these scenarios.
I think these might need a rethink in general...
Sounds like there should at least be some more feedback from the server when things go wrong! |
Yes.
I think the old
Actually there were very many lines of error reporting with resulting exceptions in the Esbonio |
It now does both :)
Technically possible... but unlikely to be implemented anytime soon. I expect the easiest option is to provide a few config values to control how the preview refreshes/incremental builds are triggered.
This is only an issue after clicking on an entry in the TOC right? If so, I think I know what is happening. The preview pane is essentially a web browser tab so it has an internal url of the document that is being shown. A preview refresh is the equivalent of hitting I'm not sure it would be wise to try and teach the preview about TOCs, since the details are likely to differ across sphinx versions and themes... but perhaps having the preview drop the |
Quick question when it comes to previewing documents that Currently when scrolling the preview, the editor will "bounce" to the top of the current file and back when scrolling. This is due to the preview only having access to line numbers - and not the source file they belong to. Injecting the source file information into the preview should be easy enough, but I'm not sure what should be done once that data is available and I'm wondering if you have any thoughts? Should it
Both are just as easy to implement - but I'm worried the second option could be jarring, especially if you happen to scroll quickly? |
I don't understand this. I don't see any "bouncing" to the top. When I open a file, the preview starts at the top. When I then scroll the editor up and down, the preview follows by scrolling from line to line in discrete steps. I think that the first option (pausing) could be confusing. I have a clear preference for the second option. This would be a great help in visualizing the structure of the file and included files. If the user would experience it as jarring, then possibly he/she has too many small included files. In such a case, the user can change the file structure by reducing the number of included files. This is exactly what I have experienced when a Teacher Assistent created too many, too small included files, which was changed later on by removing most of the included files. |
The strange thing is that I have just tried to replicate the behavior (see #609 (comment)) by testing many, including very large, files. But all the other files that I have tested behave as they should. So the problem appears to occur only in this one single file, see #609 (comment). It is a file that has been generated from Latex source, but I don't see any strange |
I think I found the culprit. When I remove all references to In
As extension, I use: Note that with |
I just noticed that the "Esbonio: Restart Language Server" does not appear to first remove the cache, which is now at one of the subfolders at |
Just went to to 0.91.0 to see if things get better as I was having problems with even the earlier release (my directory has spaces and apostrophes which was confusing things) I have sphinx in a virtualenv, and I think the esbonio process must be starting without activating the venv.
|
Oh that's interesting, for some reason the extension is trying to start the wrong server. 🤔 Quick bit of context, the extension is currently shipping with 2 versions of the language server
For some reason the extension is trying to launch the original Can you set the Assuming that you also have the right virtual environment activated in the official Python extension, the server should then be able to attach itself to the right environment 🤞 |
I did this in settings.json and restarted, now don't see the error I reported. I do however see the following, which I saw before as well. then when I clicked No Do I need to uninstall reStructuredText (LeXtudio Inc) v189.3.0? |
At the very least I would disable it in the current workspace while you experiment with Esbonio |
Yup, now the preview works. It's not displaying my graphviz chart, but that's not displaying on readthedocs.io (I just realized), so I'm sure it's not an esbonio problem. Thanks! |
FWIW, I've fixed the graphviz problem on readthedocs. This was fixed with louking/tm-csv-connector@b6701fe (just the bits on lines 17-18 were enough, I'm sure). Still esbonio displays the raw graphviz code (no chart) in the preview for https://github.com/louking/tm-csv-connector/blob/3c920236d9a6b3e307151b4c5bad0d8ef2351036/web/docs/source/design.rst?plain=1#L53-L100. Interestingly github also displays the raw code. See https://tm-csv-connector.readthedocs.io/en/latest/design.html#design for reference |
Interesting... did the rest of the preview render ok? Would you mind sharing a screenshot? I would've expected you to see the HTML version of the page complete with the read the docs theme etc. |
Yes the rest of the preview rendered ok, including use of readthedocs theme. Here are a couple of screenshots. The design.zip file includes the html file my local build produced, which renders like https://tm-csv-connector.readthedocs.io/en/latest/design.html |
Awesome thanks for that! It looks like the source code is set as the alt text for the chart's I'm wondering if esbonio is missing a build phase or something... 🤔 |
I would be surprised if it mattered since the preview does the equivalent of
Hmm, at least it looks like esbonio is producing the image file - will have to investigate! |
Not sure it's clear that esbonio produced any image file -- I have been running |
Interesting.... I'll have a look but I'm not sure if that's from anything Is |
Yes an environment variable: https://learn.microsoft.com/en-us/windows/deployment/usmt/usmt-recognized-environment-variables I'm not certain this is related to Sphinx or esbonio. But I noted it started appearing around Oct 15, which fits the timeframe of installing the new esbonio, according to my change log.
When I get time, I'll try to reproduce this and see if it's clear. |
Hi, thanks for your work. I have issue #699 with |
New year, new pre-prelease! What to expect
What not to expect
|
v0.91.0
v0.92.1
I've tried the prerelease version (Windows, VSCode 1.86, Python 3.11, Sphinx 7.1.2). Live preview, Ctrl+T, problem reporting all work. One issue I've noticed is that I have to manually restart the Esbonio server after a fresh VSCode start. Otherwise I get this:
|
Thanks for giving it a try! This looks like a similar issue to #646, I need to look into how to re-establish a connection once it has been interrupted... |
Closing this issue as it has probably served its purpose. I've gone back through all the messages and opened issues for anything that was not covered elsewhere. Feel free to open an issue if you think I've missed anything |
I've just pushed a pre-release version of the Esbonio VSCode extension -
v0.90.1
, the first draft of what ultimately should becomev1.0
. It would be greatly appreciated if people can try it out and offer some feedback.What to expect
v1.0
of the language server - it should no longer be necessary to installesbonio
directly into your documentation's Python environment!What not to expect
What to test
The focus of this pre-release is purely on getting the fundamentals right, distribution, multi-root support, Sphinx configuration, the new preview implementation. Once it's clear that this new approach is going to work out, it should be possible to port across the missing features... relatively quickly 😅
The text was updated successfully, but these errors were encountered: