Sphinx-build sometimes hangs

[marcel-22]

Expected behavior

If an Esbonio sphinx-build fails for some reason, it should abort the build process and try again the next time?

Actual behavior

Sometimes the Esbonio sphinx-build hangs. The progress in the status bar is stuck at:

The notification panel of our VS Code like editor shows:

The actual issue is presumably caused by PlantUML, see sphinx-contrib/plantuml#94

I'm curious if more users are experiencing this. We have a multi-root workspace setup. Esbonio version is 0.96.0.

Another example is that sometimes the build hangs due to sphinx_last_updated_by_git.

Log output

(Optional) Settings from conf.py

[marcel-22]

On the other hand Esbonio not finishing the sphinx-build helps to identify problems for now.. 😉

[alcarney]

I should really look at fixing #802 as I expect it is making the problem look worse than it really is. In fact, I would not be surprised if the failed build you see is only "real" build that is happening.

If an Esbonio sphinx-build fails for some reason, it should abort the build process and try again the next time

I think this is the case already? Or at least it should be when the build actually crashes. If it's genuinely hanging... does restarting the Sphinx process via the Sphinx Processes view allow it to recover?

[marcel-22]

I would not be surprised if the failed build you see is only "real" build that is happening.

I'm not sure what you mean by this.

If it's genuinely hanging... does restarting the Sphinx process via the Sphinx Processes view allow it to recover?

I would say that it is hanging, because the esbonio notifications don't disappear. Clicking on the Restart Sphinx Process button does not clear the notifications. Also the live preview window does not update on changes in the RST document, even when saving the document. More Esbonio notifications then appear in the notifications panel, but all on top of the previous ones.

[marcel-22]

Do you have a clue what is going on? Is the issue caused by the other Sphinx extensions (e.g. sphinx_last_updated_by_git) or is it an Esbonio issue? I have never had problems with these extensions until now.

[alcarney]

Do you have a clue what is going on?

Yes, most of this is Esbonio's fault (#802)

Each time Esbonio starts a new build, it creates a new notification however, #802 means that it doesn't always clean them up. Resulting in this long list of builds that look like they are stuck when in reality they all finished a long time ago.

There can only be one build per Sphinx process, so unless the server is creating multiple Sphinx processes per project (which should get listed in the UI) then it should be safe to assume there is at most one build happening at once.

Have you checked the logs? I expect the Sphinx output you do/don't see there would also help to indicate if builds are completing or not.

Also the live preview window does not update on changes in the RST document, even when saving the document.

Interesting... 🤔

There could be other issues happening as well (such as your linked plantuml bug), but until #802 is fixed, it might be difficult to unpick them all 😅.

[marcel-22]

Have you checked the logs? I expect the Sphinx output you do/don't see there would also help to indicate if builds are completing or not.

I had tried to find some useful details in there, but so far hadn't find something strange or interesting. So at first glance it seems like the build is finishing normally. But I haven't looked in very detail, so maybe I should check again.

There could be other issues happening as well (such as your linked plantuml bug), but until #802 is fixed, it might be difficult to unpick them all.

Are you planning to fix #802 any time soon? Just to know what I can expect 😉
The live preview window sometimes not updating is bothersome.