Tutorial docs needed

[dbrtly]

Hi Simon,

I'm trying to wire this up as py-black or py-ruff and not finding the code obvious. Maybe it's just me.

I got Black working via bazel-super-formatter but keen to implement this as alternative for the learning experience to compare & contrast.

If you could point me in the right direction that would be great. Please.

[shs96c]

My apologies for not getting to this sooner. Some docs, as you say, would be very useful. The outline given in the README is very brief, but perhaps I can expand a little more on that here.

The first step is to express your lint check as a *_test rule (so py_black_test or similar in your case) You can also create an optional *_fix rule that can be used with bazel run to fix the lint problems if your linter can fix things for you automatically.

Generally, I treat lint configs like toolchains: I represent them using build rules that either contain options or point to a config file. I also tend to assume that there's one style used per-repo. I know there's a lot of "generally" and "tend" in there, but apple_rules_lint allows overriding the config on a per-package basis.

When people wire apple_rules_lint into their own repos, they opt-into linting by calling lint_setup and passing a dict of "well-known name" to config (which might be a simple boolean, if the linter accepts no configuration options). The "well-known name" should be lower-case, unambiguous, and is chosen by you (the linter author). So far, the pattern used has been lang-linter-name (eg. java-checkstyle)

Once you have your test rule, you then use a macro to wrap an existing rule (eg. py_library or py_binary) to emit that rule plus any of linting tests. You can see an example here in contrib_rules_jvm

The complicated bit is figuring out whether or not the user has opted into linting for the target. In order to check that, call get_lint_config passing in the well-known name of your linter, and the tags for the target you're thinking of linting. The config for your well-known name is passed into lint_setup is returned if we should be generating lint tests. That example from contrib_rules_jvm shows everything wired up.

If you'd like more help, please feel free to either comment on this issue. I'm also on the public Bazel slack during UK work hours, and I'd be happy to help you there too.

I'm leaving the issue open in case you'd like to comment more, but please feel free to close if you think what I've written above is sufficient.