Skip to content

docs(gazelle): POC the bare minimum for linking modules_mapping in docs.#3140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dougthor42 wants to merge 1 commit into
base:main
Choose a base branch
from
Draft

docs(gazelle): POC the bare minimum for linking modules_mapping in docs. #3140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/BUILD.bazel
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -82,9 +82,15 @@ build_test(
targets = [":docs"],
)

alias(
name = "gazelle_modules_mapping_def_bzl",
actual = "@rules_python_gazelle_plugin//modules_mapping:def_bzl",
)

sphinx_stardocs(
name = "bzl_api_docs",
srcs = [
":gazelle_modules_mapping_def_bzl",

@dougthor42dougthor42Aug 5, 2025

Copy link
Copy Markdown
CollaboratorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sphinx_stardocs doesn't like @rules_python_gazelle_plugin//modules_mapping:def_bzl with:

Error in _stardoc_input_helper:
illegal rule name:
_bzl_api_docs_@rules_python_gazelle_plugin//modules_mapping/def_bzl.primary_bzl_src:
invalid target name '_bzl_api_docs_@rules_python_gazelle_plugin//modules_mapping/def_bzl.primary_bzl_src':
target names may not contain '//' path separators

So I tried the alias thing and it worked 🤷. Having an alias for every bzl_library target is not feasible of course. Maybe a filegroup or a meta-target bzl_library(srcs = ["$ALL_BZL_LIBRARY_TARGETS"])...

With the alias, we are able to link with {bzl:obj}. It goes to: http://localhost:8000/api/rules_python_gazelle_plugin%2B/modules_mapping/def.html#modules_mapping where %2B is +:

rules_python_gazelle_plugin+/modules_mapping/def.html

@aignasaignasAug 5, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think some of the automatic inference withing sphinxdocs needs to be updated, but I am not sure where, I'd need to dig, maybe @rickeylev knows of his hat.

@rickeylevrickeylevAug 16, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error is due to a macro generating a target with the raw label value; it does this to create some helper targets to extract some info.

sphinxdocs/private/sphinx_stardoc.bzl, function _name_to_label -- just needs to also replace @, too.

"//python:defs_bzl",
"//python:features_bzl",
"//python:packaging_bzl",
Expand Down
4 changes: 2 additions & 2 deletions gazelle/docs/installation_and_usage.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -61,8 +61,8 @@ bazel_dep(name = "rules_python_gazelle_plugin", version = "1.5.1")

Next, we'll fetch metadata about your Python dependencies, so that gazelle can
determine which package a given import statement comes from. This is provided
by the `modules_mapping` rule. We'll make a target for consuming this
`modules_mapping`, and writing it as a manifest file for Gazelle to read.
by the {bzl:obj}`modules_mapping` rule. We'll make a target for consuming this
{bzl:obj}`modules_mapping`, and writing it as a manifest file for Gazelle to read.
This is checked into the repo for speed, as it takes some time to calculate
in a large monorepo.

Expand Down
7 changes: 7 additions & 0 deletions gazelle/modules_mapping/BUILD.bazel
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
load("@bazel_skylib//rules:copy_file.bzl", "copy_file")
load("@rules_python//python:defs.bzl", "py_binary", "py_test")

Expand DownExpand Up@@ -38,3 +39,9 @@ filegroup(
srcs = glob(["**"]),
visibility = ["//:__pkg__"],
)

bzl_library(
name = "def_bzl",
srcs = ["def.bzl"],
visibility = ["//visibility:public"],
)