Skip to content

Add default_repo_name attribute to starlark_doc_extract#19002

Closed
fmeum wants to merge 1 commit intobazelbuild:masterfrom
fmeum:default_repo_name
Closed

Add default_repo_name attribute to starlark_doc_extract#19002
fmeum wants to merge 1 commit intobazelbuild:masterfrom
fmeum:default_repo_name

Conversation

@fmeum
Copy link
Copy Markdown
Collaborator

@fmeum fmeum commented Jul 20, 2023

The specified repository name is used to make repo-relative labels repo-absolute. This applies to default values that are labels as well as the locations of .bzl files.

@fmeum fmeum requested a review from lberki as a code owner July 20, 2023 08:50
@fmeum fmeum requested review from tetromino and removed request for lberki July 20, 2023 08:50
@github-actions github-actions bot added the awaiting-review PR is awaiting review from an assigned reviewer label Jul 20, 2023
@fmeum fmeum mentioned this pull request Jul 20, 2023
Merged
@fmeum
Add default_repo_name attribute to starlark_doc_extract
e1cec58 
The specified repository name is used to make repo-relative labels
repo-absolute. This applies to default values that are labels as well
as the locations of `.bzl` files.
@fmeum fmeum force-pushed the default_repo_name branch from a1080d0 to e1cec58 Compare July 20, 2023 09:06
tetromino
tetromino requested changes Jul 20, 2023
View reviewed changes
Copy link
Copy Markdown
Contributor

@tetromino tetromino left a comment •
edited
Loading

Choose a reason for hiding this comment

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

Thanks you very much for this PR!

But I see a problem in the test output: attribute default label values and origin key labels are rendered with different canonicalizations even though they refer to targets in the same repo. Let me see if there is a simple fix...

@tetromino tetromino self-assigned this Jul 20, 2023
@tetromino tetromino added type: bug P1 I'll work on this now. (Assignee required) team-Starlark-Integration Issues involving Bazel's integration with Starlark, excluding builtin symbols and removed awaiting-review PR is awaiting review from an assigned reviewer labels Jul 20, 2023
@fmeum
Copy link
Copy Markdown
Collaborator Author

fmeum commented Jul 20, 2023 •
edited
Loading

@tetromino Are you referring to getDisplayForm vs getShorthandDisplayForm? If so, since the origin key labels should always reference .bzl or .scl files, I wouldn't expect that difference to really matter in practice as nobody is going to name their repo defs.bzl just so that they can load from @defs.bzl instead of @defs.bzl//:defs.bzl.

@tetromino
Copy link
Copy Markdown
Contributor

tetromino commented Jul 20, 2023

@tetromino Are you referring to getDisplayForm vs getShorthandDisplayForm? If so, since the origin key labels should always reference .bzl or .scl files, I wouldn't expect that difference to really matter in practice as nobody is going to name their repo defs.bzl just so that they can load from @defs.bzl instead of @defs.bzl//:defs.bzl.

I was referring to the fact that we need the same label formatting in all contexts - not just attribute defaults but also e.g. moduleInfo.file and originKey.file

@tetromino tetromino mentioned this pull request Jul 20, 2023
Closed
@tetromino
Copy link
Copy Markdown
Contributor

tetromino commented Jul 20, 2023

After thinking for a bit and talking to @brandjon, I would prefer to fix this by a different approach in #19009:

  • I think we don't need a string for the main repo name, a boolean is sufficient: whether to render the repo name or not. Inconsistent repo name vs. module name can be handled already by repo_name parameter to module() which already propagates the right name to the repo map
  • this boolean is only relevant for the main repo because label stringification API prevents us from using a non-main repo's repo map (which means my hope of consistent doc output when building a stardoc target living in the main repo vs. a dependency had not worked in the first place; I did not realize that due to insufficient tests)
  • the only tricky part is that the main repo has lots of mapped names - "@", "__main__" etc. We need to iterate over them and pick the first one starting with an alphabetic character.

@tetromino tetromino closed this Jul 20, 2023
@fmeum fmeum deleted the default_repo_name branch July 21, 2023 12:20
copybara-service bot pushed a commit that referenced this pull request Jul 27, 2023
@tetromino @copybara-github
Add render_main_repo_name attribute to starlark_doc_extract
6f3789a 
For labels in the main repo, users may wish one of 2 behaviors:

* render labels in display form (without the repo component) - when documenting
  rules intended for other users of the same repo. (This is the expected use case
  in an organization's internal monorepo).
* render labels with the @repo component included - when documenting rules intended
  for use from other repos. (This is the expected use case for public rule sets.)

Formerly, starlark_doc_extract only supported case 1. We add support for case 2 via
the new `render_main_repo_name` attribute. Supporting it means we can't simply use
Label.getDisplayForm() any more - we need to post-process the string via a new
label renderer.

It also turned out that Label.getDisplayForm() fails an assert when using a repo
map owned by the non-main repo. This means we always have to use the main repo's
repo map for rendering, which in turn means that starlark_doc_extract's label
stringification is different depending on whether the starlark_doc_extract target
lives in the main repo or a dependency. Arguably, this is the correct thing to do:
the owner of the main repo presumably wants to generate documentation with
consistent repo names regardless of whether the target lives in the main repo or
in a dep.

Inspired by @fmeum's work in #19002

Closes #19009.

PiperOrigin-RevId: 551594134
Change-Id: Iec4b9479ca9b27babd0435883649802e5cde8aab
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tetromino tetromino tetromino requested changes

Assignees

@tetromino tetromino

Labels

P1 I'll work on this now. (Assignee required) team-Starlark-Integration Issues involving Bazel's integration with Starlark, excluding builtin symbols type: bug

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@fmeum @tetromino