docs(gazelle): Start migrating Gazelle docs to ReadTheDocs, part 1 of ~5 (#3129)

Part of #3082

First of probably 5 PRs.

+ Set up the Bazel config so that the rules_python root docs can
reference and use the gazelle/docs directory.
+ Replace the original `docs/gazelle.md` with `gazelle/docs/index.md`
+ Migrate general info from `gazelle/README.md` to
`gazelle/docs/index.md`
+ Mechanical updates:
  + Wrap at ~80 chars
  + Use MyST directives and roles.
+ Also a drive-by update to building and running docs _without_
`ibazel`.

Author: dougthor42

docs/BUILD.bazel

@@ -55,7 +55,7 @@ sphinx_docs(
             "_*",
             "*.inv*",
         ],
-    ),
+    ) + ["//gazelle/docs"],
     config = "conf.py",
     formats = [
         "html",

docs/README.md

@@ -28,6 +28,20 @@ changes and re-run the build process, and you can simply refresh your browser to
 see the changes. Using ibazel is not required; you can manually run the
 equivalent bazel command if desired.
 
+An alternative to `ibazel` is using `inotify` on Linux systems:
+
+```
+inotifywait --event modify --monitor . --recursive --includei '^.*\.md$' |
+while read -r dir events filename; do bazel build //docs:docs; done;
+```
+
+And lastly, a poor-man's `ibazel` and `inotify` is simply `watch` with
+a reasonable interval like 10s:
+
+```
+watch --interval 10 bazel build //docs:docs
+```
+
 ### Installing ibazel
 
 The `ibazel` tool can be used to automatically rebuild the docs as you

docs/gazelle.md

@@ -99,7 +99,7 @@ pypi/index
 Toolchains <toolchains>
 coverage
 precompiling
-gazelle
+gazelle/docs/index
 REPL <repl>
 Extending <extending>
 Contributing <contributing>

docs/index.md

@@ -1,19 +1,10 @@
 # Python Gazelle plugin
 
-[Gazelle](https://github.com/bazelbuild/bazel-gazelle)
-is a build file generator for Bazel projects. It can create new BUILD.bazel files for a project that follows language conventions, and it can update existing build files to include new sources, dependencies, and options.
+:::{note}
+The gazelle plugin docs are being migrated to our primary documentation on
+ReadTheDocs. Please see https://rules-python.readthedocs.io/gazelle/docs/index.html.
+:::
 
-Gazelle may be run by Bazel using the gazelle rule, or it may be installed and run as a command line tool.
-
-This directory contains a plugin for
-[Gazelle](https://github.com/bazelbuild/bazel-gazelle)
-that generates BUILD files content for Python code. When Gazelle is run as a command line tool with this plugin, it embeds a Python interpreter resolved during the plugin build.
-The behavior of the plugin is slightly different with different version of the interpreter as the Python `stdlib` changes with every minor version release.
-Distributors of Gazelle binaries should, therefore, build a Gazelle binary for each OS+CPU architecture+Minor Python version combination they are targeting.
-
-The following instructions are for when you use [bzlmod](https://docs.bazel.build/versions/5.0.0/bzlmod.html).
-Please refer to older documentation that includes instructions on how to use Gazelle
-without using bzlmod as your dependency manager.
 
 ## Example
 
@@ -153,18 +144,6 @@ gazelle(
 That's it, now you can finally run `bazel run //:gazelle` anytime
 you edit Python code, and it should update your `BUILD` files correctly.
 
-## Usage
-
-Gazelle is non-destructive.
-It will try to leave your edits to BUILD files alone, only making updates to `py_*` targets.
-However it will remove dependencies that appear to be unused, so it's a
-good idea to check in your work before running Gazelle so you can easily
-revert any changes it made.
-
-The rules_python extension assumes some conventions about your Python code.
-These are noted below, and might require changes to your existing code.
-
-Note that the `gazelle` program has multiple commands. At present, only the `update` command (the default) does anything for Python code.
 
 ### Directives
 

gazelle/README.md

@@ -0,0 +1,5 @@
+filegroup(
+    name = "docs",
+    srcs = glob(["*.md"]),
+    visibility = ["//visibility:public"],
+)

gazelle/docs/BUILD.bazel

@@ -0,0 +1,45 @@
+# Gazelle Plugin
+
+[Gazelle][gazelle] is a build file generator for Bazel projects. It can
+create new `BUILD` or `BUILD.bazel` files for a project that
+follows language conventions and update existing build files to include new
+sources, dependencies, and options.
+
+[gazelle]: https://github.com/bazel-contrib/bazel-gazelle
+
+Bazel may run Gazelle using the Gazelle rule, or Gazelle may be installed and run
+as a command line tool.
+
+The {gh-path}`gazelle` directory contains a plugin for Gazelle
+that generates `BUILD` files content for Python code. When Gazelle is
+run as a command line tool with this plugin, it embeds a Python interpreter
+resolved during the plugin build. The behavior of the plugin is slightly
+different with different version of the interpreter as the Python
+`stdlib` changes with every minor version release. Distributors of Gazelle
+binaries should, therefore, build a Gazelle binary for each OS+CPU
+architecture+Minor Python version combination they are targeting.
+
+:::{note}
+These instructions are for when you use [bzlmod][bzlmod]. Please refer to
+older documentation that includes instructions on how to use Gazelle
+without using bzlmod as your dependency manager.
+:::
+
+[bzlmod]: https://bazel.build/external/module
+
+Gazelle is non-destructive. It will try to leave your edits to `BUILD`
+files alone, only making updates to `py_*` targets. However it **will
+remove** dependencies that appear to be unused, so it's a good idea to check
+in your work before running Gazelle so you can easily revert any changes it made.
+
+The `rules_python` extension assumes some conventions about your Python code.
+These are noted in the subsequent documents, and might require changes to your
+existing code.
+
+Note that the `gazelle` program has multiple commands. At present, only
+the `update` command (the default) does anything for Python code.
+
+
+```{toctree}
+:maxdepth: 1
+```