Sphinx and preview

Use the built-in preview#

Start with the Built-in engine for ordinary RST authoring without Python. It supports common directives, admonitions, tables, images, math, code highlighting, and supported Sphinx Design components. Choose Editor only, Split, or Preview only and adjust the update delay if needed.

Configure Sphinx#

Install the documentation project’s dependencies in its normal environment. In Settings → Tools → reStructuredText Pro, choose Sphinx and select or auto-detect sphinx-build. Confirm that executable can import the project’s extensions.

Set Docs root under Project settings. Open a source file and compare its rendering with the project build, especially for custom directives, themes, and cross-reference domains.

Diagnose a build difference#

Run the same Sphinx environment from a terminal and inspect errors in conf.py, extensions, or source. If the IDE was opened from a desktop launcher, its environment may not include your shell’s path; configure the executable explicitly.

The built-in renderer is useful while editing, but the production Sphinx build remains the final check for the deployed documentation. Review its warnings before publishing.