Skip to content
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

Add support for building documentation with latest sphinx #2695

Open
wants to merge 28 commits into
base: master
Choose a base branch
from

Conversation

neofelis2X
Copy link

As discussed in #2672, this unpins sphinx and makes building the documentation with latest sphinx (currently 8.1.3) possible.
A current build of the documentation can be viewed here. This test page will be deleted later.

The sphinx build process was tested locally with macOS and Windows, with python 3.9 and 3.13.

To get the docs to look and work as before, a few fixes were needed. Mostly changes to the sphinx config and the post-processing script.

A rough overview of the changes:

  • Update to Doxygen 1.9.1
  • Doxygen for windows now comes with libclang.dll
    • getTool is now able to load also .tar.bz2 files
  • getting back jQuery with "sphinxcontrib.jquery"
  • fixed a deprecated getargspec function
  • doc2dash --name flag needs the full name with extension
  • some tweaking of the theme (css)
  • some fixes where the ReStructuredText was incorrect
  • in windows sphinx couldn't load images from a windows path in ReST files
  • wxStyledTextCtrl has many methods, which are now sorted and linked correctly
  • the postprocessing script needed to be updated because it alters the output html files directly

Fixes #2672

It also relates to #2608 but I did not update the inheritance diagrams yet.

@neofelis2X
Copy link
Author

Ok so I looked into why the build workflow failed.

The Problem:

The "new" doxygen version is linked against clang-9 and that is missing. Furthermore, the host Ubuntu 22.04 doesn't even support clang-9 anymore. My bad, sorry, I didn't know that.

The good news:

Ubuntu 22.04 has doxygen 1.9.1 as a package. This binary is linked against clang-14 and it works.

My proposed solution:

  1. Upload the ubuntu binary to wxPython-tools. Then we have a functional version there.
  2. Install apt install doxygen in the github workflow - then we have all needed dependencies

Please let me know what you think of that. I'm not much of a linux person, but that's how I would solve this complication.

@echoix
Copy link
Contributor

echoix commented Feb 10, 2025

Does doxygen work correctly with a static build? Is it tied to llvm?

@neofelis2X
Copy link
Author

I didn't try that, should work in theory.

@swt2c
Copy link
Collaborator

swt2c commented Feb 11, 2025

1. Upload the ubuntu binary to `wxPython-tools`. Then we have a functional version there.

I don't think we should just upload the ubuntu binary to wxPython tools. Then it technically might work in our CI but it won't work for anyone else. Ideally, we would use a statically linked doxygen that doesn't require external dependencies (or I suppose include the dependencies?) which is how the current doyxgen build works. It would be nice if we could keep that property.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Help wanted: Get documentation building with current Sphinx
3 participants