From fbe0cd53820a47177a61e60dda2e17d576c969db Mon Sep 17 00:00:00 2001 From: Douglas Thor Date: Thu, 31 Jul 2025 20:23:38 -0700 Subject: [PATCH 1/2] docs(gazelle): Start migrating Gazelle docs Part of #3082 + 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 + Also a drive-by update to building and running docs _without_ `ibazel`. --- docs/BUILD.bazel | 2 +- docs/README.md | 14 +++++++++++++ docs/gazelle.md | 9 -------- docs/index.md | 2 +- gazelle/README.md | 29 ++++---------------------- gazelle/docs/BUILD.bazel | 5 +++++ gazelle/docs/index.md | 45 ++++++++++++++++++++++++++++++++++++++++ 7 files changed, 70 insertions(+), 36 deletions(-) delete mode 100644 docs/gazelle.md create mode 100644 gazelle/docs/BUILD.bazel create mode 100644 gazelle/docs/index.md diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index 852c4d4fa6..d80b486879 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -56,7 +56,7 @@ sphinx_docs( "_*", "*.inv*", ], - ), + ) + ["//gazelle/docs"], config = "conf.py", formats = [ "html", diff --git a/docs/README.md b/docs/README.md index 456f1cfd64..1316d733bb 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/gazelle.md b/docs/gazelle.md deleted file mode 100644 index 60b46faf2c..0000000000 --- a/docs/gazelle.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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 update existing build files to include new sources, dependencies, and options. - -Bazel may run Gazelle using the Gazelle rule, or Gazelle may be installed and run as a command line tool. - -See the documentation for Gazelle with `rules_python` in the {gh-path}`gazelle` -directory. diff --git a/docs/index.md b/docs/index.md index 25b423c6c3..bdc6982ad5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -99,7 +99,7 @@ pypi/index Toolchains coverage precompiling -gazelle +gazelle/docs/index REPL Extending Contributing diff --git a/gazelle/README.md b/gazelle/README.md index 8b088a4e70..3ad3637b20 100644 --- a/gazelle/README.md +++ b/gazelle/README.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 diff --git a/gazelle/docs/BUILD.bazel b/gazelle/docs/BUILD.bazel new file mode 100644 index 0000000000..7c6b6fd56e --- /dev/null +++ b/gazelle/docs/BUILD.bazel @@ -0,0 +1,5 @@ +filegroup( + name = "docs", + srcs = glob(["*.md"]), + visibility = ["//visibility:public"], +) diff --git a/gazelle/docs/index.md b/gazelle/docs/index.md new file mode 100644 index 0000000000..f35599f759 --- /dev/null +++ b/gazelle/docs/index.md @@ -0,0 +1,45 @@ +# Gazelle Plugin + +[Gazelle][gazelle] is a build file generator for Bazel projects. It can +create new {code}`BUILD` or {code}`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 {code}`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 +{code}`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://docs.bazel.build/versions/5.0.0/bzlmod.html + +Gazelle is non-destructive. It will try to leave your edits to {code}`BUILD` +files alone, only making updates to {code}`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 {code}`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 {code}`gazelle` program has multiple commands. At present, only +the {code}`update` command (the default) does anything for Python code. + + +```{toctree} +:maxdepth: 1 +``` From ccf3387efe86b234c1b0f28b686c3a9a363131fc Mon Sep 17 00:00:00 2001 From: Douglas Thor Date: Sat, 2 Aug 2025 04:48:27 +0000 Subject: [PATCH 2/2] updates from review --- gazelle/docs/index.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/gazelle/docs/index.md b/gazelle/docs/index.md index f35599f759..ea20e9c3e0 100644 --- a/gazelle/docs/index.md +++ b/gazelle/docs/index.md @@ -1,7 +1,7 @@ # Gazelle Plugin [Gazelle][gazelle] is a build file generator for Bazel projects. It can -create new {code}`BUILD` or {code}`BUILD.bazel` files for a project that +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. @@ -11,11 +11,11 @@ Bazel may run Gazelle using the Gazelle rule, or Gazelle may be installed and ru as a command line tool. The {gh-path}`gazelle` directory contains a plugin for Gazelle -that generates {code}`BUILD` files content for Python code. When Gazelle is +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 -{code}`stdlib` changes with every minor version release. Distributors of Gazelle +`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. @@ -25,19 +25,19 @@ older documentation that includes instructions on how to use Gazelle without using bzlmod as your dependency manager. ::: -[bzlmod]: https://docs.bazel.build/versions/5.0.0/bzlmod.html +[bzlmod]: https://bazel.build/external/module -Gazelle is non-destructive. It will try to leave your edits to {code}`BUILD` -files alone, only making updates to {code}`py_*` targets. However it **will +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 {code}`rules_python` extension assumes some conventions about your Python code. +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 {code}`gazelle` program has multiple commands. At present, only -the {code}`update` command (the default) does anything for Python code. +Note that the `gazelle` program has multiple commands. At present, only +the `update` command (the default) does anything for Python code. ```{toctree}