Skip to content
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

Jump to bottom

register_toolchains and other globals are documented twice #16383

Closed
jfirebaugh opened this issue Oct 4, 2022 · 2 comments
Closed

register_toolchains and other globals are documented twice #16383

jfirebaugh opened this issue Oct 4, 2022 · 2 comments
Assignees
@Wyverald
Labels
area-Bzlmod Bzlmod-specific PRs, issues, and feature requests P2 We'll consider working on this in future. (Assignee optional) team-Documentation Documentation improvements that cannot be directly linked to other team labels team-ExternalDeps External dependency handling, remote repositiories, WORKSPACE file. type: documentation (cleanup)

Comments

@jfirebaugh
Copy link

jfirebaugh commented Oct 4, 2022 •
edited
Loading

Description of the bug:

register_toolchains is documented twice with slightly different documentation text.

https://bazel.build/rules/lib/globals#register_toolchains() is the permalink to both. If you visit that link you'll see both items. One reads "Register an already-defined toolchain..." and the other "Specifies already-defined toolchains...".

register_execution_platforms() and repository_rule(implementation, attrs, local, environ, configure, remotable, doc) are also duplicated.
@ShreeM01 ShreeM01 added team-Documentation Documentation improvements that cannot be directly linked to other team labels type: bug untriaged labels Oct 4, 2022
@Wyverald Wyverald added the area-Bzlmod Bzlmod-specific PRs, issues, and feature requests label Oct 5, 2022
@Wyverald
Copy link
Member

Wyverald commented Oct 5, 2022

This is an unfortunate result of our documentation setup. One register_toolchains is for the WORKSPACE function and the other is for the MODULE.bazel function. cc @fweikert @meteorcloudy I was planning to do something about this after the branch cut.

@meteorcloudy meteorcloudy added type: documentation (cleanup) team-ExternalDeps External dependency handling, remote repositiories, WORKSPACE file. P2 We'll consider working on this in future. (Assignee optional) and removed type: bug untriaged labels Oct 28, 2022
@sgowroji
Copy link
Member

Similar issue with documentation #14879 (comment)

@Wyverald Wyverald mentioned this issue Nov 18, 2022
Closed
@Wyverald Wyverald mentioned this issue Dec 2, 2022
Closed
copybara-service bot pushed a commit that referenced this issue Apr 5, 2023
@Wyverald @copybara-github
Fix DocCategory usage
75da855 
- All @StarlarkBuiltin annotations that don't have `documented=false` should have a DocCategory set. This CL fixes offending cases, but doesn't change the annotation processor to enforce it; that can be done later.
- Fixed @StarlarkBuiltin annotations that had the wrong DocCategory.
- Removed DocCategory.NONE; it doesn't mean anything.
- Renamed DocCategory.TOP_LEVEL_TYPE to TOP_LEVEL_MODULE. This category represents stuff like `attr`, which we don't typically think of as "types" (you don't create instances of `attr` the module).

Work towards #16383

PiperOrigin-RevId: 522079755
Change-Id: I969e52939139d7e9d584060dfe0b541f1fd42b23
copybara-service bot pushed a commit that referenced this issue Apr 5, 2023
@Wyverald @copybara-github
Rename @DocumentMethods to @GlobalMethods and add "environment" infor…
d1c72d7 
…mation

- Renamed to emphasize the fact that each method in there is available as a global method (aka top-level binding).
- Added a mandatory "environment" field to let classes specify in which environment their methods are supposed to be available: BUILD files, WORKSPACE files, MODULE files, or .bzl files.
  - This information will be used in a follow-up CL.

Work towards #16383

PiperOrigin-RevId: 522080811
Change-Id: I94bb50011147cee30a141b002e968a323c40a1be
copybara-service bot pushed a commit that referenced this issue Apr 11, 2023
@Wyverald @copybara-github
Prevent repository_rule from showing up twice in documentation
b4ef50c 
- Removed @GlobalMethods from StarlarkRepositoryModule as the interface RepositoryModuleApi is already annotated with @GlobalMethods
- Moved the two methods, `moduleExtension` and `tagClass`, and their documentation, to the interface instead
- Added no-op fake implementation for the two methods in FakeRepositoryModule
- TagClass's documentation is moved to an interface RepositoryModuleApi.TagClassApi (so that we can still refer to it); ModuleExtension's documentation is removed, as that type is never meaningfully used in Starlark (only exported)

Work towards #16383

PiperOrigin-RevId: 523356118
Change-Id: Ic937be3c41bcf7d748945d7bc2d2afb124d9c4bd
fweikert pushed a commit to fweikert/bazel that referenced this issue May 25, 2023
@Wyverald @fweikert
Fix DocCategory usage
14ebb41 
- All @StarlarkBuiltin annotations that don't have `documented=false` should have a DocCategory set. This CL fixes offending cases, but doesn't change the annotation processor to enforce it; that can be done later.
- Fixed @StarlarkBuiltin annotations that had the wrong DocCategory.
- Removed DocCategory.NONE; it doesn't mean anything.
- Renamed DocCategory.TOP_LEVEL_TYPE to TOP_LEVEL_MODULE. This category represents stuff like `attr`, which we don't typically think of as "types" (you don't create instances of `attr` the module).

Work towards bazelbuild#16383

PiperOrigin-RevId: 522079755
Change-Id: I969e52939139d7e9d584060dfe0b541f1fd42b23
fweikert pushed a commit to fweikert/bazel that referenced this issue May 25, 2023
@Wyverald @fweikert
Rename @DocumentMethods to @GlobalMethods and add "environment" infor…
63d47e4 
…mation

- Renamed to emphasize the fact that each method in there is available as a global method (aka top-level binding).
- Added a mandatory "environment" field to let classes specify in which environment their methods are supposed to be available: BUILD files, WORKSPACE files, MODULE files, or .bzl files.
  - This information will be used in a follow-up CL.

Work towards bazelbuild#16383

PiperOrigin-RevId: 522080811
Change-Id: I94bb50011147cee30a141b002e968a323c40a1be
fweikert pushed a commit to fweikert/bazel that referenced this issue May 25, 2023
@Wyverald @fweikert
Prevent repository_rule from showing up twice in documentation
7dbd645 
- Removed @GlobalMethods from StarlarkRepositoryModule as the interface RepositoryModuleApi is already annotated with @GlobalMethods
- Moved the two methods, `moduleExtension` and `tagClass`, and their documentation, to the interface instead
- Added no-op fake implementation for the two methods in FakeRepositoryModule
- TagClass's documentation is moved to an interface RepositoryModuleApi.TagClassApi (so that we can still refer to it); ModuleExtension's documentation is removed, as that type is never meaningfully used in Starlark (only exported)

Work towards bazelbuild#16383

PiperOrigin-RevId: 523356118
Change-Id: Ic937be3c41bcf7d748945d7bc2d2afb124d9c4bd
fweikert pushed a commit to fweikert/bazel that referenced this issue May 25, 2023
@Wyverald @fweikert
Docgen: Split the "global functions" page into multiple ones
b77cb78 
======

- Primary motivation: bazelbuild#16383
- Currently, the pages generated by docgen is a `PageTitle -> Page` map. It's then separated into multiple categories based on the `docCategory` value of the `@StarlarkBuiltin` annotation, with the exception of the "global functions" page, which is special-cased.
  - This has several issues: for one, the configuration fragment named "proto" has a conflict with the top-level module named "proto", since everything is in the same map (we work around this by naming the latter "ProtoModule", which is wrong and confusing).
  - For another, we can't easily split the "global functions" page into multiple ones, unless we special-case every one of them.
- So we structure the returned pages into a `Category -> [Page]` map. The new category `GLOBAL_FUNCTION` contains a few pages, each of which contains global functions available in a certain environment (see bazelbuild@d1c72d7). The other categories are largely unchanged.
- We also change the URL format of these pages from `..../lib/$TITLE.html` to `..../lib/$CATEGORY/$TITLE.html`.
  - The bulk of this CL involves fixing up all links.
  - This also means that "proto" the configuration fragment and "proto" the top-level module can now both be named "proto".
  - This does break old links, but I can't find the energy to set up redirects for everything...
- Miscellaneous changes:
  - The `starlark-nav.vm` page is removed; nobody uses it.
  - Renamed the category overview pages from `..../lib/starlark-$CATEGORY.html` to just `..../lib/$CATEGORY.html`, now that there's no pages directly under `..../lib`.
  - A bunch of small documentation fixes across the codebase as I went through them.

Fixes bazelbuild#16383

PiperOrigin-RevId: 523745069
Change-Id: Idfbb29f1f589bde58ac5a8b199a788245286256a
SalmaSamy pushed a commit that referenced this issue Sep 12, 2023
@Wyverald @SalmaSamy
Prevent repository_rule from showing up twice in documentation
30c3004 
- Removed @GlobalMethods from StarlarkRepositoryModule as the interface RepositoryModuleApi is already annotated with @GlobalMethods
- Moved the two methods, `moduleExtension` and `tagClass`, and their documentation, to the interface instead
- Added no-op fake implementation for the two methods in FakeRepositoryModule
- TagClass's documentation is moved to an interface RepositoryModuleApi.TagClassApi (so that we can still refer to it); ModuleExtension's documentation is removed, as that type is never meaningfully used in Starlark (only exported)

Work towards #16383

PiperOrigin-RevId: 523356118
Change-Id: Ic937be3c41bcf7d748945d7bc2d2afb124d9c4bd

# Conflicts:
#	src/main/java/com/google/devtools/build/lib/bazel/bzlmod/BUILD
#	src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtension.java
#	src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TagClass.java
#	src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java
#	src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java
SalmaSamy pushed a commit that referenced this issue Sep 12, 2023
@Wyverald @SalmaSamy
Prevent repository_rule from showing up twice in documentation
5e1ceaf 
- Removed @GlobalMethods from StarlarkRepositoryModule as the interface RepositoryModuleApi is already annotated with @GlobalMethods
- Moved the two methods, `moduleExtension` and `tagClass`, and their documentation, to the interface instead
- Added no-op fake implementation for the two methods in FakeRepositoryModule
- TagClass's documentation is moved to an interface RepositoryModuleApi.TagClassApi (so that we can still refer to it); ModuleExtension's documentation is removed, as that type is never meaningfully used in Starlark (only exported)

Work towards #16383

PiperOrigin-RevId: 523356118
Change-Id: Ic937be3c41bcf7d748945d7bc2d2afb124d9c4bd

# Conflicts:
#	src/main/java/com/google/devtools/build/lib/bazel/bzlmod/BUILD
#	src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtension.java
#	src/main/java/com/google/devtools/build/lib/bazel/bzlmod/TagClass.java
#	src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java
#	src/main/java/com/google/devtools/build/lib/starlarkbuildapi/repository/RepositoryModuleApi.java

# Conflicts:
#	src/main/java/com/google/devtools/build/lib/bazel/bzlmod/ModuleExtension.java
#	src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Wyverald Wyverald

Labels
area-Bzlmod Bzlmod-specific PRs, issues, and feature requests P2 We'll consider working on this in future. (Assignee optional) team-Documentation Documentation improvements that cannot be directly linked to other team labels team-ExternalDeps External dependency handling, remote repositiories, WORKSPACE file. type: documentation (cleanup)
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@jfirebaugh @Wyverald @meteorcloudy @sgowroji @ShreeM01