Sphinx Preview

VS Code preview for Sphinx documentation. It creates an isolated Python virtual environment, starts sphinx-autobuild, and opens the result in VS Code's Simple Browser. Saving an RST, configuration, image, or diagram source triggers a rebuild and browser reload.

The extension is independent of the Python used by build machines. Its preview PowerShell runner is bundled in the VSIX. Repository-specific generation steps can be configured as pre-build or post-build commands.

Install

From this directory, run:

npm install
npm run package
code --install-extension .\sphinx-preview-0.1.0.vsix

The project uses the standard npm registry by default:

https://registry.npmjs.org/

Override it for one command when an internal or mirrored registry is required:

npm install --registry=https://your-npm-server.example/repository/npm/

Alternatively, override it for the current PowerShell session:

$env:npm_config_registry = "https://your-npm-server.example/repository/npm/"
npm install

Command-line and environment overrides take precedence over the project .npmrc. Reload VS Code after installing the VSIX.

Use

1. Open a Sphinx project, any folder inside it, or a parent folder containing the project in VS Code. The extension searches upward for the configured source directory and also checks the opened folder's immediate children. If multiple child projects match, it asks which one to preview.
2. Run Sphinx: Start Preview from the Command Palette.
3. If Python 3.12 is unavailable, approve the user-scoped installation through winget.
4. Save documentation files to rebuild and reload the preview.
5. Run Sphinx: Stop Preview when finished.

Build and server output is available in the Sphinx Preview output channel. By default, generated preview files are written to source-docs/_build/html; the location is configurable. A Sphinx docs status-bar item reopens the running preview.

Python environment

The extension accepts any Python 3.12 patch release. It searches the Python launcher and common user/system installations. When Python is missing on Windows, it offers to run:

winget install --id Python.Python.3.12 --exact --scope user

The virtual environment is stored in VS Code's extension global-storage directory, not in the repository. Dependencies are installed from requirements.txt and are reinstalled only when that file changes.

Settings

• sphinxPreview.sourceDirectory: directory containing conf.py, relative to the detected project root; defaults to source-docs.
• sphinxPreview.outputDirectory: generated HTML directory; defaults to ${documentationRoot}/_build/html.
• sphinxPreview.pipIndexUrl: package index used to initialize the virtual environment; defaults to https://pypi.org/simple. Clear it to use the user's pip configuration.
• sphinxPreview.plantUmlJarPath: optional path to plantuml.jar. It supports ${workspaceFolder}, ${projectRoot}, and ${documentationRoot} variables. For example: ${workspaceFolder}/tools/plantuml.jar. When empty or missing, the preview continues using the path from conf.py; unavailable diagrams produce Sphinx warnings but do not stop the server.
• sphinxPreview.preBuildCommands: PowerShell commands run once before preview startup. A failure prevents startup.
• sphinxPreview.postBuildCommands: PowerShell commands run once after the initial preview is available. A failure is reported but leaves the preview running.
• sphinxPreview.host / sphinxPreview.port: preview endpoint.
• sphinxPreview.powerShellPath: use pwsh.exe here if preferred.
• sphinxPreview.openOnStart: automatically open the Simple Browser.

Path settings and build commands support ${workspaceFolder}, ${projectRoot}, and ${documentationRoot} where indicated. ${projectRoot} is the detected project containing the configured documentation source, while ${documentationRoot} is the directory containing conf.py. For example:

{
  "sphinxPreview.sourceDirectory": "docs",
  "sphinxPreview.outputDirectory": "${documentationRoot}/_build/html",
  "sphinxPreview.preBuildCommands": [
    "& '${workspaceFolder}/tools/generate-documentation-input.ps1'"
  ],
  "sphinxPreview.postBuildCommands": [
    "Write-Output 'Initial documentation preview is ready'"
  ]
}

Commands execute only when starting a trusted workspace; they do not run again for hot-reload builds. #� �S�p�h�i�n�x�-�P�r�e�v�i�e�w�-�E�x�t�e�n�s�i�o�n� � �