docs: fix api docs and publish flow

- fix: api doc via aliases
- fix: various broken links
- fix: various unclear mandatory fields

docs/api/legacy.md

@@ -7,36 +7,66 @@ Rules for building native binaries using the GraalVM `native-image` tool on Baze
 ## graal_binary
 
 <pre>
-graal_binary(<a href="#graal_binary-name">name</a>, <a href="#graal_binary-kwargs">kwargs</a>)
+graal_binary(<a href="#graal_binary-name">name</a>, <a href="#graal_binary-deps">deps</a>, <a href="#graal_binary-main_class">main_class</a>, <a href="#graal_binary-include_resources">include_resources</a>, <a href="#graal_binary-reflection_configuration">reflection_configuration</a>, <a href="#graal_binary-jni_configuration">jni_configuration</a>,
+             <a href="#graal_binary-initialize_at_build_time">initialize_at_build_time</a>, <a href="#graal_binary-initialize_at_run_time">initialize_at_run_time</a>, <a href="#graal_binary-native_features">native_features</a>, <a href="#graal_binary-data">data</a>, <a href="#graal_binary-extra_args">extra_args</a>,
+             <a href="#graal_binary-check_toolchains">check_toolchains</a>, <a href="#graal_binary-c_compiler_option">c_compiler_option</a>, <a href="#graal_binary-default_executable_name">default_executable_name</a>, <a href="#graal_binary-kwargs">kwargs</a>)
 </pre>
 
-Macros which creates a native image via the legacy rules.
+Alias for the renamed `native_image` rule. Identical.
 
 **PARAMETERS**
 
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="graal_binary-name"></a>name |  <p align="center"> - </p>   |  none |
-| <a id="graal_binary-kwargs"></a>kwargs |  <p align="center"> - </p>   |  none |
+| <a id="graal_binary-name"></a>name |  Name of the target; required.   |  none |
+| <a id="graal_binary-deps"></a>deps |  Dependency `java_library` targets to assemble the classpath from. Mandatory.   |  none |
+| <a id="graal_binary-main_class"></a>main_class |  Entrypoint main class to build from; mandatory.   |  none |
+| <a id="graal_binary-include_resources"></a>include_resources |  Glob to pass to `IncludeResources`. No default; optional.   |  `None` |
+| <a id="graal_binary-reflection_configuration"></a>reflection_configuration |  Reflection configuration file. No default; optional.   |  `None` |
+| <a id="graal_binary-jni_configuration"></a>jni_configuration |  JNI configuration file. No default; optional.   |  `None` |
+| <a id="graal_binary-initialize_at_build_time"></a>initialize_at_build_time |  Classes or patterns to pass to `--initialize-at-build-time`. No default; optional.   |  `[]` |
+| <a id="graal_binary-initialize_at_run_time"></a>initialize_at_run_time |  Classes or patterns to pass to `--initialize-at-run-time`. No default; optional.   |  `[]` |
+| <a id="graal_binary-native_features"></a>native_features |  GraalVM `Feature` classes to include and apply. No default; optional.   |  `[]` |
+| <a id="graal_binary-data"></a>data |  Data files to make available during the compilation. No default; optional.   |  `[]` |
+| <a id="graal_binary-extra_args"></a>extra_args |  Extra `native-image` args to pass. Last wins. No default; optional.   |  `[]` |
+| <a id="graal_binary-check_toolchains"></a>check_toolchains |  Whether to perform toolchain checks in `native-image`; defaults to `True` on Windows, `False` otherwise.   |  `select({"@bazel_tools//src/conditions:windows": True, "//conditions:default": False})` |
+| <a id="graal_binary-c_compiler_option"></a>c_compiler_option |  Extra C compiler options to pass through `native-image`. No default; optional.   |  `[]` |
+| <a id="graal_binary-default_executable_name"></a>default_executable_name |  Set the name of the output binary; defaults to `%target%-bin`, or `%target%-bin.exe` on Windows. The special string `%target%`, if present, is replaced with `name`.   |  `select({"@bazel_tools//src/conditions:windows": "%target%-bin.exe", "//conditions:default": "%target%-bin"})` |
+| <a id="graal_binary-kwargs"></a>kwargs |  Extra keyword arguments are passed to the underlying `native_image` rule.   |  none |
 
 
 <a id="native_image"></a>
 
 ## native_image
 
 <pre>
-native_image(<a href="#native_image-name">name</a>, <a href="#native_image-kwargs">kwargs</a>)
+native_image(<a href="#native_image-name">name</a>, <a href="#native_image-deps">deps</a>, <a href="#native_image-main_class">main_class</a>, <a href="#native_image-include_resources">include_resources</a>, <a href="#native_image-reflection_configuration">reflection_configuration</a>, <a href="#native_image-jni_configuration">jni_configuration</a>,
+             <a href="#native_image-initialize_at_build_time">initialize_at_build_time</a>, <a href="#native_image-initialize_at_run_time">initialize_at_run_time</a>, <a href="#native_image-native_features">native_features</a>, <a href="#native_image-data">data</a>, <a href="#native_image-extra_args">extra_args</a>,
+             <a href="#native_image-check_toolchains">check_toolchains</a>, <a href="#native_image-c_compiler_option">c_compiler_option</a>, <a href="#native_image-default_executable_name">default_executable_name</a>, <a href="#native_image-kwargs">kwargs</a>)
 </pre>
 
-Macros which creates a native image via the legacy rules.
+Generates and compiles a GraalVM native image from a Java library target.
 
 **PARAMETERS**
 
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="native_image-name"></a>name |  <p align="center"> - </p>   |  none |
-| <a id="native_image-kwargs"></a>kwargs |  <p align="center"> - </p>   |  none |
+| <a id="native_image-name"></a>name |  Name of the target; required.   |  none |
+| <a id="native_image-deps"></a>deps |  Dependency `java_library` targets to assemble the classpath from. Mandatory.   |  none |
+| <a id="native_image-main_class"></a>main_class |  Entrypoint main class to build from; mandatory.   |  none |
+| <a id="native_image-include_resources"></a>include_resources |  Glob to pass to `IncludeResources`. No default; optional.   |  `None` |
+| <a id="native_image-reflection_configuration"></a>reflection_configuration |  Reflection configuration file. No default; optional.   |  `None` |
+| <a id="native_image-jni_configuration"></a>jni_configuration |  JNI configuration file. No default; optional.   |  `None` |
+| <a id="native_image-initialize_at_build_time"></a>initialize_at_build_time |  Classes or patterns to pass to `--initialize-at-build-time`. No default; optional.   |  `[]` |
+| <a id="native_image-initialize_at_run_time"></a>initialize_at_run_time |  Classes or patterns to pass to `--initialize-at-run-time`. No default; optional.   |  `[]` |
+| <a id="native_image-native_features"></a>native_features |  GraalVM `Feature` classes to include and apply. No default; optional.   |  `[]` |
+| <a id="native_image-data"></a>data |  Data files to make available during the compilation. No default; optional.   |  `[]` |
+| <a id="native_image-extra_args"></a>extra_args |  Extra `native-image` args to pass. Last wins. No default; optional.   |  `[]` |
+| <a id="native_image-check_toolchains"></a>check_toolchains |  Whether to perform toolchain checks in `native-image`; defaults to `True` on Windows, `False` otherwise.   |  `select({"@bazel_tools//src/conditions:windows": True, "//conditions:default": False})` |
+| <a id="native_image-c_compiler_option"></a>c_compiler_option |  Extra C compiler options to pass through `native-image`. No default; optional.   |  `[]` |
+| <a id="native_image-default_executable_name"></a>default_executable_name |  Set the name of the output binary; defaults to `%target%-bin`, or `%target%-bin.exe` on Windows. The special string `%target%`, if present, is replaced with `name`.   |  `select({"@bazel_tools//src/conditions:windows": "%target%-bin.exe", "//conditions:default": "%target%-bin"})` |
+| <a id="native_image-kwargs"></a>kwargs |  Extra keyword arguments are passed to the underlying `native_image` rule.   |  none |
 
 

docs/api/repositories.md

@@ -7,7 +7,7 @@ Repository rule definitions, intended for use by rule users.
 ## graalvm_repository
 
 <pre>
-graalvm_repository(<a href="#graalvm_repository-name">name</a>, <a href="#graalvm_repository-java_version">java_version</a>, <a href="#graalvm_repository-version">version</a>, <a href="#graalvm_repository-distribution">distribution</a>, <a href="#graalvm_repository-toolchain">toolchain</a>, <a href="#graalvm_repository-toolchain_prefix">toolchain_prefix</a>,
+graalvm_repository(<a href="#graalvm_repository-version">version</a>, <a href="#graalvm_repository-java_version">java_version</a>, <a href="#graalvm_repository-name">name</a>, <a href="#graalvm_repository-distribution">distribution</a>, <a href="#graalvm_repository-toolchain">toolchain</a>, <a href="#graalvm_repository-toolchain_prefix">toolchain_prefix</a>,
                    <a href="#graalvm_repository-target_compatible_with">target_compatible_with</a>, <a href="#graalvm_repository-components">components</a>, <a href="#graalvm_repository-setup_actions">setup_actions</a>, <a href="#graalvm_repository-register_all">register_all</a>, <a href="#graalvm_repository-kwargs">kwargs</a>)
 </pre>
 
@@ -32,9 +32,9 @@ In this case, the `rules_graalvm` package does not provide an SHA256 hash otherw
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="graalvm_repository-name"></a>name |  Name of the VM repository.   |  none |
+| <a id="graalvm_repository-version"></a>version |  Version of the GraalVM release.   |  none |
 | <a id="graalvm_repository-java_version"></a>java_version |  Java version to use/declare.   |  none |
-| <a id="graalvm_repository-version"></a>version |  Version of the GraalVM release.   |  `"latest"` |
+| <a id="graalvm_repository-name"></a>name |  Name of the VM repository. Defaults to `graalvm`.   |  `"graalvm"` |
 | <a id="graalvm_repository-distribution"></a>distribution |  Which GVM distribution to download - `ce`, `community`, or `oracle`.   |  `None` |
 | <a id="graalvm_repository-toolchain"></a>toolchain |  Whether to create a Java toolchain from this GVM installation.   |  `True` |
 | <a id="graalvm_repository-toolchain_prefix"></a>toolchain_prefix |  Name prefix to use for the toolchain; defaults to `graalvm`.   |  `"graalvm"` |

docs/api/toolchain.md

@@ -7,18 +7,26 @@ Toolchain types and rules for GraalVM.
 ## register_graalvm_toolchains
 
 <pre>
-register_graalvm_toolchains(<a href="#register_graalvm_toolchains-repository">repository</a>, <a href="#register_graalvm_toolchains-register_java_toolchain">register_java_toolchain</a>, <a href="#register_graalvm_toolchains-register_gvm_toolchain">register_gvm_toolchain</a>)
+register_graalvm_toolchains(<a href="#register_graalvm_toolchains-name">name</a>, <a href="#register_graalvm_toolchains-register_java_toolchain">register_java_toolchain</a>, <a href="#register_graalvm_toolchains-register_gvm_toolchain">register_gvm_toolchain</a>)
 </pre>
 
-Register GraalVM toolchains for Native Image and installed language components.
+Register Bazel toolchains via the installed GraalVM repository.
+
+The default repository `name` is `@graalvm`, but this should be set to whatever the target repository
+is named (in the call to `graalvm_repository` or `graal_bindist_repository`).
+
+The GraalVM toolchain registers a custom Bazel toolchain which allows resolution of tools like
+`native-image`. If you opt out of installing the GraalVM toolchain, make sure you properly declare the
+target tool in your `native_image` binary targets.
+
 
 **PARAMETERS**
 
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="register_graalvm_toolchains-repository"></a>repository |  <p align="center"> - </p>   |  `"@graalvm"` |
-| <a id="register_graalvm_toolchains-register_java_toolchain"></a>register_java_toolchain |  <p align="center"> - </p>   |  `True` |
-| <a id="register_graalvm_toolchains-register_gvm_toolchain"></a>register_gvm_toolchain |  <p align="center"> - </p>   |  `True` |
+| <a id="register_graalvm_toolchains-name"></a>name |  Name of the target repository; defaults to `@graalvm`.   |  `"@graalvm"` |
+| <a id="register_graalvm_toolchains-register_java_toolchain"></a>register_java_toolchain |  Whether to register GraalVM as a Java toolchain. Defaults to `True`.   |  `True` |
+| <a id="register_graalvm_toolchains-register_gvm_toolchain"></a>register_gvm_toolchain |  Whether to register a GraalVM-typed toolchain. Defaults to `True`.   |  `True` |
 
 

docs/api/workspace.md

@@ -7,19 +7,27 @@ Bazel Workspace (non-Bzlmod) definitions.
 ## register_graalvm_toolchains
 
 <pre>
-register_graalvm_toolchains(<a href="#register_graalvm_toolchains-repository">repository</a>, <a href="#register_graalvm_toolchains-register_java_toolchain">register_java_toolchain</a>, <a href="#register_graalvm_toolchains-register_gvm_toolchain">register_gvm_toolchain</a>)
+register_graalvm_toolchains(<a href="#register_graalvm_toolchains-name">name</a>, <a href="#register_graalvm_toolchains-register_java_toolchain">register_java_toolchain</a>, <a href="#register_graalvm_toolchains-register_gvm_toolchain">register_gvm_toolchain</a>)
 </pre>
 
-Register GraalVM toolchains for Native Image and installed language components.
+Register Bazel toolchains via the installed GraalVM repository.
+
+The default repository `name` is `@graalvm`, but this should be set to whatever the target repository
+is named (in the call to `graalvm_repository` or `graal_bindist_repository`).
+
+The GraalVM toolchain registers a custom Bazel toolchain which allows resolution of tools like
+`native-image`. If you opt out of installing the GraalVM toolchain, make sure you properly declare the
+target tool in your `native_image` binary targets.
+
 
 **PARAMETERS**
 
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="register_graalvm_toolchains-repository"></a>repository |  <p align="center"> - </p>   |  `"@graalvm"` |
-| <a id="register_graalvm_toolchains-register_java_toolchain"></a>register_java_toolchain |  <p align="center"> - </p>   |  `True` |
-| <a id="register_graalvm_toolchains-register_gvm_toolchain"></a>register_gvm_toolchain |  <p align="center"> - </p>   |  `True` |
+| <a id="register_graalvm_toolchains-name"></a>name |  Name of the target repository; defaults to `@graalvm`.   |  `"@graalvm"` |
+| <a id="register_graalvm_toolchains-register_java_toolchain"></a>register_java_toolchain |  Whether to register GraalVM as a Java toolchain. Defaults to `True`.   |  `True` |
+| <a id="register_graalvm_toolchains-register_gvm_toolchain"></a>register_gvm_toolchain |  Whether to register a GraalVM-typed toolchain. Defaults to `True`.   |  `True` |
 
 
 <a id="rules_graalvm_repositories"></a>
@@ -30,7 +38,7 @@ Register GraalVM toolchains for Native Image and installed language components.
 rules_graalvm_repositories(<a href="#rules_graalvm_repositories-omit_rules_java">omit_rules_java</a>, <a href="#rules_graalvm_repositories-omit_bazel_skylib">omit_bazel_skylib</a>)
 </pre>
 
-Defines dependencies for the GraalVM Rules for Bazel.
+Register dependency repositories for the GraalVM Rules for Bazel.
 
 This function only needs to be called if consuming the GraalVM Rules from a non-Bzlmod environment.
 The only dependencies the rules have are: (1) `rules_java`, and (2) `bazel_skylib`. Either or both