docs(gazelle): Migrate Gazelle docs to ReadTheDocs, part 3/5: annotations (#3137) Part of #3082 3rd of probably 5 PRs. + Migrate annotations docs from `gazelle/README.md` to `gazelle/docs/annotations.md` + Switch from table-based summary to bulleted lists + This will be much easier to maintain going forward. + Mechanical updates: + Wrap at ~80 chars + Use MyST directives and roles.

diff --git a/gazelle/README.md b/gazelle/README.md
index 11a9e5b..efc7004 100644
--- a/gazelle/README.md
+++ b/gazelle/README.md

@@ -390,191 +390,6 @@
 
 When `false`, Gazelle will ignore any `py_proto_library`, including previously-generated or hand-created rules.
 
-### Annotations
-
-*Annotations* refer to comments found _within Python files_ that configure how
-Gazelle acts for that particular file.
-
-Annotations have the form:
-
-```python
-# gazelle:annotation_name value
-```
-
-and can reside anywhere within a Python file where comments are valid. For example:
-
-```python
-import foo
-# gazelle:annotation_name value
-
-def bar():  # gazelle:annotation_name value
-    pass
-```
-
-The annotations are:
-
-| **Annotation**                                                | **Default value** |
-|---------------------------------------------------------------|-------------------|
-| [`# gazelle:ignore imports`](#annotation-ignore)              | N/A               |
-| Tells Gazelle to ignore import statements. `imports` is a comma-separated list of imports to ignore. | |
-| [`# gazelle:include_dep targets`](#annotation-include_dep)    | N/A               |
-| Tells Gazelle to include a set of dependencies, even if they are not imported in a Python module. `targets` is a comma-separated list of target names to include as dependencies. | |
-| [`# gazelle:include_pytest_conftest bool`](#annotation-include_pytest_conftest)    | N/A               |
-| Whether or not to include a sibling `:conftest` target in the deps of a `py_test` target. Default behaviour is to include `:conftest`. | |
-
-
-#### Annotation: `ignore`
-
-This annotation accepts a comma-separated string of values. Values are names of Python
-imports that Gazelle should _not_ include in target dependencies.
-
-The annotation can be added multiple times, and all values are combined and
-de-duplicated.
-
-For `python_generation_mode = "package"`, the `ignore` annotations
-found across all files included in the generated target are removed from `deps`.
-
-Example:
-
-```python
-import numpy  # a pypi package
-
-# gazelle:ignore bar.baz.hello,foo
-import bar.baz.hello
-import foo
-
-# Ignore this import because _reasons_
-import baz  # gazelle:ignore baz
-```
-
-will cause Gazelle to generate:
-
-```starlark
-deps = ["@pypi//numpy"],
-```
-
-
-#### Annotation: `include_dep`
-
-This annotation accepts a comma-separated string of values. Values _must_
-be Python targets, but _no validation is done_. If a value is not a Python
-target, building will result in an error saying:
-
-```
-<target> does not have mandatory providers: 'PyInfo' or 'CcInfo' or 'PyInfo'.
-```
-
-Adding non-Python targets to the generated target is a feature request being
-tracked in [Issue #1865](https://github.com/bazel-contrib/rules_python/issues/1865).
-
-The annotation can be added multiple times, and all values are combined
-and de-duplicated.
-
-For `python_generation_mode = "package"`, the `include_dep` annotations
-found across all files included in the generated target are included in `deps`.
-
-Example:
-
-```python
-# gazelle:include_dep //foo:bar,:hello_world,//:abc
-# gazelle:include_dep //:def,//foo:bar
-import numpy  # a pypi package
-```
-
-will cause Gazelle to generate:
-
-```starlark
-deps = [
-    ":hello_world",
-    "//:abc",
-    "//:def",
-    "//foo:bar",
-    "@pypi//numpy",
-]
-```
-
-#### Annotation: `include_pytest_conftest`
-
-Added in [#3080][gh3080].
-
-[gh3080]: https://github.com/bazel-contrib/rules_python/pull/3080
-
-This annotation accepts any string that can be parsed by go's
-[`strconv.ParseBool`][ParseBool]. If an unparsable string is passed, the
-annotation is ignored.
-
-[ParseBool]: https://pkg.go.dev/strconv#ParseBool
-
-Starting with [`rules_python` 0.14.0][rules-python-0.14.0] (specifically [PR #879][gh879]),
-Gazelle will include a `:conftest` dependency to an `py_test` target that is in
-the same directory as `conftest.py`.
-
-[rules-python-0.14.0]: https://github.com/bazel-contrib/rules_python/releases/tag/0.14.0
-[gh879]: https://github.com/bazel-contrib/rules_python/pull/879
-
-This annotation allows users to adjust that behavior. To disable the behavior, set
-the annotation value to "false":
-
-```
-# some_file_test.py
-# gazelle:include_pytest_conftest false
-```
-
-Example:
-
-Given a directory tree like:
-
-```
-.
-├── BUILD.bazel
-├── conftest.py
-└── some_file_test.py
-```
-
-The default Gazelle behavior would create:
-
-```starlark
-py_library(
-    name = "conftest",
-    testonly = True,
-    srcs = ["conftest.py"],
-    visibility = ["//:__subpackages__"],
-)
-
-py_test(
-    name = "some_file_test",
-    srcs = ["some_file_test.py"],
-    deps = [":conftest"],
-)
-```
-
-When `# gazelle:include_pytest_conftest false` is found in `some_file_test.py`
-
-```python
-# some_file_test.py
-# gazelle:include_pytest_conftest false
-```
-
-Gazelle will generate:
-
-```starlark
-py_library(
-    name = "conftest",
-    testonly = True,
-    srcs = ["conftest.py"],
-    visibility = ["//:__subpackages__"],
-)
-
-py_test(
-    name = "some_file_test",
-    srcs = ["some_file_test.py"],
-)
-```
-
-See [Issue #3076][gh3076] for more information.
-
-[gh3076]: https://github.com/bazel-contrib/rules_python/issues/3076
-
 
 #### Directive: `python_experimental_allow_relative_imports`
 Enables experimental support for resolving relative imports in

diff --git a/gazelle/docs/annotations.md b/gazelle/docs/annotations.md
new file mode 100644
index 0000000..cc87543
--- /dev/null
+++ b/gazelle/docs/annotations.md

@@ -0,0 +1,194 @@
+# Annotations
+
+*Annotations* refer to comments found _within Python files_ that configure how
+Gazelle acts for that particular file.
+
+Annotations have the form:
+
+```python
+# gazelle:annotation_name value
+```
+
+and can reside anywhere within a Python file where comments are valid. For example:
+
+```python
+import foo
+# gazelle:annotation_name value
+
+def bar():  # gazelle:annotation_name value
+    pass
+```
+
+The annotations are:
+
+* [`# gazelle:ignore imports`](#ignore)
+  * Default: n/a
+  * Allowed Values: A comma-separated string of python package names
+  * Tells Gazelle to ignore import statements. `imports` is a comma-separated
+    list of imports to ignore.
+* [`# gazelle:include_dep targets`](#include-dep)
+  * Default: n/a
+  * Allowed Values: A string
+  * Tells Gazelle to include a set of dependencies, even if they are not imported
+    in a Python module. `targets` is a comma-separated list of target names
+    to include as dependencies.
+* [`# gazelle:include_pytest_conftest bool`](#include-pytest-conftest)
+  * Default: n/a
+  * Allowed Values: `true`, `false`
+  * Whether or not to include a sibling `:conftest` target in the `deps`
+    of a {bzl:obj}`py_test` target. The default behaviour is to include `:conftest`
+    (i.e.: `# gazelle:include_pytest_conftest true`).
+
+
+## `ignore`
+
+This annotation accepts a comma-separated string of values. Values are names of
+Python imports that Gazelle should _not_ include in target dependencies.
+
+The annotation can be added multiple times, and all values are combined and
+de-duplicated.
+
+For `python_generation_mode = "package"`, the `ignore` annotations
+found across all files included in the generated target are removed from
+`deps`.
+
+### Example:
+
+```python
+import numpy  # a pypi package
+
+# gazelle:ignore bar.baz.hello,foo
+import bar.baz.hello
+import foo
+
+# Ignore this import because _reasons_
+import baz  # gazelle:ignore baz
+```
+
+will cause Gazelle to generate:
+
+```starlark
+deps = ["@pypi//numpy"],
+```
+
+
+## `include_dep`
+
+This annotation accepts a comma-separated string of values. Values _must_
+be Python targets, but _no validation is done_. If a value is not a Python
+target, building will result in an error saying:
+
+```
+<target> does not have mandatory providers: 'PyInfo' or 'CcInfo' or 'PyInfo'.
+```
+
+Adding non-Python targets to the generated target is a feature request being
+tracked in {gh-issue}`1865`.
+
+The annotation can be added multiple times, and all values are combined
+and de-duplicated.
+
+For `python_generation_mode = "package"`, the `include_dep` annotations
+found across all files included in the generated target are included in
+`deps`.
+
+### Example:
+
+```python
+# gazelle:include_dep //foo:bar,:hello_world,//:abc
+# gazelle:include_dep //:def,//foo:bar
+import numpy  # a pypi package
+```
+
+will cause Gazelle to generate:
+
+```starlark
+deps = [
+    ":hello_world",
+    "//:abc",
+    "//:def",
+    "//foo:bar",
+    "@pypi//numpy",
+]
+```
+
+
+## `include_pytest_conftest`
+
+:::{versionadded} VERSION_NEXT_FEATURE
+{gh-pr}`3080`
+:::
+
+This annotation accepts any string that can be parsed by go's
+[`strconv.ParseBool`][ParseBool]. If an unparsable string is passed, the
+annotation is ignored.
+
+[ParseBool]: https://pkg.go.dev/strconv#ParseBool
+
+Starting with [`rules_python` 0.14.0][rules-python-0.14.0] (specifically
+{gh-pr}`879`), Gazelle will include a `:conftest` dependency to a
+{bzl:obj}`py_test` target that is in the same directory as `conftest.py`.
+
+[rules-python-0.14.0]: https://github.com/bazel-contrib/rules_python/releases/tag/0.14.0
+
+This annotation allows users to adjust that behavior. To disable the behavior,
+set the annotation value to `false`:
+
+```
+# some_file_test.py
+# gazelle:include_pytest_conftest false
+```
+
+### Example:
+
+Given a directory tree like:
+
+```
+.
+├── BUILD.bazel
+├── conftest.py
+└── some_file_test.py
+```
+
+The default Gazelle behavior would create:
+
+```starlark
+py_library(
+    name = "conftest",
+    testonly = True,
+    srcs = ["conftest.py"],
+    visibility = ["//:__subpackages__"],
+)
+
+py_test(
+    name = "some_file_test",
+    srcs = ["some_file_test.py"],
+    deps = [":conftest"],
+)
+```
+
+When `# gazelle:include_pytest_conftest false` is found in
+`some_file_test.py`
+
+```python
+# some_file_test.py
+# gazelle:include_pytest_conftest false
+```
+
+Gazelle will generate:
+
+```starlark
+py_library(
+    name = "conftest",
+    testonly = True,
+    srcs = ["conftest.py"],
+    visibility = ["//:__subpackages__"],
+)
+
+py_test(
+    name = "some_file_test",
+    srcs = ["some_file_test.py"],
+)
+```
+
+See {gh-issue}`3076` for more information.

diff --git a/gazelle/docs/index.md b/gazelle/docs/index.md
index c04efd6..e262d7f 100644
--- a/gazelle/docs/index.md
+++ b/gazelle/docs/index.md

@@ -43,4 +43,5 @@
 ```{toctree}
 :maxdepth: 1
 installation_and_usage
+annotations
 ```