Skip to main content

A Sphinx extension to pass reStructuredText code blocks to external tools.

Project description

Sphinx awesome codelinter

License PyPI version PyTest Status Codecov Supported Python Versions Code style

This extension for the Sphinx documentation generator allows you to expose code blocks in your documentation to an external tool. This can be used to check that code blocks contain only valid code. For more information about the Sphinx project, visit the website at

This extension provides a new builder: sphinx-build -b codelinter.


Install the extension:

pip install sphinxawesome-codelinter

This Sphinx extension should work with Python versions newer than 3.6 and recent Sphinx releases.


To enable this extension in Sphinx, add it to the list of extensions in the Sphinx configuration file

extensions = ["sphinxawesome.codelinter"]

To pass code blocks to an external tool, provide the language as a key and the tool as the associated value to the codelinter_languages dictionary. This dictionary is initially empty, so even if the extension is installed and included in the extensions list, no code blocks will be processed by default.

For example, to pass all JSON blocks to the python builtin JSON module, use:

codelinter_languages = {
  "json": "python -m json.tool"

The python command returns an error for non-valid JSON code. For linting YAML code blocks, you could install the yamllint tool and then add:

codelinter_languages = {
  "yaml": "yamllint -"

The - tells yamllint to read from stdin. You can also write your own tools that can read from stdin and write to stdout or stderr. The only expectation is that any tools returns a value of 0 if no errors were found, a non-zero value otherwise.

You can use any reStructuredText directive that gets parsed as a literal_block node. For example, you can use .. code-block:: json as well as .. highlight:: json.

You can also use the ..literalinclude:: <filename> directive to include code from files.

.. literalinclude:: code.json
   :language: json

Caution: The value of the codelinter_languages dictionary will be called as provided. No additional safe-guards are in place to prevent abuse.


Use sphinx-build -b codelinter like you would use other Sphinx builders. No output will be written to disk. If the codelinter tool exits with a non-zero return value, a warning will be logged. You can use the sphinx-build -W option to turn those warnings into errors to stop the build process.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sphinxawesome-codelinter, version 1.0.5
Filename, size File type Python version Upload date Hashes
Filename, size sphinxawesome_codelinter-1.0.5-py3-none-any.whl (5.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size sphinxawesome-codelinter-1.0.5.tar.gz (5.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page