Skip to content

BF: Mock gltools so the docs build does not segfault - #9

Open
JoKeyser wants to merge 1 commit into
psychopy:mainfrom
JoKeyser:BF/fix-docs-build-segfault
Open

JoKeyser wants to merge 1 commit into
psychopy:mainfrom
JoKeyser:BF/fix-docs-build-segfault

Conversation

@JoKeyser

@JoKeyser JoKeyser commented Oct 5, 2026 •

Copy link
Copy Markdown

Thanks a lot for maintaining this template, it helps me getting started much easier.
While trying it out I hit a crash when building the docs, so here is a small fix (probably with a fairly indirect root cause behind it).

When trying to build the docs, it segfaults while reading coder/ExampleVisualStim. I saw this with PsychoPy 2026.2.4, pyglet 1.5.27, Sphinx 8.1.3 and Python 3.10, both on Linux with a display and on macos-latest. (Used command: sphinx-build docs_src docs -b dirhtml).

With this PR, docs_src/conf.py now mocks psychopy.tools.gltools.
With it, psychopy.visual gets imported and documented without segfault.

My best guess at the cause: Sphinx imports psychopy.visual to document the plugin, which imports psychopy.tools.gltools, which queries OpenGL at import time. pyglet skips creating its hidden window when sphinx is in sys.modules, so there is no OpenGL context and the query crashes in native code. The try/except around it can't catch that. I also tried autodoc_mock_imports, but it doesn't help: the crashing import happens in sphinx.pycode, outside autodoc's mock context.

To check it yourself:

What I tested: The build succeeds on Linux laptop (Python 3.10), and the full docs workflow succeeds on macos-latest.

Sphinx sets a flag that makes pyglet skip creating its hidden window,
so no OpenGL context exists. psychopy.visual imports
psychopy.tools.gltools, which queries OpenGL at import time, and that
query segfaults. Mocking only gltools avoids the query and keeps
psychopy.visual importable and documented.
JoKeyser added a commit to CMDN-Lab/psychopy-plugin-lsl that referenced this pull request Oct 6, 2026
JoKeyser added a commit to dhprlab/psychopy-cyclus2 that referenced this pull request Oct 6, 2026

This branch has not been deployed

No deployments
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.

1 participant