sphinxcontrib-shellcheck

What it is and what it does

sphinxcontrib-shellcheck is a Sphinx documentation builder extension that integrates the shellcheck linter into your documentation build process. It scans bash, sh, dash, and ksh code blocks embedded in reStructuredText files and reports shell script errors, style violations, and potential bugs with line and column references.

The extension runs as a custom Sphinx builder (invoked with `sphinx-build -b shellcheck`) and processes code blocks marked with shell language directives. It relies on the external shellcheck utility to perform the actual linting and outputs violations to both the console and a log file. Configuration options allow you to specify shell dialects, the shellcheck executable path, terminal prompt character, and debug verbosity.

Use it for:

• Validate shell scripts embedded in installation guides or deployment documentation before publishing.
• Catch common shell scripting mistakes in code examples during CI/CD documentation builds.
• Enforce consistent shell style across multiple documentation files in a large project.
• Document shell commands with automatic verification that they follow best practices.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that automatically lints shell code blocks in documentation using the shellcheck utility, reporting shell script errors and style issues during the documentation build.

No. The package is abandoned (last release March 2020) and has not been updated for modern Python or Sphinx versions. While it has low install friction and a permissive MIT license, the lack of maintenance means it will not receive bug fixes, security updates, or compatibility patches. If you need shell linting in Sphinx documentation, consider maintaining a fork or evaluating active alternatives.

Install

sphinxcontrib-shellcheck on PyPI

pip install sphinxcontrib-shellcheck

uv add sphinxcontrib-shellcheck

poetry add sphinxcontrib-shellcheck

Installing sphinxcontrib-shellcheck

Before you install

Low install friction with pure Python wheels for Python 3.5, 3.6, 3.7, and 3.8. However, the package is abandoned as of March 2020, and depends on the external shellcheck utility which must be installed separately on the system.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal restrictions, making it safe to adopt in most projects.

Quickstart

pip install sphinxcontrib-shellcheck

Add to conf.py:
extensions = ["sphinxcontrib.shellcheck"]

Run: sphinx-build -b shellcheck . _build example.rst

The shellcheck command-line utility must be installed on the system; the package is a Sphinx extension wrapper around it.

Verify before relying

• Whether shellcheck utility is automatically installed or must be provisioned separately by the user.
• Compatibility with Python versions beyond 3.8 or modern Sphinx versions.
• Current state of the shellcheck executable dependency and any version constraints.

Package facts

Evidence: sphinxcontrib_shellcheck-1.1.2-py35-none-any.whl; sphinxcontrib_shellcheck-1.1.2-py36-none-any.whl; sphinxcontrib_shellcheck-1.1.2-py37-none-any.whl; sphinxcontrib_shellcheck-1.1.2-py38-none-any.whl

Tags

More Documentation packages