Generating documentation using Sphinx fails

[kmr29499]

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. clone repo to local machine (Linux or Windows - both the same behavior)
2. go to folder ./EVerest/docs
3. make sure to have Python, Sphinx etc. installed
4. execute make pdf
5. Error: ImportError: cannot import name 'setup_js_tag_helper' from 'sphinx.builders.html'
   Expected behavior
   I would have expected to have a clean run of documentation generation

Screenshots

Desktop (please complete the following information):

• OS: Ubuntu 22.04 and Windows 11

Installed Python packages:
pypackages.txt

[krealyt]

This is a known issue currently, but thanks for officially reporting.

We will check what we can suggest as best practice to generate docs locally. And then, this has to be documented in the "How to document" section.

[volkert-fastned]

I ran into the same issue. It's because setup_js_tag_helper this is no longer available in Sphinx 7.2.x and later versions. It seems like the EVerest documentation project needs to be updated to use a newer API somewhere.

In the meantime, what worked for me was to downgrade Sphinx to 7.1.x:

# You'll probably have to add the `--user` option to the command below if you're not using a Virtual Environment (venv).
pip install sphinx==7.1.2

Which led me to another problem: how to generate the contents of chapter 13 (or 3.13?), since that is generated from module-specific yaml files. I'm looking at the GitHub Actions Workflow to see how that needs to be done.

Question for the project maintainers: any reason why you have PDF file generation disabled by default? It would be nice to have the entire generated documentation in a single file as a release artifact on this project's GitHub page. (Much easier to search in, compared to the multi-page HTML documentation.)

Thanks!

[krealyt]

@volkert-fastned First of all, thanks for digging into that.

As far as I remember, deactivating PDF generation was a TEMPORARY (TM) step to get the whole doc creation workflow running again when we had an issue with the PDF part and we didn't have the time back then to solve things directly.

So, if the reason for your question was whether you can re-activate PDF generation, go for it. Be aware that we are curently thinking about changing the documentation structure for quite a bit. But that should have to relation to repairing PDF creation here. What do you think, @andistorm ?

[andistorm]

I hope to be able making the sphinx build as part of the dagger poc, which means implementing the ci workflow in dagger, this would enable running this locally, too. Not natively, but at least in a defined containerized environment