A Sphinx extension that enables running linters over code blocks
Project description
Sphinx Awesome Codelinter
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 http://www.sphinx-doc.org/.
This extension provides a new builder, sphinx-build -b codelinter
.
Installation
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.
Configuration
To enable this extension in Sphinx, add it to the list of extensions in the Sphinx
configuration file conf.py
:
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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinxawesome-codelinter-1.0.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1a0dea7795978e188ece1f1a6c668284dba9d93e82c6aa8303bfbae2411445bc |
|
MD5 | 729af05109499dbc967d2d2deb7dd1cc |
|
BLAKE2b-256 | 177e894b202696664dab6e94663fde03828133718aed5c0c4aa98e2c8e4fd2ec |
Hashes for sphinxawesome_codelinter-1.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e325ce4f003d8bc3ca772279a156f68e18296eb1ab2c2bb382d101c2da36d57c |
|
MD5 | 0b24b7870eed016f78eb24b706edf84a |
|
BLAKE2b-256 | f1aa64372ec0fa8531519ce961c05bd7924f458ae6e27a52511202c9b75e91b9 |