From 496572a0e6b9e26f17cc0caf47322555d691bfa2 Mon Sep 17 00:00:00 2001
From: Alex Eagle <alex@aspect.dev>
Date: Thu, 12 Oct 2023 10:22:24 -0700
Subject: [PATCH] chore: generate API docs for flake8

Third commit in "how to add a new linter".
---
 README.md        |  2 ++
 docs/BUILD.bazel |  5 ++++
 docs/flake8.md   | 74 ++++++++++++++++++++++++++++++++++++++++++++++++
 lint/BUILD.bazel |  6 ++++
 4 files changed, 87 insertions(+)
 create mode 100644 docs/flake8.md

diff --git a/README.md b/README.md
index 7eb683c9..0e884097 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,8 @@ We have a separate project for formatting, see <https://github.com/aspect-build/
   - `buf lint`: <https://buf.build/docs/lint/overview>
 - JavaScript
   - `eslint`: https://eslint.org/
+- Python
+  - `flake8`: <https://flake8.pycqa.org/en/latest/index.html>
 
 ### Adding a linter
 
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
index a61f6888..0b09c0bd 100644
--- a/docs/BUILD.bazel
+++ b/docs/BUILD.bazel
@@ -12,4 +12,9 @@ stardoc_with_diff_test(
     bzl_library_target = "//lint:eslint",
 )
 
+stardoc_with_diff_test(
+    name = "flake8",
+    bzl_library_target = "//lint:flake8",
+)
+
 update_docs(name = "update")
diff --git a/docs/flake8.md b/docs/flake8.md
new file mode 100644
index 00000000..63853c83
--- /dev/null
+++ b/docs/flake8.md
@@ -0,0 +1,74 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+API for declaring a flake8 lint aspect that visits py_library rules.
+
+Typical usage:
+
+```
+load("@aspect_rules_lint//lint:flake8.bzl", "flake8_aspect")
+
+flake8 = flake8_aspect(
+    binary = "@@//:flake8",
+    config = "@@//:.flake8",
+)
+```
+
+
+<a id="flake8_action"></a>
+
+## flake8_action
+
+<pre>
+flake8_action(<a href="#flake8_action-ctx">ctx</a>, <a href="#flake8_action-executable">executable</a>, <a href="#flake8_action-srcs">srcs</a>, <a href="#flake8_action-config">config</a>, <a href="#flake8_action-report">report</a>, <a href="#flake8_action-use_exit_code">use_exit_code</a>)
+</pre>
+
+Run flake8 as an action under Bazel.
+
+Based on https://flake8.pycqa.org/en/latest/user/invocation.html
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="flake8_action-ctx"></a>ctx |  Bazel Rule or Aspect evaluation context   |  none |
+| <a id="flake8_action-executable"></a>executable |  label of the the flake8 program   |  none |
+| <a id="flake8_action-srcs"></a>srcs |  python files to be linted   |  none |
+| <a id="flake8_action-config"></a>config |  label of the flake8 config file (setup.cfg, tox.ini, or .flake8)   |  none |
+| <a id="flake8_action-report"></a>report |  output file to generate   |  none |
+| <a id="flake8_action-use_exit_code"></a>use_exit_code |  whether to fail the build when a lint violation is reported   |  <code>False</code> |
+
+
+<a id="flake8_aspect"></a>
+
+## flake8_aspect
+
+<pre>
+flake8_aspect(<a href="#flake8_aspect-binary">binary</a>, <a href="#flake8_aspect-config">config</a>)
+</pre>
+
+A factory function to create a linter aspect.
+
+Attrs:
+    binary: a flake8 executable. Can be obtained from rules_python like so:
+
+        ```
+        load("@rules_python//python/entry_points:py_console_script_binary.bzl", "py_console_script_binary")
+
+        py_console_script_binary(
+            name = "flake8",
+            pkg = "@pip//flake8:pkg",
+        )
+        ```
+    config: the flake8 config file (`setup.cfg`, `tox.ini`, or `.flake8`)
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="flake8_aspect-binary"></a>binary |  <p align="center"> - </p>   |  none |
+| <a id="flake8_aspect-config"></a>config |  <p align="center"> - </p>   |  none |
+
+
diff --git a/lint/BUILD.bazel b/lint/BUILD.bazel
index 9f22810d..566c0af4 100644
--- a/lint/BUILD.bazel
+++ b/lint/BUILD.bazel
@@ -18,3 +18,9 @@ bzl_library(
         "@aspect_rules_js//js:libs",
     ],
 )
+
+bzl_library(
+    name = "flake8",
+    srcs = ["flake8.bzl"],
+    visibility = ["//visibility:public"],
+)