Update stardoc for bzlmod #776

luispadron · 2023-10-16T22:50:36Z

This PR updates stardoc for use with bzlmod. This is required as the versions of stardoc on the registry require these stricter deps changes.

This updates our documentation (i.e. stardoc and bzl_library targets) to work in a similar way to rules_apple: https://github.com/bazelbuild/rules_apple/blob/master/apple/BUILD#L33

Each file we want documentation generated for defines it's own bzl_library with it's own set of deps. These target names are then used within the stardoc rule to generate documentation for each of them.

The main change is going from one giant bzl_library to multiple bzl_library.

Depends on the following stack:

luispadron · 2023-10-16T22:52:00Z

I plan to PR two things before this PR is merged but that it depends on:

Updating Bazel verison, we need >= 6.3.2 to fix issues with bzlmod and stardoc
Update to use bazel_skylib's write_file rule vs our custom copy of it, reduces code duplication and amount of bzl_library needed to create

luispadron · 2023-10-16T23:20:13Z

rules/library.bzl

 load("@bazel_skylib//lib:selects.bzl", "selects")
 load("@bazel_skylib//rules:write_file.bzl", "write_file")
-load("@build_bazel_rules_apple//apple:apple.bzl", "apple_dynamic_framework_import", "apple_static_framework_import")
+load("@build_bazel_rules_apple//apple/internal:apple_framework_import.bzl", "apple_dynamic_framework_import", "apple_static_framework_import")


Changing from apple.bzl umbrella import to specific internal import works around an issue i reported in stardoc + bzlmod: bazelbuild/stardoc#192

luispadron · 2023-10-16T23:20:51Z

rules/repositories.bzl

+    _maybe(
+        http_archive,
+        name = "io_bazel_stardoc",
+        sha256 = "62bd2e60216b7a6fec3ac79341aa201e0956477e7c8f6ccc286f279ad1d96432",
+        urls = [
+            "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.6.2/stardoc-0.6.2.tar.gz",
+            "https://github.com/bazelbuild/stardoc/releases/download/0.6.2/stardoc-0.6.2.tar.gz",
+        ],
+    )


Moved this from WORKSPACE to the dev_dependencies section so that it matches the other rules_ios deps.

luispadron · 2023-10-16T23:21:10Z

WORKSPACE

+load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
+
+rules_jvm_external_deps()
+
+load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
+
+rules_jvm_external_setup()
+
+load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps")
+
+stardoc_external_deps()
+
+load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install")
+
+stardoc_pinned_maven_install()


This is required by new stardoc versions

luispadron · 2023-10-16T23:21:20Z

WORKSPACE.bzlmod

 workspace(name = "build_bazel_rules_ios")
-
-# TODO: stardoc doesn't currently support bzlmod: https://github.com/bazelbuild/stardoc/issues/117
-# Once that closes we should depend on it via the WORKSPACE file.
-# In the meantime, this is a workaround to at least allow building.
-# Note however that updating docs with bzlmod will not work until the above is resolved.
-# Until then use: --noenable_bzlmod
-load(
-    "@bazel_tools//tools/build_defs/repo:git.bzl",
-    "git_repository",
-)
-
-git_repository(
-    name = "io_bazel_stardoc",
-    commit = "6f274e903009158504a9d9130d7f7d5f3e9421ed",
-    remote = "https://github.com/bazelbuild/stardoc.git",
-    shallow_since = "1667581897 -0400",
-)
-
-load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
-
-stardoc_repositories()


Now fully bzlmod 🎉

justinseanmartin

Take comments with a grain of salt and nothing that I'd consider a blocker to landing this.

justinseanmartin · 2023-10-17T00:19:38Z

docs/vfs_overlay.doc_doc.md

The file name here and xcconfig.doc_doc.md seem odd

Just fixed this, should be generated correctly now

justinseanmartin · 2023-10-17T00:30:47Z

rules/xcconfig.doc.bzl

@@ -0,0 +1,10 @@
+load(
+    "//rules/library:xcconfig.bzl",


Should this live under rules/library/xcconfig.doc.bzl to be next to its associated rule? I presume we don't want all of //rules/library:xcconfig.bzl to be considered public API, so we're cherry-picking a subset of it here? Should we mark the rest as internal symbols with an underscore prefix or something, if that prevents it from being documented?

Same feedback for vfs_overlay.

The use of .doc.bzl matches what rules_apple does, it's exporting the public api of xcconfig.bzl in the //rules package specifically. This makes it so we can create the stardoc target for these in one list vs. conditionalizing the path to the bzl_library

See this in docs/BUILD.bazel:

stardoc( ... input = "//rules:%s.bzl" % file, )

docs/BUILD.bazel

jerrymarino · 2023-10-18T00:10:30Z

docs/BUILD.bazel

-    "apple_patched",
    "extension",
+    "features",
+    "force_load_direct_deps",


A number of the files are internal ones we don't consider upholding an API contract for or have quality starlark doc comments about said internal components; though if other people really want to have this I'm not opposed - nor do I think it will change the lack of some API contract beyond apple_framework

Features seems useful and imo more of the public API than some of the other things we've said are.

Do you have a specific list you'd want me to remove?

thiagohmcruz

Thx so much for tackling this!

docs/BUILD.bazel

Co-authored-by: Thiago Cruz <thiago.hmcruz@gmail.com>

1. Export all files to `bzl_srcs` 2. Remove mirror of includes into `bzl_library` 3. Remove documentation of internal sources Related: #783 #776

luispadron force-pushed the luis/update-stardoc-for-bzlmod branch from 3075874 to c5eb90b Compare October 16, 2023 22:57

This was referenced Oct 16, 2023

Update from Bazel 6.1.2 to Bazel 6.3.2 #777

Merged

Move to using write_file from Bazel Skylib #778

Merged

luispadron force-pushed the luis/update-stardoc-for-bzlmod branch 2 times, most recently from 55a090a to 8c87c5d Compare October 16, 2023 23:05

luispadron changed the base branch from master to luis/use-bazel-skylib-write_file October 16, 2023 23:14

luispadron force-pushed the luis/update-stardoc-for-bzlmod branch from 8c87c5d to 52c657a Compare October 16, 2023 23:15

luispadron marked this pull request as ready for review October 16, 2023 23:15

luispadron requested review from jerrymarino, jszumski, mattrobmattrob and thiagohmcruz October 16, 2023 23:16

luispadron commented Oct 16, 2023

View reviewed changes

luispadron force-pushed the luis/update-stardoc-for-bzlmod branch from 52c657a to f18dc96 Compare October 17, 2023 00:18

luispadron mentioned this pull request Oct 17, 2023

Feature request: Add support for Bzlmod #704

Closed

luispadron force-pushed the luis/update-stardoc-for-bzlmod branch from f18dc96 to 890aa9a Compare October 17, 2023 00:24

justinseanmartin approved these changes Oct 17, 2023

View reviewed changes

luispadron force-pushed the luis/update-stardoc-for-bzlmod branch 2 times, most recently from 61e7273 to 34ac987 Compare October 17, 2023 00:50

Base automatically changed from luis/use-bazel-skylib-write_file to master October 17, 2023 14:05

luispadron force-pushed the luis/update-stardoc-for-bzlmod branch from 34ac987 to 412a316 Compare October 17, 2023 14:45

luispadron mentioned this pull request Oct 17, 2023

Add Bazel central registry files #780

Merged

jerrymarino reviewed Oct 18, 2023

View reviewed changes

luispadron added 3 commits October 18, 2023 10:39

Update nonbzlmod WORKSPACE for stardoc 0.6.2

8a597ee

Use stardoc from bzlmod registry

6e8748f

Update doc targets to work with latest version of stardoc

4fdb438

luispadron force-pushed the luis/update-stardoc-for-bzlmod branch from 412a316 to 4fdb438 Compare October 18, 2023 14:41

luispadron requested a review from jerrymarino October 18, 2023 14:41

thiagohmcruz approved these changes Oct 18, 2023

View reviewed changes

docs/BUILD.bazel Outdated Show resolved Hide resolved

Update docs/BUILD.bazel

aca86c7

Co-authored-by: Thiago Cruz <thiago.hmcruz@gmail.com>

luispadron merged commit b7b624b into master Oct 18, 2023

luispadron deleted the luis/update-stardoc-for-bzlmod branch October 18, 2023 20:06

jerrymarino mentioned this pull request Oct 19, 2023

Update dependencies and use latest archives #784

Merged

jerrymarino mentioned this pull request Oct 19, 2023

[Stardoc] Cleanup new stardoc include issues, removing internal docs #785

Closed

Update stardoc for bzlmod #776

Update stardoc for bzlmod #776

Uh oh!

Conversation

luispadron commented Oct 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

luispadron commented Oct 16, 2023

Uh oh!

luispadron Oct 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinseanmartin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jerrymarino Oct 18, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thiagohmcruz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

luispadron commented Oct 16, 2023 •

edited

Loading

luispadron Oct 16, 2023 •

edited

Loading

jerrymarino Oct 18, 2023 •

edited

Loading