Skip to main content

A Sphinx extension that enables running linters over code blocks

Project description

Sphinx Awesome Codelinter

License: MIT PyPI version Test Status Code style: black

This extension for the Sphinx documentation suite allows you to iterate over code blocks and expose them to an external tool. This can be used to make sure, that code blocks are valid. 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. Unit tests are being run against Python 3.6, 3.7, 3.8 and Sphinx 2.0, 2.1, 2.2, and 2.3.


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

extensions = ['sphinxawesome.codelinter']

The extension is configured via the codelinter_languages dictionary, which is empty by default. That is, no code blocks will be processed unless you provide the language and the tool to process the language as a key/value pair. For example, to pass all JSON blocks to the python builtin JSON module, use:

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

which would return 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 retun a value of 0, ifcno errors were found, a non-zero value otherwise.

After configuring the extension, you can use sphinx-build -b codelinter ... like other Sphinx builders. No output will be written to disk. If the linter 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.

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 used as provided. No additional safe-guards are in place to prevent abuse.

Project details

Release history Release notifications

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.2
Filename, size File type Python version Upload date Hashes
Filename, size sphinxawesome_codelinter-1.0.2-py3-none-any.whl (5.1 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size sphinxawesome-codelinter-1.0.2.tar.gz (4.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page