Troubleshooting

Sphinx cannot be found#

Use executable auto-detection or select sphinx-build explicitly. Verify it belongs to the environment containing the project’s extensions; a system Sphinx may differ from the project’s virtual environment.

A directive renders differently from the site#

Switch from built-in rendering to the configured Sphinx engine when the directive depends on a Python extension. Check conf.py and installed dependencies, then reproduce the build outside the IDE.

References or static images are unresolved#

Check Docs root, label spelling, document paths, and domain-qualified roles such as py:func. Review reference warnings in the context of the complete Sphinx project.

Report an issue#

Use email support and include:

• Your IDE edition and full build number from Help → About.
• The installed plugin version; this manual covers 2026.2.4.
• Relevant external-tool versions, the failing action, and a small reproducible example.
• The error message and relevant log excerpt, with credentials and private project data removed.

Use Help → Show Log in Finder/Explorer to locate IDE logs when requested. Describe what you expected to happen and whether the same operation works from a terminal.