docs(gazelle): Use definition lists instead of bullets for Gazelle docs (#3154)
Primary updates:
+ Use Definition List
+ Move the annotation/directive description to the definition line
Secondary updates:
+ Add missing directive arguments. For example, `#
gazelle:python_extension` becomes `# gazelle:python_extension value`.
+ Address WIP lines for "allowed values"
+ Link things with `{term}`.
Fixes #3142.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e7441b..2535a0f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -70,7 +70,10 @@
* (gazelle) Switched back to smacker/go-tree-sitter, fixing
[#2630](https://github.com/bazel-contrib/rules_python/issues/2630)
* (ci) We are now testing on Ubuntu 22.04 for RBE and non-RBE configurations.
-* (core) #!/usr/bin/env bash is now used as a shebang in the stage1 bootstrap template.
+* (core) `#!/usr/bin/env bash` is now used as a shebang in the stage1 bootstrap template.
+* (gazelle:docs) The Gazelle docs have been migrated from {gh-path}`gazelle/README.md` to
+ {gh-path}`gazelle/docs` and are now available on the primary documentation site
+ at https://rules-python.readthedocs.io/en/latest/gazelle/docs/index.html
{#v0-0-0-fixed}
### Fixed
@@ -108,8 +111,8 @@
{#v0-0-0-added}
### Added
* (repl) Default stub now has tab completion, where `readline` support is available,
- see ([#3114](https://github.com/bazel-contrib/rules_python/pull/3114)).
- ([#3114](https://github.com/bazel-contrib/rules_python/pull/3114)).
+ see ([#3114](https://github.com/bazel-contrib/rules_python/pull/3114)).
+ ([#3114](https://github.com/bazel-contrib/rules_python/pull/3114)).
* (pypi) To configure the environment for `requirements.txt` evaluation, use the newly added
developer preview of the `pip.default` tag class. Only `rules_python` and root modules can use
this feature. You can also configure custom `config_settings` using `pip.default`.
diff --git a/gazelle/README.md b/gazelle/README.md
index 128fb1f..1cbef2d 100644
--- a/gazelle/README.md
+++ b/gazelle/README.md
@@ -2,5 +2,5 @@
:::{note}
The gazelle plugin docs have been migrated to our primary documentation on
-ReadTheDocs. Please see https://rules-python.readthedocs.io/gazelle/docs/index.html.
+ReadTheDocs. Please see https://rules-python.readthedocs.io/en/latest/gazelle/docs/index.html.
:::
diff --git a/gazelle/docs/annotations.md b/gazelle/docs/annotations.md
index cc87543..da6e58f 100644
--- a/gazelle/docs/annotations.md
+++ b/gazelle/docs/annotations.md
@@ -21,23 +21,26 @@
The annotations are:
-* [`# gazelle:ignore imports`](#ignore)
+{.glossary}
+[`# gazelle:ignore imports`](#ignore)
+: Tells Gazelle to ignore import statements. `imports` is a comma-separated
+ list of imports to 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)
+
+[`# gazelle:include_dep targets`](#include-dep)
+: 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.
* 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)
+ * Allowed Values: A comma-separated string of targets
+
+[`# gazelle:include_pytest_conftest bool`](#include-pytest-conftest)
+: 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`).
* 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`
diff --git a/gazelle/docs/directives.md b/gazelle/docs/directives.md
index 9221c60..ecc30a9 100644
--- a/gazelle/docs/directives.md
+++ b/gazelle/docs/directives.md
@@ -15,136 +15,159 @@
The Python-specific directives are:
-* [`# gazelle:python_extension`](#python-extension)
+{.glossary}
+[`# gazelle:python_extension value`](#python-extension)
+: Controls whether the Python extension is enabled or not. Sub-packages
+ inherit this value.
* Default: `enabled`
* Allowed Values: `enabled`, `disabled`
- * Controls whether the Python extension is enabled or not. Sub-packages
- inherit this value.
-* [`# gazelle:python_root`](#python-root)
+
+[`# gazelle:python_root`](#python-root)
+: Sets a Bazel package as a Python root. This is used on monorepos with
+ multiple Python projects that don't share the top-level of the workspace
+ as the root.
* Default: n/a
* Allowed Values: None. This direcive does not consume values.
- * Sets a Bazel package as a Python root. This is used on monorepos with
- multiple Python projects that don't share the top-level of the workspace
- as the root.
-* [`# gazelle:python_manifest_file_name`](#python-manifest-file-name)
+
+[`# gazelle:python_manifest_file_name value`](#python-manifest-file-name)
+: Overrides the default manifest file name.
* Default: `gazelle_python.yaml`
* Allowed Values: A string
- * Overrides the default manifest file name.
-* [`# gazelle:python_ignore_files`](#python-ignore-files)
+
+[`# gazelle:python_ignore_files value`](#python-ignore-files)
+: Controls the files which are ignored from the generated targets.
* Default: n/a
- * Allowed Values: WIP
- * Controls the files which are ignored from the generated targets.
-* [`# gazelle:python_ignore_dependencies`](#python-ignore-dependencies)
+ * Allowed Values: A comma-separated list of strings.
+
+[`# gazelle:python_ignore_dependencies value`](#python-ignore-dependencies)
+: Controls the ignored dependencies from the generated targets.
* Default: n/a
- * Allowed Values: WIP
- * Controls the ignored dependencies from the generated targets.
-* [`# gazelle:python_validate_import_statements`](#python-validate-import-statements)
+ * Allowed Values: A comma-separated list of strings.
+
+[`# gazelle:python_validate_import_statements bool`](#python-validate-import-statements)
+: Controls whether the Python import statements should be validated.
* Default: `true`
* Allowed Values: `true`, `false`
- * Controls whether the Python import statements should be validated.
-* [`# gazelle:python_generation_mode`](#python-generation-mode)
+
+[`# gazelle:python_generation_mode value`](#python-generation-mode)
+: Controls the target generation mode.
* Default: `package`
* Allowed Values: `file`, `package`, `project`
- * Controls the target generation mode.
-* [`# gazelle:python_generation_mode_per_file_include_init`](#python-generation-mode-per-file-include-init)
+
+[`# gazelle:python_generation_mode_per_file_include_init bool`](#python-generation-mode-per-file-include-init)
+: Controls whether `__init__.py` files are included as srcs in each
+ generated target when target generation mode is "file".
* Default: `false`
* Allowed Values: `true`, `false`
- * Controls whether `__init__.py` files are included as srcs in each
- generated target when target generation mode is "file".
-* [`# gazelle:python_generation_mode_per_package_require_test_entry_point`](python-generation-mode-per-package-require-test-entry-point)
+
+[`# gazelle:python_generation_mode_per_package_require_test_entry_point bool`](python-generation-mode-per-package-require-test-entry-point)
+: Controls whether a file called `__test__.py` or a target called
+ `__test__` is required to generate one test target per package in
+ package mode.
* Default: `true`
* Allowed Values: `true`, `false`
- * Controls whether a file called `__test__.py` or a target called
- `__test__` is required to generate one test target per package in
- package mode.
-* [`# gazelle:python_library_naming_convention`](#python-library-naming-convention)
+
+[`# gazelle:python_library_naming_convention value`](#python-library-naming-convention)
+: Controls the {bzl:obj}`py_library` naming convention. It interpolates
+ `$package_name$` with the Bazel package name. E.g. if the Bazel package
+ name is `foo`, setting this to `$package_name$_my_lib` would result in a
+ generated target named `foo_my_lib`.
* Default: `$package_name$`
* Allowed Values: A string containing `"$package_name$"`
- * Controls the {bzl:obj}`py_library` naming convention. It interpolates
- `$package_name$` with the Bazel package name. E.g. if the Bazel package
- name is `foo`, setting this to `$package_name$_my_lib` would result in a
- generated target named `foo_my_lib`.
-* [`# gazelle:python_binary_naming_convention`](#python-binary-naming-convention)
+
+[`# gazelle:python_binary_naming_convention value`](#python-binary-naming-convention)
+: Controls the {bzl:obj}`py_binary` naming convention. Follows the same interpolation
+ rules as `python_library_naming_convention`.
* Default: `$package_name$_bin`
* Allowed Values: A string containing `"$package_name$"`
- * Controls the {bzl:obj}`py_binary` naming convention. Follows the same interpolation
- rules as `python_library_naming_convention`.
-* [`# gazelle:python_test_naming_convention`](#python-test-naming-convention)
+
+[`# gazelle:python_test_naming_convention value`](#python-test-naming-convention)
+: Controls the {bzl:obj}`py_test` naming convention. Follows the same interpolation
+ rules as `python_library_naming_convention`.
* Default: `$package_name$_test`
* Allowed Values: A string containing `"$package_name$"`
- * Controls the {bzl:obj}`py_test` naming convention. Follows the same interpolation
- rules as `python_library_naming_convention`.
-* [`# gazelle:python_proto_naming_convention`](#python-proto-naming-convention)
+
+[`# gazelle:python_proto_naming_convention value`](#python-proto-naming-convention)
+: Controls the {bzl:obj}`py_proto_library` naming convention. It interpolates
+ `$proto_name$` with the {bzl:obj}`proto_library` rule name, minus any trailing
+ `_proto`. E.g. if the {bzl:obj}`proto_library` name is `foo_proto`, setting this
+ to `$proto_name$_my_lib` would render to `foo_my_lib`.
* Default: `$proto_name$_py_pb2`
* Allowed Values: A string containing `"$proto_name$"`
- * Controls the {bzl:obj}`py_proto_library` naming convention. It interpolates
- `$proto_name$` with the {bzl:obj}`proto_library` rule name, minus any trailing
- `_proto`. E.g. if the {bzl:obj}`proto_library` name is `foo_proto`, setting this
- to `$proto_name$_my_lib` would render to `foo_my_lib`.
-* [`# gazelle:resolve py ...`](#resolve-py)
+
+[`# gazelle:resolve py import-lang import-string label`](#resolve-py)
+: Instructs the plugin what target to add as a dependency to satisfy a given
+ import statement. The syntax is `# gazelle:resolve py import-string label`
+ where `import-string` is the symbol in the python `import` statement,
+ and `label` is the Bazel label that Gazelle should write in `deps`.
* Default: n/a
* Allowed Values: See the [bazel-gazelle docs][gazelle-directives]
- * Instructs the plugin what target to add as a dependency to satisfy a given
- import statement. The syntax is `# gazelle:resolve py import-string label`
- where `import-string` is the symbol in the python `import` statement,
- and `label` is the Bazel label that Gazelle should write in `deps`.
-* [`# gazelle:python_default_visibility labels`](python-default-visibility)
+
+[`# gazelle:python_default_visibility labels`](python-default-visibility)
+: Instructs gazelle to use these visibility labels on all python targets.
+ `labels` is a comma-separated list of labels (without spaces).
* Default: `//$python_root$:__subpackages__`
* Allowed Values: A string
- * Instructs gazelle to use these visibility labels on all python targets.
- `labels` is a comma-separated list of labels (without spaces).
-* [`# gazelle:python_visibility label`](python-visibility)
+
+[`# gazelle:python_visibility label`](python-visibility)
+: Appends additional visibility labels to each generated target. This r
+ directive can be set multiple times.
* Default: n/a
* Allowed Values: A string
- * Appends additional visibility labels to each generated target. This r
- directive can be set multiple times.
-* [`# gazelle:python_test_file_pattern`](python-test-file-pattern)
+
+[`# gazelle:python_test_file_pattern value`](python-test-file-pattern)
+: Filenames matching these comma-separated {command}`glob`s will be mapped to
+ {bzl:obj}`py_test` targets.
* Default: `*_test.py,test_*.py`
* Allowed Values: A glob string
- * Filenames matching these comma-separated {command}`glob`s will be mapped to
- {bzl:obj}`py_test` targets.
-* [`# gazelle:python_label_convention`](#python-label-convention)
+
+[`# gazelle:python_label_convention value`](#python-label-convention)
+: Defines the format of the distribution name in labels to third-party deps.
+ Useful for using Gazelle plugin with other rules with different repository
+ conventions (e.g. `rules_pycross`). Full label is always prepended with
+ the `pip` repository name, e.g. `@pip//numpy` if your
+ `MODULE.bazel` has `use_repo(pip, "pip")` or `@pypi//numpy`
+ if your `MODULE.bazel` has `use_repo(pip, "pypi")`.
* Default: `$distribution_name$`
* Allowed Values: A string
- * Defines the format of the distribution name in labels to third-party deps.
- Useful for using Gazelle plugin with other rules with different repository
- conventions (e.g. `rules_pycross`). Full label is always prepended with
- the `pip` repository name, e.g. `@pip//numpy` if your
- `MODULE.bazel` has `use_repo(pip, "pip")` or `@pypi//numpy`
- if your `MODULE.bazel` has `use_repo(pip, "pypi")`.
-* [`# gazelle:python_label_normalization`](#python-label-normalization)
+
+[`# gazelle:python_label_normalization value`](#python-label-normalization)
+: Controls how distribution names in labels to third-party deps are
+ normalized. Useful for using Gazelle plugin with other rules with different
+ label conventions (e.g. `rules_pycross` uses PEP-503).
* Default: `snake_case`
* Allowed Values: `snake_case`, `none`, `pep503`
- * Controls how distribution names in labels to third-party deps are
- normalized. Useful for using Gazelle plugin with other rules with different
- label conventions (e.g. `rules_pycross` uses PEP-503).
-* [`# gazelle:python_experimental_allow_relative_imports`](#python-experimental-allow-relative-imports)
+
+[`# gazelle:python_experimental_allow_relative_imports bool`](#python-experimental-allow-relative-imports)
+: Controls whether Gazelle resolves dependencies for import statements that
+ use paths relative to the current package.
* Default: `false`
* Allowed Values: `true`, `false`
- * Controls whether Gazelle resolves dependencies for import statements that
- use paths relative to the current package.
-* [`# gazelle:python_generate_pyi_deps`](#python-generate-pyi-deps)
+
+[`# gazelle:python_generate_pyi_deps bool`](#python-generate-pyi-deps)
+: Controls whether to generate a separate `pyi_deps` attribute for
+ type-checking dependencies or merge them into the regular `deps`
+ attribute. When `false` (default), type-checking dependencies are
+ merged into `deps` for backward compatibility. When `true`, generates
+ separate `pyi_deps`. Imports in blocks with the format
+ `if typing.TYPE_CHECKING:` or `if TYPE_CHECKING:` and type-only stub
+ packages (eg. boto3-stubs) are recognized as type-checking dependencies.
* Default: `false`
* Allowed Values: `true`, `false`
- * Controls whether to generate a separate `pyi_deps` attribute for
- type-checking dependencies or merge them into the regular `deps`
- attribute. When `false` (default), type-checking dependencies are
- merged into `deps` for backward compatibility. When `true`, generates
- separate `pyi_deps`. Imports in blocks with the format
- `if typing.TYPE_CHECKING:` or `if TYPE_CHECKING:` and type-only stub
- packages (eg. boto3-stubs) are recognized as type-checking dependencies.
-* [`# gazelle:python_generate_proto`](#python-generate-proto)
+
+[`# gazelle:python_generate_proto bool`](#python-generate-proto)
+: Controls whether to generate a {bzl:obj}`py_proto_library` for each
+ {bzl:obj}`proto_library` in the package. By default we load this rule from the
+ `@protobuf` repository; use `gazelle:map_kind` if you need to load this
+ from somewhere else.
* Default: `false`
* Allowed Values: `true`, `false`
- * Controls whether to generate a {bzl:obj}`py_proto_library` for each
- {bzl:obj}`proto_library` in the package. By default we load this rule from the
- `@protobuf` repository; use `gazelle:map_kind` if you need to load this
- from somewhere else.
-* [`# gazelle:python_resolve_sibling_imports`](#python-resolve-sibling-imports)
+
+[`# gazelle:python_resolve_sibling_imports bool`](#python-resolve-sibling-imports)
+: Allows absolute imports to be resolved to sibling modules (Python 2's
+ behavior without `absolute_import`).
* Default: `false`
* Allowed Values: `true`, `false`
- * Allows absolute imports to be resolved to sibling modules (Python 2's
- behavior without `absolute_import`).
## `python_extension`
diff --git a/gazelle/docs/installation_and_usage.md b/gazelle/docs/installation_and_usage.md
index 123f30a..1858f41 100644
--- a/gazelle/docs/installation_and_usage.md
+++ b/gazelle/docs/installation_and_usage.md
@@ -156,7 +156,7 @@
### Libraries
Python source files are those ending in `.py` that are not matched as a test
-file via the `# gazelle:python_test_file_pattern` directive. By default,
+file via the {term}`# gazelle:python_test_file_pattern value` directive. By default,
python source files are all `*.py` files except for `*_test.py` and
`test_*.py`.
@@ -179,7 +179,7 @@
A {bzl:obj}`py_test` target is added to the `BUILD(.bazel)` file when gazelle
encounters a file named `__test__.py` or when files matching the
-`# gazelle:python_test_file_pattern` directive are found.
+{term}`# gazelle:python_test_file_pattern value` directive are found.
For example, if we had a folder that is a package named "foo" we could have a
Python file named `foo_test.py` and gazelle would create a {bzl:obj}`py_test`
@@ -198,7 +198,7 @@
```
You can control the naming convention for test targets using the
-`# gazelle:python_test_naming_convention` directive.
+{term}`# gazelle:python_test_naming_convention value` directive.
### Binaries
@@ -217,7 +217,7 @@
Gazelle will create a {bzl:obj}`py_binary` target for every module with such
a line, with the target name the same as the module name.
-If the `# gazelle:python_generation_mode` directive is set to `file`, then
+If the {term}`# gazelle:python_generation_mode value` directive is set to `file`, then
instead of one {bzl:obj}`py_binary` target per module, Gazelle will create
one {bzl:obj}`py_binary` target for each file with such a line, and the name
of the target will match the name of the script.