docs(gazelle): document the python_resolve_sibling_imports directive (#4437)

Document the `python_resolve_sibling_imports` gazelle directive, which
only had
a "Detailed docs are not yet written" placeholder.

Since 1.6.0 (#3106) gazelle does not resolve absolute imports to sibling
modules by default, so e.g. `from typing import TYPE_CHECKING` next to a
`typing.py` file resolves to the standard library. The docs explain this
default, how to depend on the sibling module with a relative import, and
how
to restore the previous behavior with
`# gazelle:python_resolve_sibling_imports true`.

The README of the `sibling_imports` test case claimed that resolving
sibling
imports is the default, which is fixed as well.

Fixes #3097

gazelle/docs/directives.md

diff --git a/gazelle/docs/directives.md b/gazelle/docs/directives.md
index 5d3ddf7..949a8e5 100644
--- a/gazelle/docs/directives.md
+++ b/gazelle/docs/directives.md
@@ -823,14 +823,46 @@
 (directive-python-resolve-sibling-imports)=
 ## `python_resolve_sibling_imports`
 
+Controls whether an absolute import can be resolved to a module in the same
+directory (a sibling module). It defaults to `false`, which follows the
+Python 3 import rules: `import foo` refers to a top-level `foo` module, not to a
+`foo.py` next to the importing file.
+
+For example, given:
+
+```
+pkg/
+├── BUILD.bazel
+├── foo.py
+└── typing.py
+```
+
+and `pkg/foo.py` containing:
+
+```python
+from typing import TYPE_CHECKING
+```
+
+Gazelle resolves the import to the standard library `typing` module and does
+not add a dependency on `pkg/typing.py` ({gh-issue}`3097`). To depend on the
+sibling module, use a relative import, e.g. `from .typing import MyType`,
+together with the
+[`python_experimental_allow_relative_imports`](#directive-python-experimental-allow-relative-imports)
+directive.
+
+Setting the directive to `true` restores the behavior from before 1.6.0
+(Python 2's implicit relative imports), where absolute imports such as
+`import a` or `from b import run` in `pkg/foo.py` are resolved to the sibling
+`pkg/a.py` and `pkg/b.py` modules:
+
+```starlark
+# gazelle:python_resolve_sibling_imports true
+```
+
 :::{versionadded} 1.6.0
 {gh-pr}`3106`
 :::
 
-:::{error}
-Detailed docs are not yet written.
-:::
-
 (directive-python-include-ancestor-conftest)=
 ## `python_include_ancestor_conftest`
 

gazelle/python/testdata/sibling_imports/README.md

diff --git a/gazelle/python/testdata/sibling_imports/README.md b/gazelle/python/testdata/sibling_imports/README.md
index d21a671..68a4d62 100644
--- a/gazelle/python/testdata/sibling_imports/README.md
+++ b/gazelle/python/testdata/sibling_imports/README.md
@@ -1,8 +1,8 @@
 # Sibling imports
 
 This test case asserts that imports from sibling modules are resolved correctly
-when the `python_resolve_sibling_imports` directive is enabled (default
-behavior). It covers 3 different types of imports in `pkg/unit_test.py`:
+when the `python_resolve_sibling_imports` directive is enabled. It covers 3
+different types of imports in `pkg/unit_test.py`:
 
 - `import a` - resolves to the sibling `a.py` in the same package
 - `import test_util` - resolves to the sibling `test_util.py` in the same