fix(docs): correct markdown syntax

[alexeagle]

These mistakes are all visible when docs are displayed as markdown such as
on the recommended API docsite https://bazelbuild.github.io/rules_kotlin/kotlin

Mostly this is because stardoc doesn't automatically dedent multiline doc strings
(perhaps it should)

[cgruber]

Well that's gross. I wonder if one could run these through a de-intent function in-line. This makes the code substantially harder to read, and starlark is already crappy for that. grumble

[alexeagle]

run these through a de-intent function in-line

I considered that (write a little dedent helper like python's textutil.dedent and copy-paste into every ruleset), but since stardoc is syntactic, I don't think it would help.

I'll put some time into the proper upstream fix (auto-dedent based on indent of the first line) similar to my bazelbuild/bazel@81e75cc

[alexeagle]

also, a pattern we use in rules_nodejs to improve readability is to move all the docs to the top, e.g.

some.bzl

"some rules"

_DOC = """\
All about the foo rule.
It's great

    code sample
    goes here
"""

_ATTRS = {
    "bar": attr.string(
        doc = """\
bar is a useless attribute for sure
""",
        default = "thing",
    ),
}

def _foo(ctx):
    return []

foo = rule(_foo, doc = _DOC, attrs = _ATTRS)

[alexeagle]

Filed bazelbuild/bazel#13402

and I'm attempting a fix upstream...