The sphinxawesome-codelinter from kai687

kai687 / sphinxawesome-codelinter Goto Github PK

View Code? Open in Web Editor NEW

A Sphinx extension to check code blocks with external tools

License: MIT License

Python 100.00%

sphinxawesome-codelinter's People

Contributors

Stargazers

sphinxawesome-codelinter's Issues

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()

Recommend Projects