refactor: simplify greatly by removing stardoc API docs are now rendered on an external pipeline
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 6cde22d..d1caf57 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml
@@ -20,7 +20,6 @@ uses: bazel-contrib/.github/.github/workflows/bazel.yaml@v6 with: folders: '[".", "e2e/headers", "e2e/smoke", "e2e/nodejs_host", "e2e/conflicting_toolchains"]' - # stardoc generated docs fail on diff_test with Bazel 6.4.0 so don't test against it in root repository exclude: | [ {"bazelversion": "6.4.0", "os": "macos-latest"},
diff --git a/.github/workflows/update-nodejs-versions.yml b/.github/workflows/update-nodejs-versions.yml index c4d4dc8..29492c6 100644 --- a/.github/workflows/update-nodejs-versions.yml +++ b/.github/workflows/update-nodejs-versions.yml
@@ -28,11 +28,7 @@ with: node-version: "14.x" - uses: pnpm/action-setup@v4 - - name: Run update-nodejs-versions - run: | - npm run update-nodejs-versions - bazel run docs:update - + - run: npm run update-nodejs-versions - name: Create Pull Request uses: peter-evans/create-pull-request@v3 with:
diff --git a/.prettierignore b/.prettierignore index 26a5be2..bd5535a 100644 --- a/.prettierignore +++ b/.prettierignore
@@ -1,2 +1 @@ -docs/*.md pnpm-lock.yaml
diff --git a/MODULE.bazel b/MODULE.bazel index 6804923..acaa2ef 100644 --- a/MODULE.bazel +++ b/MODULE.bazel
@@ -49,3 +49,5 @@ register_toolchains("@nodejs_toolchains//:windows_amd64_toolchain_target") register_toolchains("@nodejs_toolchains//:windows_amd64_toolchain") + +bazel_dep(name = "aspect_bazel_lib", version = "2.19.3", dev_dependency = True)
diff --git a/README.md b/README.md index bbe4587..9fa13a9 100644 --- a/README.md +++ b/README.md
@@ -19,5 +19,5 @@ ## Documentation -Comprehensive documentation for installing and using the rules, including generated API docs: +Comprehensive documentation for installing and using the rules: https://bazel-contrib.github.io/rules_nodejs/
diff --git a/WORKSPACE b/WORKSPACE index 13728f4..43c6327 100644 --- a/WORKSPACE +++ b/WORKSPACE
@@ -73,27 +73,6 @@ bazel_skylib_workspace() -# Stardoc -load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") - -stardoc_repositories() - -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() - # Buildifier load("@buildifier_prebuilt//:deps.bzl", "buildifier_prebuilt_deps")
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel deleted file mode 100644 index bb6f2b6..0000000 --- a/docs/BUILD.bazel +++ /dev/null
@@ -1,63 +0,0 @@ -# Copyright 2017 The Bazel Authors. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -load("@bazel_skylib//rules:diff_test.bzl", "diff_test") -load("@bazel_skylib//rules:write_file.bzl", "write_file") -load("//tools/stardoc:index.bzl", "stardoc") - -stardoc( - name = "core", - bzl_library_target = "//nodejs:index.for_docs", -) - -_READMES = { - "Core": "//docs:core-docgen.md", -} - -[ - diff_test( - name = "check_" + k.lower(), - failure_message = "Please run: bazel run //docs:update", - file1 = k + ".md", - file2 = v, - ) - for [ - k, - v, - ] in _READMES.items() -] - -write_file( - name = "gen_update", - out = "update.sh", - content = [ - "#!/usr/bin/env bash", - "cd $BUILD_WORKSPACE_DIRECTORY", - ] + [ - "cp -fv bazel-bin/{1} docs/{0}.md".format( - k, - v.replace(":", "/"), - ) - for [ - k, - v, - ] in _READMES.items() - ], -) - -sh_binary( - name = "update", - srcs = ["update.sh"], - data = _READMES.values(), -)
diff --git a/docs/Core.md b/docs/Core.md deleted file mode 100644 index a998810..0000000 --- a/docs/Core.md +++ /dev/null
@@ -1,270 +0,0 @@ -<!-- ********************* - DO NOT EDIT THIS FILE - It is a generated build output from Stardoc. - Instead you must edit the .bzl file where the rules are declared, - or possibly a markdown file next to the .bzl file - ********************* --> -# rules_nodejs Bazel module - -Features: -- A [Toolchain](https://docs.bazel.build/versions/main/toolchains.html) - that fetches a hermetic copy of node and npm - independent of what's on the developer's machine. -- Core [Providers](https://docs.bazel.build/versions/main/skylark/rules.html#providers) to allow interop between JS rules. - -## UserBuildSettingInfo - -**USAGE** - -<pre> -UserBuildSettingInfo(<a href="#UserBuildSettingInfo-value">value</a>) -</pre> - - - -**FIELDS** - -<h4 id="UserBuildSettingInfo-value">value</h4> - - - - - -## nodejs_repositories - -**USAGE** - -<pre> -nodejs_repositories(<a href="#nodejs_repositories-name">name</a>, <a href="#nodejs_repositories-node_download_auth">node_download_auth</a>, <a href="#nodejs_repositories-node_repositories">node_repositories</a>, <a href="#nodejs_repositories-node_urls">node_urls</a>, <a href="#nodejs_repositories-node_version">node_version</a>, - <a href="#nodejs_repositories-node_version_from_nvmrc">node_version_from_nvmrc</a>, <a href="#nodejs_repositories-include_headers">include_headers</a>, <a href="#nodejs_repositories-kwargs">kwargs</a>) -</pre> - -To be run in user's WORKSPACE to install rules_nodejs dependencies. - -This rule sets up node, npm, and npx. The versions of these tools can be specified in one of three ways - -### Simplest Usage - -Specify no explicit versions. This will download and use the latest Node.js that was available when the -version of rules_nodejs you're using was released. - -### Forced version(s) - -You can select the version of Node.js to download & use by specifying it when you call node_repositories, -using a value that matches a known version (see the default values) - -### Using a custom version - -You can pass in a custom list of Node.js repositories and URLs for node_repositories to use. - -#### Custom Node.js versions - -To specify custom Node.js versions, use the `node_repositories` attribute - -```python -nodejs_repositories( - node_repositories = { - "10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e"), - "10.10.0-linux_amd64": ("node-v10.10.0-linux-x64.tar.xz", "node-v10.10.0-linux-x64", "686d2c7b7698097e67bcd68edc3d6b5d28d81f62436c7cf9e7779d134ec262a9"), - "10.10.0-windows_amd64": ("node-v10.10.0-win-x64.zip", "node-v10.10.0-win-x64", "70c46e6451798be9d052b700ce5dadccb75cf917f6bf0d6ed54344c856830cfb"), - }, -) -``` - -These can be mapped to a custom download URL, using `node_urls` - -```python -nodejs_repositories( - node_version = "10.10.0", - node_repositories = {"10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e")}, - node_urls = ["https://mycorpproxy/mirror/node/v{version}/{filename}"], -) -``` - -A Mac client will try to download node from `https://mycorpproxy/mirror/node/v10.10.0/node-v10.10.0-darwin-x64.tar.gz` -and expect that file to have sha256sum `00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e` - -See the [the repositories documentation](repositories.html) for how to use the resulting repositories. - -### Using a custom node.js. - -To avoid downloads, you can check in a vendored node.js binary or can build one from source. -See [toolchains](./toolchains.md). - - -**PARAMETERS** - - -<h4 id="nodejs_repositories-name">name</h4> - -Unique name for the repository rule - - - -<h4 id="nodejs_repositories-node_download_auth">node_download_auth</h4> - -Auth to use for all url requests. - -Example: { "type": "basic", "login": "<UserName>", "password": "<Password>" } - -Defaults to `{}` - -<h4 id="nodejs_repositories-node_repositories">node_repositories</h4> - -Custom list of node repositories to use - -A dictionary mapping Node.js versions to sets of hosts and their corresponding (filename, strip_prefix, sha256) tuples. -You should list a node binary for every platform users have, likely Mac, Windows, and Linux. - -By default, if this attribute has no items, we'll use a list of all public Node.js releases. - -Defaults to `{}` - -<h4 id="nodejs_repositories-node_urls">node_urls</h4> - -List of URLs to use to download Node.js. - -Each entry is a template for downloading a node distribution. - -The `{version}` parameter is substituted with the `node_version` attribute, -and `{filename}` with the matching entry from the `node_repositories` attribute. - -Defaults to `["https://nodejs.org/dist/v{version}/{filename}"]` - -<h4 id="nodejs_repositories-node_version">node_version</h4> - -The specific version of Node.js to install - -Defaults to `"20.19.2"` - -<h4 id="nodejs_repositories-node_version_from_nvmrc">node_version_from_nvmrc</h4> - -The .nvmrc file containing the version of Node.js to use. - -If set then the version found in the .nvmrc file is used instead of the one specified by node_version. - -Defaults to `None` - -<h4 id="nodejs_repositories-include_headers">include_headers</h4> - -Set headers field in NodeInfo provided by this toolchain. - -This setting creates a dependency on a c++ toolchain. - -Defaults to `False` - -<h4 id="nodejs_repositories-kwargs">kwargs</h4> - -Additional parameters - - - - -## nodejs_toolchain - -**USAGE** - -<pre> -nodejs_toolchain(<a href="#nodejs_toolchain-name">name</a>, <a href="#nodejs_toolchain-node">node</a>, <a href="#nodejs_toolchain-node_path">node_path</a>, <a href="#nodejs_toolchain-npm">npm</a>, <a href="#nodejs_toolchain-npm_path">npm_path</a>, <a href="#nodejs_toolchain-npm_srcs">npm_srcs</a>, <a href="#nodejs_toolchain-headers">headers</a>, <a href="#nodejs_toolchain-kwargs">kwargs</a>) -</pre> - -Defines a node toolchain for a platform. - -You can use this to refer to a vendored nodejs binary in your repository, -or even to compile nodejs from sources using rules_foreign_cc or other rules. - -First, in a BUILD.bazel file, create a nodejs_toolchain definition: - -```starlark -load("@rules_nodejs//nodejs:toolchain.bzl", "nodejs_toolchain") - -nodejs_toolchain( - name = "toolchain", - node = "//some/path/bin/node", -) -``` - -Next, declare which execution platforms or target platforms the toolchain should be selected for -based on constraints. - -```starlark -toolchain( - name = "my_nodejs", - exec_compatible_with = [ - "@platforms//os:linux", - "@platforms//cpu:x86_64", - ], - toolchain = ":toolchain", - toolchain_type = "@rules_nodejs//nodejs:toolchain_type", -) -``` - -See https://bazel.build/extending/toolchains#toolchain-resolution for more information on toolchain -resolution. - -Finally in your `WORKSPACE`, register it with `register_toolchains("//:my_nodejs")` - -For usage see https://docs.bazel.build/versions/main/toolchains.html#defining-toolchains. -You can use the `--toolchain_resolution_debug` flag to `bazel` to help diagnose which toolchain is selected. - - -**PARAMETERS** - - -<h4 id="nodejs_toolchain-name">name</h4> - -Unique name for this target - - - -<h4 id="nodejs_toolchain-node">node</h4> - -Node.js executable - -Defaults to `None` - -<h4 id="nodejs_toolchain-node_path">node_path</h4> - -Path to Node.js executable file - -This is typically an absolute path to a non-hermetic Node.js executable. - -Only one of `node` and `node_path` may be set. - -Defaults to `""` - -<h4 id="nodejs_toolchain-npm">npm</h4> - -Npm JavaScript entry point - -Defaults to `None` - -<h4 id="nodejs_toolchain-npm_path">npm_path</h4> - -Path to npm JavaScript entry point. - -This is typically an absolute path to a non-hermetic npm installation. - -Only one of `npm` and `npm_path` may be set. - -Defaults to `""` - -<h4 id="nodejs_toolchain-npm_srcs">npm_srcs</h4> - -Additional source files required to run npm. - -Not necessary if specifying `npm_path` to a non-hermetic npm installation. - -Defaults to `[]` - -<h4 id="nodejs_toolchain-headers">headers</h4> - -cc_library that contains the Node/v8 header files - -Defaults to `None` - -<h4 id="nodejs_toolchain-kwargs">kwargs</h4> - -Additional parameters - - - -
diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 8c01742..0000000 --- a/docs/README.md +++ /dev/null
@@ -1,14 +0,0 @@ -# Authoring the docsite - -The docsite is a mix of stardoc generated markdown and hand written markdown. -The files marked with -``` -<!-- ********************* - DO NOT EDIT THIS FILE - It is a generated build output from Stardoc. - Instead you must edit the .bzl file where the rules are declared, - or possibly a markdown file next to the .bzl file - ********************* --> - ``` - -Should be edited by modifying the docs in the source `.bzl` files.
diff --git a/docs/index.md b/docs/index.md index f93d9cc..0fe15fc 100644 --- a/docs/index.md +++ b/docs/index.md
@@ -8,10 +8,7 @@ The `@rules_nodejs` Bazel module contains a toolchain that fetches a hermetic node and npm (independent of what's on the developer's machine). It is currently useful for Bazel Rules developers who want to make their own JavaScript support, and -is maintained by community volunteers from [Aspect](https://aspect.dev). - - [Install and setup](install.md) - - [Rules API](Core.md) - - [Toolchains](Toolchains.md) +is maintained by community volunteers from [Aspect](https://aspect.dev). - [Install and setup](install.md) - [Toolchains](Toolchains.md) ## Deprecated modules @@ -36,4 +33,3 @@ The JS ecosystem is also full of false equivalence arguments. The first question we often get is "What's better, Webpack or Bazel?". This is understandable, since most JS tooling is forced to provide a single turn-key experience with an isolated ecosystem of plugins, and humans love a head-to-head competition. Instead Bazel just orchestrates calling these tools. -
diff --git a/docs/install.md b/docs/install.md index 6491313..8746c8e 100644 --- a/docs/install.md +++ b/docs/install.md
@@ -45,4 +45,3 @@ You can use your own Node.js binary rather than fetching from the internet. You could check in a binary file, or build Node.js from sources. -To use See [`nodejs_toolchain`](./Core.md#nodejs_toolchain) for docs.
diff --git a/nodejs/BUILD.bazel b/nodejs/BUILD.bazel index ae325b7..5278f96 100644 --- a/nodejs/BUILD.bazel +++ b/nodejs/BUILD.bazel
@@ -11,8 +11,11 @@ bzl_library( name = "index.for_docs", - srcs = glob(["*.bzl"]) + ["@bazel_tools//tools:bzl_srcs"], + srcs = glob(["*.bzl"]), deps = [ + "//nodejs:providers.bzl", + "//nodejs:repositories.bzl", + "//nodejs:toolchain.bzl", "//nodejs/private:bzl", "//nodejs/private/providers:bzl", "@bazel_skylib//lib:paths",
diff --git a/repositories.bzl b/repositories.bzl index 1afb558..5b75069 100644 --- a/repositories.bzl +++ b/repositories.bzl
@@ -38,12 +38,6 @@ ) http_archive( - name = "io_bazel_stardoc", - sha256 = "fabb280f6c92a3b55eed89a918ca91e39fb733373c81e87a18ae9e33e75023ec", - urls = ["https://github.com/bazelbuild/stardoc/releases/download/0.7.1/stardoc-0.7.1.tar.gz"], - ) - - http_archive( name = "aspect_bazel_lib", sha256 = "db7da732db4dece80cd6d368220930950c9306ff356ebba46498fe64e65a3945", strip_prefix = "bazel-lib-2.19.3",
diff --git a/tools/stardoc/BUILD.bazel b/tools/stardoc/BUILD.bazel deleted file mode 100644 index 801dc3c..0000000 --- a/tools/stardoc/BUILD.bazel +++ /dev/null
@@ -1 +0,0 @@ -exports_files(glob(["templates/*.vm"]))
diff --git a/tools/stardoc/index.bzl b/tools/stardoc/index.bzl deleted file mode 100644 index 7c11e3e..0000000 --- a/tools/stardoc/index.bzl +++ /dev/null
@@ -1,16 +0,0 @@ -"Wrap stardoc to set our repo-wide defaults" - -load("@aspect_bazel_lib//lib:docs.bzl", _stardoc = "stardoc_with_diff_test") - -_PKG = "@rules_nodejs//tools/stardoc" - -def stardoc(name, **kwargs): - _stardoc( - name = name, - aspect_template = _PKG + ":templates/aspect.vm", - header_template = _PKG + ":templates/header.vm", - func_template = _PKG + ":templates/func.vm", - provider_template = _PKG + ":templates/provider.vm", - rule_template = _PKG + ":templates/rule.vm", - **kwargs - )
diff --git a/tools/stardoc/templates/README.md b/tools/stardoc/templates/README.md deleted file mode 100644 index b8b2b0b..0000000 --- a/tools/stardoc/templates/README.md +++ /dev/null
@@ -1,2 +0,0 @@ -We have our own stardoc templates as a workaround for -https://github.com/bazelbuild/skydoc/issues/216
diff --git a/tools/stardoc/templates/aspect.vm b/tools/stardoc/templates/aspect.vm deleted file mode 100644 index a974801..0000000 --- a/tools/stardoc/templates/aspect.vm +++ /dev/null
@@ -1,33 +0,0 @@ -#[[##]]# ${aspectName} - -**USAGE** - -<pre> -${util.aspectSummary($aspectName, $aspectInfo)} -</pre> - -$aspectInfo.getDocString() - -**ASPECT ATTRIBUTES** - -#if (!$aspectInfo.getAttributeList().isEmpty()) -#foreach ($aspectAttribute in $aspectInfo.getAspectAttributeList()) -<h4>${aspectAttribute}</h4> -#end -#end - -**ATTRIBUTES** - -#if (!$aspectInfo.getAttributeList().isEmpty()) -#foreach ($attribute in $aspectInfo.getAttributeList()) -<h4 id="${aspectName}-${attribute.name}">${attribute.name}</h4> - -(*${util.attributeTypeString($attribute)}, {util.mandatoryString($attribute)}*) -#if(!$attribute.docString.isEmpty()) $attribute.docString.trim() #else - #end - -#if( !$attribute.defaultValue.isEmpty() ) -Defaults to `$attribute.defaultValue` -#end - -#end -#end
diff --git a/tools/stardoc/templates/func.vm b/tools/stardoc/templates/func.vm deleted file mode 100644 index 74ee239..0000000 --- a/tools/stardoc/templates/func.vm +++ /dev/null
@@ -1,26 +0,0 @@ -#[[##]]# ${funcInfo.functionName} - -**USAGE** - -<pre> -${util.funcSummary($funcInfo)} -</pre> - -$funcInfo.docString - -**PARAMETERS** - -#if (!$funcInfo.getParameterList().isEmpty()) -#foreach ($param in $funcInfo.getParameterList()) - -<h4 id="${funcInfo.functionName}-${param.name}">${param.name}</h4> - -#if (!$param.docString.isEmpty()) -${util.htmlEscape($param.docString.trim())} -#end - -#if( !$param.defaultValue.isEmpty() ) -Defaults to `$param.defaultValue`#end - -#end -#end
diff --git a/tools/stardoc/templates/header.vm b/tools/stardoc/templates/header.vm deleted file mode 100644 index 5eb7747..0000000 --- a/tools/stardoc/templates/header.vm +++ /dev/null
@@ -1,7 +0,0 @@ -<!-- ********************* - DO NOT EDIT THIS FILE - It is a generated build output from Stardoc. - Instead you must edit the .bzl file where the rules are declared, - or possibly a markdown file next to the .bzl file - ********************* --> -${moduleDocstring}
diff --git a/tools/stardoc/templates/provider.vm b/tools/stardoc/templates/provider.vm deleted file mode 100644 index 2c3f742..0000000 --- a/tools/stardoc/templates/provider.vm +++ /dev/null
@@ -1,20 +0,0 @@ -#[[##]]# ${providerName} - -**USAGE** - -<pre> -${util.providerSummary($providerName, $providerInfo)} -</pre> - -${providerInfo.docString} - -**FIELDS** - -#if (!$providerInfo.fieldInfoList.isEmpty()) -#foreach ($field in $providerInfo.fieldInfoList) -<h4 id="${providerName}-${field.name}">${field.name}</h4> - -#if(!$field.docString.isEmpty()) $field.docString.trim() #else - #end - -#end -#end
diff --git a/tools/stardoc/templates/rule.vm b/tools/stardoc/templates/rule.vm deleted file mode 100644 index aee2b98..0000000 --- a/tools/stardoc/templates/rule.vm +++ /dev/null
@@ -1,28 +0,0 @@ -#[[##]]# ${ruleName} - -**USAGE** - -<pre> -${util.ruleSummary($ruleName, $ruleInfo)} -</pre> - -$ruleInfo.docString - -**ATTRIBUTES** - -#if (!$ruleInfo.getAttributeList().isEmpty()) -#foreach ($attribute in $ruleInfo.getAttributeList()) - -<h4 id="${ruleName}-${attribute.name}">${attribute.name}</h4> - -(*${util.attributeTypeString($attribute)}#if( $attribute.mandatory ), mandatory#end*)#if (!$attribute.docString.isEmpty()): ${attribute.docString.trim()}#end -#if (!$attribute.getProviderNameGroupList().isEmpty()) - The dependencies of this attribute must provide: ${util.attributeProviders($attribute)} -#end - -#if( !$attribute.defaultValue.isEmpty() ) - -Defaults to `$attribute.defaultValue`#end - -#end -#end