Add support for backticks in default values

Temporarily uses a fork of Bazel that includes a new helper function.

WORKSPACE

@@ -14,8 +14,8 @@ load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
 # Needed for generating the Stardoc release binary.
 git_repository(
     name = "io_bazel",
-    commit = "c2394ca2d201bdc72887b3920680ca119d46a26e",  # 2023-05-10
-    remote = "https://github.com/bazelbuild/bazel.git",
+    commit = "7316ec4d1a3a90f2ae62ad552fd0fd63e195b46a",  # Temporary commit in a fork of Bazel.
+    remote = "https://github.com/fmeum/bazel.git",
 )
 
 # The following binds are needed for building protobuf java libraries.

stardoc/proto/stardoc_output.proto

@@ -23,9 +23,9 @@ package stardoc_output;
 option java_package = "com.google.devtools.build.skydoc.rendering.proto";
 option java_outer_classname = "StardocOutputProtos";
 
-// The root output proto of Stardoc. A single invocation of Stardoc will output
-// exactly one instance of this proto, representing all documentation for
-// the input Starlark file.
+// The root output proto of Stardoc. An invocation of Stardoc on a single file
+// will output exactly one instance of this proto, representing all
+// documentation for the input Starlark file.
 message ModuleInfo {
   repeated RuleInfo rule_info = 1;
 
@@ -37,6 +37,11 @@ message ModuleInfo {
 
   // The docstring present at the top of the input Starlark file.
   string module_docstring = 5;
+
+  // The display form of the label of the module file (as seen from the
+  // starlark_doc_extract or Stardoc target's repo). Unset when there is no
+  // module file (e.g. when the module is a REPL, or in Bazel's internal tests).
+  string file = 6;
 }
 
 // Representation of a Starlark rule attribute type. These generally
@@ -63,14 +68,26 @@ enum AttributeType {
 
 // Representation of a Starlark rule definition.
 message RuleInfo {
-  // The name of the rule.
+  // The name under which the rule is made accessible to a user of this module,
+  // including any structs it is nested in, for example "foo.foo_library".
   string rule_name = 1;
 
   // The documentation string of the rule.
   string doc_string = 2;
 
   // The attributes of the rule.
   repeated AttributeInfo attribute = 3;
+
+  // The module where and the name under which the rule was originally declared.
+  //
+  // Note: legacy Stardoc (0.5.x and earlier) does not set this field.
+  OriginKey origin_key = 4;
+
+  // The list of providers that the rule's implementation must return. Unset if
+  // the rule lists no advertised providers.
+  //
+  // Note: legacy Stardoc (0.5.x and earlier) does not set this field.
+  ProviderNameGroup advertised_providers = 5;
 }
 
 // Representation of a Starlark rule attribute definition, comprised of an
@@ -102,19 +119,36 @@ message AttributeInfo {
   string default_value = 6;
 }
 
-// Representation of a set of providers that a rule attribute may be required to
-// have.
+// Representation of a set of providers.
 message ProviderNameGroup {
-  // The names of the providers that must be given by any dependency appearing
-  // in this attribute. The name will be "Unknown Provider" if the name is
-  // unidentifiable, for example, if the provider is part of a namespace.
-  // TODO(kendalllane): Fix documentation of providers from namespaces.
+  // The names of the providers.
+  //
+  // This field is only intended for rendering human-readable output.
+  // Please use origin_key (a list of the same length and in the same order as
+  // this field) for cross-references and tooling.
+  //
+  // Note: legacy Stardoc (0.5.x and earlier) is unable to extract the name in
+  // some circumstances (for example, if the provider is nested in a struct),
+  // and in that case, the provider name will be "Unknown Provider".
   repeated string provider_name = 1;
+
+  // A list of unambiguous references to providers, of the same length and in
+  // the same order as the provider_name list.
+  //
+  // For provider symbols, this means modules where and the names under which
+  // the providers were originally declared.
+  //
+  // For legacy struct providers, origin_key.file is unset.
+  //
+  // Note: legacy Stardoc (0.5.x and earlier) does not set this field.
+  repeated OriginKey origin_key = 2;
 }
 
 // Representation of Starlark function definition.
 message StarlarkFunctionInfo {
-  // The name of the function.
+  // The name under which the function is made accessible to a user of this
+  // module, including any structs it is nested in, for example
+  // "foo.frobnicate".
   string function_name = 1;
 
   // The parameters for the function.
@@ -129,6 +163,12 @@ message StarlarkFunctionInfo {
 
   // The deprecation for the function.
   FunctionDeprecationInfo deprecated = 5;
+
+  // The module where and the name under which the function was originally
+  // declared.
+  //
+  // Note: legacy Stardoc (0.5.x and earlier) does not set this field.
+  OriginKey origin_key = 6;
 }
 
 // Representation of a Starlark function parameter definition.
@@ -174,19 +214,28 @@ message ProviderFieldInfo {
 
 // Representation of a Starlark provider definition.
 message ProviderInfo {
-  // The name of the provider.
+  // The name under which the provider is made accessible to a user of this
+  // module, including any structs it is nested in, for example "foo.FooInfo".
   string provider_name = 1;
 
   // The description of the provider.
   string doc_string = 2;
 
   // The fields of the provider.
   repeated ProviderFieldInfo field_info = 3;
+
+  // The module where and the name under which the provider was originally
+  // declared.
+  //
+  // Note: legacy Stardoc (0.5.x and earlier) does not set this field.
+  OriginKey origin_key = 4;
 }
 
 // Representation of a Starlark aspect definition.
 message AspectInfo {
-  // The name of the aspect.
+  // The name under which the aspect is made accessible to a user of this
+  // module, including any structs it is nested in, for example
+  // "foo.foo_aspect".
   string aspect_name = 1;
 
   // The documentation string of the aspect.
@@ -197,4 +246,27 @@ message AspectInfo {
 
   // The attributes of the aspect.
   repeated AttributeInfo attribute = 4;
+
+  // The module where and the name under which the aspect was originally
+  // declared.
+  //
+  // Note: legacy Stardoc (0.5.x and earlier) does not set this field.
+  OriginKey origin_key = 5;
+}
+
+// Representation of the origin of a rule, provider, aspect, or function.
+// Intended to be used for building unambiguous cross-references: for example,
+// between an element of a ProviderNameGroup required by a rule attribute and
+// its corresponding ProviderInfo.
+message OriginKey {
+  // The name under which the entity was originally exported. Unset when the
+  // entity was not exported in its module.
+  string name = 1;
+
+  // The display form of the label of the module file in which the entity was
+  // originally declared (as seen from the starlark_doc_extract or Stardoc
+  // target's repo), or "<native>" for Bazel's built-in entities implemented in
+  // Java. Unset when there is no module file (such as for legacy struct
+  // providers, when the module is a REPL, or in Bazel's internal tests).
+  string file = 2;
 }

stardoc/templates/markdown_tables/aspect.vm

@@ -27,6 +27,6 @@ $aspectInfo.getDocString()
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 #foreach ($attribute in $aspectInfo.getAttributeList())
-| <a id="${aspectName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end  | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) `$attribute.defaultValue` #end |
+| <a id="${aspectName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end  | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) `${util.markdownInlineCodeEscape($attribute.defaultValue)}` #end |
 #end
 #end

stardoc/templates/markdown_tables/func.vm

@@ -15,7 +15,7 @@ ${funcInfo.docString}
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 #foreach ($param in $funcInfo.getParameterList())
-| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else <p align="center"> - </p> #end  | #if(!$param.getDefaultValue().isEmpty()) `$param.getDefaultValue()` #else none #end|
+| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else <p align="center"> - </p> #end  | #if(!$param.getDefaultValue().isEmpty()) `${util.markdownInlineCodeEscape($param.defaultValue)}` #else none #end|
 #end
 #end
 #if (!$funcInfo.getReturn().docString.isEmpty())

stardoc/templates/markdown_tables/rule.vm

@@ -15,6 +15,6 @@ ${ruleInfo.docString}
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 #foreach ($attribute in $ruleInfo.getAttributeList())
-| <a id="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end  | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) `$attribute.defaultValue` #end |
+| <a id="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end  | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) `${util.markdownInlineCodeEscape($attribute.defaultValue)}` #end |
 #end
 #end

test/testdata/angle_bracket_test/golden.md

@@ -79,7 +79,7 @@ foo = "<thing>"
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 | <a id="bracket_function-param"></a>param |  an arg with **formatted** docstring, <code>&lt;default&gt;</code> by default.   |  `"<default>"` |
-| <a id="bracket_function-md_string"></a>md_string |  A markdown string.   |  `"foo `1<<10` bar"` |
+| <a id="bracket_function-md_string"></a>md_string |  A markdown string.   |  `` "foo `1<<10` bar" `` |
 
 **RETURNS**