Skip to content

Commit 3c88a5b

Browse files
dougthor42dougthor42
authored
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.
1 parent 54397d7 commit 3c88a5b

File tree

3 files changed

+195
-185
lines changed

3 files changed

+195
-185
lines changed

‎gazelle/README.md‎

Lines changed: 0 additions & 185 deletions
Original file line numberDiff line numberDiff line change
@@ -390,191 +390,6 @@ py_proto_library(
390390

391391
When `false`, Gazelle will ignore any `py_proto_library`, including previously-generated or hand-created rules.
392392

393-
### Annotations
394-
395-
*Annotations* refer to comments found _within Python files_ that configure how
396-
Gazelle acts for that particular file.
397-
398-
Annotations have the form:
399-
400-
```python
401-
# gazelle:annotation_name value
402-
```
403-
404-
and can reside anywhere within a Python file where comments are valid. For example:
405-
406-
```python
407-
import foo
408-
# gazelle:annotation_name value
409-
410-
def bar(): # gazelle:annotation_name value
411-
pass
412-
```
413-
414-
The annotations are:
415-
416-
| **Annotation** | **Default value** |
417-
|---------------------------------------------------------------|-------------------|
418-
| [`# gazelle:ignore imports`](#annotation-ignore) | N/A |
419-
| Tells Gazelle to ignore import statements. `imports` is a comma-separated list of imports to ignore. | |
420-
| [`# gazelle:include_dep targets`](#annotation-include_dep) | N/A |
421-
| 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. | |
422-
| [`# gazelle:include_pytest_conftest bool`](#annotation-include_pytest_conftest) | N/A |
423-
| Whether or not to include a sibling `:conftest` target in the deps of a `py_test` target. Default behaviour is to include `:conftest`. | |
424-
425-
426-
#### Annotation: `ignore`
427-
428-
This annotation accepts a comma-separated string of values. Values are names of Python
429-
imports that Gazelle should _not_ include in target dependencies.
430-
431-
The annotation can be added multiple times, and all values are combined and
432-
de-duplicated.
433-
434-
For `python_generation_mode = "package"`, the `ignore` annotations
435-
found across all files included in the generated target are removed from `deps`.
436-
437-
Example:
438-
439-
```python
440-
import numpy # a pypi package
441-
442-
# gazelle:ignore bar.baz.hello,foo
443-
import bar.baz.hello
444-
import foo
445-
446-
# Ignore this import because _reasons_
447-
import baz # gazelle:ignore baz
448-
```
449-
450-
will cause Gazelle to generate:
451-
452-
```starlark
453-
deps = ["@pypi//numpy"],
454-
```
455-
456-
457-
#### Annotation: `include_dep`
458-
459-
This annotation accepts a comma-separated string of values. Values _must_
460-
be Python targets, but _no validation is done_. If a value is not a Python
461-
target, building will result in an error saying:
462-
463-
```
464-
<target> does not have mandatory providers: 'PyInfo' or 'CcInfo' or 'PyInfo'.
465-
```
466-
467-
Adding non-Python targets to the generated target is a feature request being
468-
tracked in [Issue #1865](https://github.com/bazel-contrib/rules_python/issues/1865).
469-
470-
The annotation can be added multiple times, and all values are combined
471-
and de-duplicated.
472-
473-
For `python_generation_mode = "package"`, the `include_dep` annotations
474-
found across all files included in the generated target are included in `deps`.
475-
476-
Example:
477-
478-
```python
479-
# gazelle:include_dep //foo:bar,:hello_world,//:abc
480-
# gazelle:include_dep //:def,//foo:bar
481-
import numpy # a pypi package
482-
```
483-
484-
will cause Gazelle to generate:
485-
486-
```starlark
487-
deps = [
488-
":hello_world",
489-
"//:abc",
490-
"//:def",
491-
"//foo:bar",
492-
"@pypi//numpy",
493-
]
494-
```
495-
496-
#### Annotation: `include_pytest_conftest`
497-
498-
Added in [#3080][gh3080].
499-
500-
[gh3080]: https://github.com/bazel-contrib/rules_python/pull/3080
501-
502-
This annotation accepts any string that can be parsed by go's
503-
[`strconv.ParseBool`][ParseBool]. If an unparsable string is passed, the
504-
annotation is ignored.
505-
506-
[ParseBool]: https://pkg.go.dev/strconv#ParseBool
507-
508-
Starting with [`rules_python` 0.14.0][rules-python-0.14.0] (specifically [PR #879][gh879]),
509-
Gazelle will include a `:conftest` dependency to an `py_test` target that is in
510-
the same directory as `conftest.py`.
511-
512-
[rules-python-0.14.0]: https://github.com/bazel-contrib/rules_python/releases/tag/0.14.0
513-
[gh879]: https://github.com/bazel-contrib/rules_python/pull/879
514-
515-
This annotation allows users to adjust that behavior. To disable the behavior, set
516-
the annotation value to "false":
517-
518-
```
519-
# some_file_test.py
520-
# gazelle:include_pytest_conftest false
521-
```
522-
523-
Example:
524-
525-
Given a directory tree like:
526-
527-
```
528-
.
529-
├── BUILD.bazel
530-
├── conftest.py
531-
└── some_file_test.py
532-
```
533-
534-
The default Gazelle behavior would create:
535-
536-
```starlark
537-
py_library(
538-
name = "conftest",
539-
testonly = True,
540-
srcs = ["conftest.py"],
541-
visibility = ["//:__subpackages__"],
542-
)
543-
544-
py_test(
545-
name = "some_file_test",
546-
srcs = ["some_file_test.py"],
547-
deps = [":conftest"],
548-
)
549-
```
550-
551-
When `# gazelle:include_pytest_conftest false` is found in `some_file_test.py`
552-
553-
```python
554-
# some_file_test.py
555-
# gazelle:include_pytest_conftest false
556-
```
557-
558-
Gazelle will generate:
559-
560-
```starlark
561-
py_library(
562-
name = "conftest",
563-
testonly = True,
564-
srcs = ["conftest.py"],
565-
visibility = ["//:__subpackages__"],
566-
)
567-
568-
py_test(
569-
name = "some_file_test",
570-
srcs = ["some_file_test.py"],
571-
)
572-
```
573-
574-
See [Issue #3076][gh3076] for more information.
575-
576-
[gh3076]: https://github.com/bazel-contrib/rules_python/issues/3076
577-
578393

579394
#### Directive: `python_experimental_allow_relative_imports`
580395
Enables experimental support for resolving relative imports in

‎gazelle/docs/annotations.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Annotations
2+
3+
*Annotations* refer to comments found _within Python files_ that configure how
4+
Gazelle acts for that particular file.
5+
6+
Annotations have the form:
7+
8+
```python
9+
# gazelle:annotation_name value
10+
```
11+
12+
and can reside anywhere within a Python file where comments are valid. For example:
13+
14+
```python
15+
import foo
16+
# gazelle:annotation_name value
17+
18+
def bar(): # gazelle:annotation_name value
19+
pass
20+
```
21+
22+
The annotations are:
23+
24+
* [`# gazelle:ignore imports`](#ignore)
25+
* Default: n/a
26+
* Allowed Values: A comma-separated string of python package names
27+
* Tells Gazelle to ignore import statements. `imports` is a comma-separated
28+
list of imports to ignore.
29+
* [`# gazelle:include_dep targets`](#include-dep)
30+
* Default: n/a
31+
* Allowed Values: A string
32+
* Tells Gazelle to include a set of dependencies, even if they are not imported
33+
in a Python module. `targets` is a comma-separated list of target names
34+
to include as dependencies.
35+
* [`# gazelle:include_pytest_conftest bool`](#include-pytest-conftest)
36+
* Default: n/a
37+
* Allowed Values: `true`, `false`
38+
* Whether or not to include a sibling `:conftest` target in the `deps`
39+
of a {bzl:obj}`py_test` target. The default behaviour is to include `:conftest`
40+
(i.e.: `# gazelle:include_pytest_conftest true`).
41+
42+
43+
## `ignore`
44+
45+
This annotation accepts a comma-separated string of values. Values are names of
46+
Python imports that Gazelle should _not_ include in target dependencies.
47+
48+
The annotation can be added multiple times, and all values are combined and
49+
de-duplicated.
50+
51+
For `python_generation_mode = "package"`, the `ignore` annotations
52+
found across all files included in the generated target are removed from
53+
`deps`.
54+
55+
### Example:
56+
57+
```python
58+
import numpy # a pypi package
59+
60+
# gazelle:ignore bar.baz.hello,foo
61+
import bar.baz.hello
62+
import foo
63+
64+
# Ignore this import because _reasons_
65+
import baz # gazelle:ignore baz
66+
```
67+
68+
will cause Gazelle to generate:
69+
70+
```starlark
71+
deps = ["@pypi//numpy"],
72+
```
73+
74+
75+
## `include_dep`
76+
77+
This annotation accepts a comma-separated string of values. Values _must_
78+
be Python targets, but _no validation is done_. If a value is not a Python
79+
target, building will result in an error saying:
80+
81+
```
82+
<target> does not have mandatory providers: 'PyInfo' or 'CcInfo' or 'PyInfo'.
83+
```
84+
85+
Adding non-Python targets to the generated target is a feature request being
86+
tracked in {gh-issue}`1865`.
87+
88+
The annotation can be added multiple times, and all values are combined
89+
and de-duplicated.
90+
91+
For `python_generation_mode = "package"`, the `include_dep` annotations
92+
found across all files included in the generated target are included in
93+
`deps`.
94+
95+
### Example:
96+
97+
```python
98+
# gazelle:include_dep //foo:bar,:hello_world,//:abc
99+
# gazelle:include_dep //:def,//foo:bar
100+
import numpy # a pypi package
101+
```
102+
103+
will cause Gazelle to generate:
104+
105+
```starlark
106+
deps = [
107+
":hello_world",
108+
"//:abc",
109+
"//:def",
110+
"//foo:bar",
111+
"@pypi//numpy",
112+
]
113+
```
114+
115+
116+
## `include_pytest_conftest`
117+
118+
:::{versionadded} VERSION_NEXT_FEATURE
119+
{gh-pr}`3080`
120+
:::
121+
122+
This annotation accepts any string that can be parsed by go's
123+
[`strconv.ParseBool`][ParseBool]. If an unparsable string is passed, the
124+
annotation is ignored.
125+
126+
[ParseBool]: https://pkg.go.dev/strconv#ParseBool
127+
128+
Starting with [`rules_python` 0.14.0][rules-python-0.14.0] (specifically
129+
{gh-pr}`879`), Gazelle will include a `:conftest` dependency to a
130+
{bzl:obj}`py_test` target that is in the same directory as `conftest.py`.
131+
132+
[rules-python-0.14.0]: https://github.com/bazel-contrib/rules_python/releases/tag/0.14.0
133+
134+
This annotation allows users to adjust that behavior. To disable the behavior,
135+
set the annotation value to `false`:
136+
137+
```
138+
# some_file_test.py
139+
# gazelle:include_pytest_conftest false
140+
```
141+
142+
### Example:
143+
144+
Given a directory tree like:
145+
146+
```
147+
.
148+
├── BUILD.bazel
149+
├── conftest.py
150+
└── some_file_test.py
151+
```
152+
153+
The default Gazelle behavior would create:
154+
155+
```starlark
156+
py_library(
157+
name = "conftest",
158+
testonly = True,
159+
srcs = ["conftest.py"],
160+
visibility = ["//:__subpackages__"],
161+
)
162+
163+
py_test(
164+
name = "some_file_test",
165+
srcs = ["some_file_test.py"],
166+
deps = [":conftest"],
167+
)
168+
```
169+
170+
When `# gazelle:include_pytest_conftest false` is found in
171+
`some_file_test.py`
172+
173+
```python
174+
# some_file_test.py
175+
# gazelle:include_pytest_conftest false
176+
```
177+
178+
Gazelle will generate:
179+
180+
```starlark
181+
py_library(
182+
name = "conftest",
183+
testonly = True,
184+
srcs = ["conftest.py"],
185+
visibility = ["//:__subpackages__"],
186+
)
187+
188+
py_test(
189+
name = "some_file_test",
190+
srcs = ["some_file_test.py"],
191+
)
192+
```
193+
194+
See {gh-issue}`3076` for more information.

‎gazelle/docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,4 +43,5 @@ the `update` command (the default) does anything for Python code.
4343
```{toctree}
4444
:maxdepth: 1
4545
installation_and_usage
46+
annotations
4647
```

0 commit comments

Comments
 (0)