Sphinx awesome codelinter

The awesome codelinter extension for the Sphinx documentation generator lets you check that code blocks are valid or follow a preferred style. The extension lets you run an external tool, such as a linter, over all code blocks in your Sphinx documentation.

Install

Install the extension:

pip install sphinxawesome-codelinter

This Sphinx extension works with Python versions newer than 3.8 and recent Sphinx releases.

Configure

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

extensions = ["sphinxawesome.codelinter"]

To use an external tool to check code blocks, add the language and tool as key-value pairs to the codelinter_languages dictionary. By default, the dictionary is empty, so no code blocks will be processed unless added.

For example, to pass all JSON blocks to Python's built-in JSON module, use:

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

The Python command python -m json.tool returns an error for non-valid JSON code. To lint YAML code blocks, install the yamllint tool and add:

codelinter_languages = {
  "yaml": "yamllint -"
}

The - tells yamllint to read from stdin. You can write your own tools that read from stdin and write to stdout or stderr. They should return 0 if no errors are 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, .. code:: json, or ..literalinclude:: <filename> to include code from files.

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

Caution: The command you add to the codelinter_languages dictionary is called as provided. No additional safe-guards are in place to prevent abuse.

Use

The awesome codelinter extension runs as a Sphinx builder. Run sphinx-build -b codelinter to check your code blocks. If the codelinter tool returns a non-zero value, a warning is logged. To turn warnings into errors and stop the build process, use sphinx-build -W.

Advanced example showcase

The codelinter tool has been really nice in helping to find issues in documentation. Not sure if you want to put this in the README or examples/ folder, but here is a simplified snippet I use in some documentation generation.

It shows some of the things I needed to implement into an existing documentation system:

when commands do not support input from stdin (mypy does not support this)
validating c code can compile without warnings
python code passes mypy checks.
ability to opt-out of linting a given code block
preamble code so that users do not need to include certain functions every time

conf.py:

codelinter_languages = {
    "python": "python -m docs.linters python",
    "c": "python -m docs.linters c",
}

docs/linters.py:

import argparse
import subprocess
import sys

python_code_preface = """
import numpy as np  
import customlib
"""


def lint_python(code: str) -> None:
    full_code = python_code_preface + code
    if "# no-check" in full_code: # skip checking
        return
    subprocess.run(["mypy", "-c", f"{full_code}"], check=True)


def lint_c(code: str) -> None:
    if "// no-check" in code:  # skip checking
        return

    # it is a full example 
    if "// full" in code:

        full_code = (
            """
#include <stdlib.h>
#include <stdio.h>
"""
            + code
        )
    else:
        full_code = (
            """
#include <stdlib.h>
#include <stdio.h>

int main() {
"""
            + code
            + """
    return 0;
}
"""
        )
    subprocess.run(
        [
            "gcc",
            "-c",
            "-x",
            "c",
            "-Wall",
            "-Werror",
            "-ansi",
            "-std=c99",
            "-pedantic",
            "-pedantic-errors",
            "-Wno-unused-variable",
            "-Wno-unused-but-set-variable",
            "-Wno-unused-local-typedefs",
            "-o",
            "/dev/null",
            "-",
        ],
        input=full_code.encode(),
        check=True,
    )

def main() -> None:
    parser = argparse.ArgumentParser()

    parser.add_argument("linter", choices=("python", "c"))
    args = parser.parse_args()
    code = sys.stdin.read()

    if args.linter == "python":
        lint_python(code)
    else:
        lint_c(code)


if __name__ == "__main__":
    main()

kai687 / sphinxawesome-codelinter Goto Github PK