diff --git a/docs/stardoc_rule.md b/docs/stardoc_rule.md index efa229dc..532855ab 100644 --- a/docs/stardoc_rule.md +++ b/docs/stardoc_rule.md @@ -23,18 +23,18 @@ This rule is an experimental replacement for the existing skylark_doc rule. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | -| aspect_template | The input file template for generating documentation of aspects. | Label | optional | //stardoc:templates/markdown_tables/aspect.vm | -| deps | A list of bzl_library dependencies which the input depends on. | List of labels | optional | [] | -| format | The format of the output file. Valid values: 'markdown' or 'proto'. | String | optional | "markdown" | -| func_template | The input file template for generating documentation of functions. | Label | optional | //stardoc:templates/markdown_tables/func.vm | -| header_template | The input file template for the header of the output documentation. | Label | optional | //stardoc:templates/markdown_tables/header.vm | -| input | The starlark file to generate documentation for. | Label | optional | None | +| aspect_template | The input file template for generating documentation of aspects. | Label | optional | //stardoc:templates/markdown_tables/aspect.vm | +| deps | A list of bzl_library dependencies which the input depends on. | List of labels | optional | [] | +| format | The format of the output file. Valid values: 'markdown' or 'proto'. | String | optional | "markdown" | +| func_template | The input file template for generating documentation of functions. | Label | optional | //stardoc:templates/markdown_tables/func.vm | +| header_template | The input file template for the header of the output documentation. | Label | optional | //stardoc:templates/markdown_tables/header.vm | +| input | The starlark file to generate documentation for. | Label | optional | None | | out | The (markdown) file to which documentation will be output. | Label | required | | -| provider_template | The input file template for generating documentation of providers. | Label | optional | //stardoc:templates/markdown_tables/provider.vm | -| renderer | The location of the renderer tool. | Label | optional | //stardoc:renderer | -| rule_template | The input file template for generating documentation of rules. | Label | optional | //stardoc:templates/markdown_tables/rule.vm | -| semantic_flags | A list of canonical flags to affect Starlark semantics for the Starlark interpretter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols.

For example, if //foo:bar.bzl does not build except when a user would specify --incompatible_foo_semantic=false, then this attribute should contain "--incompatible_foo_semantic=false". | List of strings | optional | [] | -| stardoc | The location of the stardoc tool. | Label | optional | //stardoc:stardoc | -| symbol_names | A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated. | List of strings | optional | [] | +| provider_template | The input file template for generating documentation of providers. | Label | optional | //stardoc:templates/markdown_tables/provider.vm | +| renderer | The location of the renderer tool. | Label | optional | //stardoc:renderer | +| rule_template | The input file template for generating documentation of rules. | Label | optional | //stardoc:templates/markdown_tables/rule.vm | +| semantic_flags | A list of canonical flags to affect Starlark semantics for the Starlark interpretter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols.

For example, if //foo:bar.bzl does not build except when a user would specify --incompatible_foo_semantic=false, then this attribute should contain "--incompatible_foo_semantic=false". | List of strings | optional | [] | +| stardoc | The location of the stardoc tool. | Label | optional | //stardoc:stardoc | +| symbol_names | A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated. | List of strings | optional | [] | diff --git a/stardoc/templates/markdown_tables/aspect.vm b/stardoc/templates/markdown_tables/aspect.vm index 04cd9757..aa9f13bf 100644 --- a/stardoc/templates/markdown_tables/aspect.vm +++ b/stardoc/templates/markdown_tables/aspect.vm @@ -6,7 +6,7 @@ ${util.aspectSummary($aspectName, $aspectInfo)} -$aspectInfo.getDocString() +${util.htmlEscape($aspectInfo.getDocString())} **ASPECT ATTRIBUTES** @@ -27,6 +27,6 @@ $aspectInfo.getDocString() | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | #foreach ($attribute in $aspectInfo.getAttributeList()) -| $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue | +| $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.htmlEscape($attribute.defaultValue)} #end | #end #end diff --git a/stardoc/templates/markdown_tables/func.vm b/stardoc/templates/markdown_tables/func.vm index d66db69f..5275d088 100644 --- a/stardoc/templates/markdown_tables/func.vm +++ b/stardoc/templates/markdown_tables/func.vm @@ -6,7 +6,7 @@ ${util.funcSummary($funcInfo)} -${funcInfo.docString} +${util.htmlEscape($funcInfo.docString)} #if (!$funcInfo.getParameterList().isEmpty()) **PARAMETERS** @@ -15,18 +15,18 @@ ${funcInfo.docString} | Name | Description | Default Value | | :------------- | :------------- | :------------- | #foreach ($param in $funcInfo.getParameterList()) -| $param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else

-

#end | #if(!$param.getDefaultValue().isEmpty()) $param.getDefaultValue() #else none #end| +| $param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else

-

#end | #if(!$param.getDefaultValue().isEmpty()) ${util.htmlEscape($param.getDefaultValue())} #else none #end| #end #end #if (!$funcInfo.getReturn().docString.isEmpty()) **RETURNS** -${funcInfo.getReturn().docString} +${util.htmlEscape($funcInfo.getReturn().docString)} #end #if (!$funcInfo.getDeprecated().docString.isEmpty()) **DEPRECATED** -${funcInfo.getDeprecated().docString} +${util.htmlEscape($funcInfo.getDeprecated().docString)} #end diff --git a/stardoc/templates/markdown_tables/header.vm b/stardoc/templates/markdown_tables/header.vm index 5556ad69..2b47292f 100644 --- a/stardoc/templates/markdown_tables/header.vm +++ b/stardoc/templates/markdown_tables/header.vm @@ -1,3 +1,3 @@ -${moduleDocstring} +${util.htmlEscape($moduleDocstring)} diff --git a/stardoc/templates/markdown_tables/provider.vm b/stardoc/templates/markdown_tables/provider.vm index 0a866dbb..7ab4c60d 100644 --- a/stardoc/templates/markdown_tables/provider.vm +++ b/stardoc/templates/markdown_tables/provider.vm @@ -6,7 +6,7 @@ ${util.providerSummary($providerName, $providerInfo)} -${providerInfo.docString} +${util.htmlEscape($providerInfo.docString)} **FIELDS** diff --git a/stardoc/templates/markdown_tables/rule.vm b/stardoc/templates/markdown_tables/rule.vm index d2ba6c25..06d9a1f6 100644 --- a/stardoc/templates/markdown_tables/rule.vm +++ b/stardoc/templates/markdown_tables/rule.vm @@ -6,7 +6,7 @@ ${util.ruleSummary($ruleName, $ruleInfo)} -${ruleInfo.docString} +${util.htmlEscape($ruleInfo.docString)} **ATTRIBUTES** @@ -15,6 +15,6 @@ ${ruleInfo.docString} | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | #foreach ($attribute in $ruleInfo.getAttributeList()) -| $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue | +| $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty())${util.htmlEscape($attribute.defaultValue)}#end | #end #end diff --git a/test/testdata/android_basic_test/golden.md b/test/testdata/android_basic_test/golden.md index 7c0d1067..0962201a 100755 --- a/test/testdata/android_basic_test/golden.md +++ b/test/testdata/android_basic_test/golden.md @@ -19,7 +19,7 @@ This rule does android-related things. | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | - | Label | required | | -| fourth | - | Boolean | optional | False | +| fourth | - | Boolean | optional | False | | second | - | Dictionary: String -> String | required | | | third | - | Label | required | | diff --git a/test/testdata/angle_bracket_test/golden.md b/test/testdata/angle_bracket_test/golden.md index 50a209d8..1c31dd2c 100755 --- a/test/testdata/angle_bracket_test/golden.md +++ b/test/testdata/angle_bracket_test/golden.md @@ -1,6 +1,9 @@ -Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186) +Input file to test <angle bracket bugs> + +See https://github.com/bazelbuild/skydoc/issues/186 +and https://github.com/bazelbuild/stardoc/issues/132 @@ -10,7 +13,7 @@ Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issue my_anglebrac(name, useless) -Rule with +Rule with <brackets> **ATTRIBUTES** @@ -18,7 +21,7 @@ Rule with | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | -| useless | Args with some tags: <tag1>, <tag2> | String | optional | "Find " | +| useless | Args with some tags: <tag1>, <tag2> | String | optional | "Find <brackets>" | @@ -29,7 +32,7 @@ Rule with bracketuse(foo, bar, baz) -Information with +Information with <brackets> **FIELDS** @@ -46,12 +49,12 @@ Information with ## bracket_function 
-bracket_function(name)
+bracket_function(param)
-Dummy docstring with . +Dummy docstring with <brackets>. -This rule runs checks on . +This rule runs checks on <angle brackets>. **PARAMETERS** @@ -59,10 +62,41 @@ This rule runs checks on . | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| name | an arg with **formatted** docstring. | none | +| param | an arg with **formatted** docstring, <default> by default. | "<default>" | **RETURNS** -some brackets +some <angled> brackets + +**DEPRECATED** + +deprecated for <reasons> + + + + +## bracket_aspect + +
+bracket_aspect(name, brackets)
+
+ +Aspect with <brackets> + +**ASPECT ATTRIBUTES** + + +| Name | Type | +| :------------- | :------------- | +| deps| String | + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| brackets | Attribute with <brackets> | String | optional | "<default>" | diff --git a/test/testdata/angle_bracket_test/input.bzl b/test/testdata/angle_bracket_test/input.bzl index 69daa7a8..4df0e1fd 100644 --- a/test/testdata/angle_bracket_test/input.bzl +++ b/test/testdata/angle_bracket_test/input.bzl @@ -1,19 +1,23 @@ -"""Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)""" +"""Input file to test -def bracket_function(name): +See https://github.com/bazelbuild/skydoc/issues/186 +and https://github.com/bazelbuild/stardoc/issues/132""" + +def bracket_function(param = ""): """Dummy docstring with . This rule runs checks on . Args: - name: an arg with **formatted** docstring. + param: an arg with **formatted** docstring, by default. Returns: some brackets + Deprecated: + deprecated for """ - _ignore = name # @unused - pass + return param # buildifier: disable=unsorted-dict-items bracketuse = provider( @@ -39,3 +43,19 @@ my_anglebrac = rule( ), }, ) + +def _bracket_aspect_impl(ctx): + _ignore = [ctx] # @unused + return [] + +bracket_aspect = aspect( + implementation = _bracket_aspect_impl, + doc = "Aspect with ", + attr_aspects = ["deps"], + attrs = { + "brackets": attr.string( + doc = "Attribute with ", + default = "", + ), + }, +) diff --git a/test/testdata/apple_basic_test/golden.md b/test/testdata/apple_basic_test/golden.md index 106b5fb6..5a9eb6e8 100755 --- a/test/testdata/apple_basic_test/golden.md +++ b/test/testdata/apple_basic_test/golden.md @@ -19,7 +19,7 @@ This rule does apple-related things. | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | - | Label | required | | -| fourth | - | Boolean | optional | False | +| fourth | - | Boolean | optional | False | | second | - | Dictionary: String -> String | required | | | third | - | Label | required | | diff --git a/test/testdata/attribute_defaults_test/golden.md b/test/testdata/attribute_defaults_test/golden.md index f84184ca..ae62b4c1 100755 --- a/test/testdata/attribute_defaults_test/golden.md +++ b/test/testdata/attribute_defaults_test/golden.md @@ -18,16 +18,16 @@ This is my rule. It does stuff. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | -| a | Some bool | Boolean | optional | False | -| b | Some int | Integer | optional | 2 | -| c | Some int_list | List of integers | optional | [0, 1] | -| d | Some label | Label | optional | //foo:bar | -| e | Some label_keyed_string_dict | Dictionary: Label -> String | optional | {"//foo:bar": "hello", "//bar:baz": "goodbye"} | -| f | Some label_list | List of labels | optional | ["//foo:bar", "//bar:baz"] | -| g | Some string | String | optional | "" | -| h | Some string_dict | Dictionary: String -> String | optional | {"animal": "bunny", "color": "orange"} | -| i | Some string_list | List of strings | optional | ["cat", "dog"] | -| j | Some string_list_dict | Dictionary: String -> List of strings | optional | {"animal": ["cat", "bunny"], "color": ["blue", "orange"]} | +| a | Some bool | Boolean | optional | False | +| b | Some int | Integer | optional | 2 | +| c | Some int_list | List of integers | optional | [0, 1] | +| d | Some label | Label | optional | //foo:bar | +| e | Some label_keyed_string_dict | Dictionary: Label -> String | optional | {"//foo:bar": "hello", "//bar:baz": "goodbye"} | +| f | Some label_list | List of labels | optional | ["//foo:bar", "//bar:baz"] | +| g | Some string | String | optional | "" | +| h | Some string_dict | Dictionary: String -> String | optional | {"animal": "bunny", "color": "orange"} | +| i | Some string_list | List of strings | optional | ["cat", "dog"] | +| j | Some string_list_dict | Dictionary: String -> List of strings | optional | {"animal": ["cat", "bunny"], "color": ["blue", "orange"]} | | k | Some bool | Boolean | required | | | l | Some int | Integer | required | | | m | Some int_list | List of integers | required | | @@ -38,9 +38,9 @@ This is my rule. It does stuff. | r | Some string_dict | Dictionary: String -> String | required | | | s | Some string_list | List of strings | required | | | t | Some string_list_dict | Dictionary: String -> List of strings | required | | -| u | - | String | optional | "" | -| v | - | Label | optional | None | -| w | - | Integer | optional | 0 | +| u | - | String | optional | "" | +| v | - | Label | optional | None | +| w | - | Integer | optional | 0 | @@ -68,7 +68,7 @@ This is my aspect. It does stuff. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | -| y | some string | String | optional | "why" | +| y | some string | String | optional | "why" | | z | - | String | required | | diff --git a/test/testdata/attribute_types_test/golden.md b/test/testdata/attribute_types_test/golden.md index 64e4c353..9a988c1c 100755 --- a/test/testdata/attribute_types_test/golden.md +++ b/test/testdata/attribute_types_test/golden.md @@ -29,6 +29,6 @@ This is my rule. It does stuff. | i | Some string | String | required | | | j | Some string_dict | Dictionary: String -> String | required | | | k | Some string_list | List of strings | required | | -| l | Some string_list_dict | Dictionary: String -> List of strings | optional | {} | +| l | Some string_list_dict | Dictionary: String -> List of strings | optional | {} | diff --git a/test/testdata/cc_api_test/golden.md b/test/testdata/cc_api_test/golden.md index 388336b7..10ca7f8a 100755 --- a/test/testdata/cc_api_test/golden.md +++ b/test/testdata/cc_api_test/golden.md @@ -19,7 +19,7 @@ This rule does C++-related things. | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | - | Label | required | | -| fourth | - | Boolean | optional | False | +| fourth | - | Boolean | optional | False | | second | - | Dictionary: String -> String | required | | | third | - | Label | required | | diff --git a/test/testdata/cpp_basic_test/golden.md b/test/testdata/cpp_basic_test/golden.md index 5f3069fe..7061e26f 100755 --- a/test/testdata/cpp_basic_test/golden.md +++ b/test/testdata/cpp_basic_test/golden.md @@ -19,7 +19,7 @@ This rule does cpp-related things. | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | - | Label | required | | -| fourth | - | Boolean | optional | False | +| fourth | - | Boolean | optional | False | | second | - | Dictionary: String -> String | required | | | third | - | Label | required | | diff --git a/test/testdata/java_basic_test/golden.md b/test/testdata/java_basic_test/golden.md index eeb17093..a6d0818a 100755 --- a/test/testdata/java_basic_test/golden.md +++ b/test/testdata/java_basic_test/golden.md @@ -19,7 +19,7 @@ This rule does java-related things. | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | - | Label | required | | -| fourth | - | Boolean | optional | False | +| fourth | - | Boolean | optional | False | | second | - | Dictionary: String -> String | required | | | third | - | Label | required | | diff --git a/test/testdata/misc_apis_test/golden.md b/test/testdata/misc_apis_test/golden.md index 7e6b6a59..7b94d9f9 100755 --- a/test/testdata/misc_apis_test/golden.md +++ b/test/testdata/misc_apis_test/golden.md @@ -18,11 +18,11 @@ This rule exercises some of the build API. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | -| deps | A list of dependencies. | List of labels | optional | [] | -| extra_arguments | - | List of strings | optional | [] | +| deps | A list of dependencies. | List of labels | optional | [] | +| extra_arguments | - | List of strings | optional | [] | | out | The output file. | Label | required | | -| src | The source file. | Label | optional | None | -| tool | The location of the tool to use. | Label | optional | //foo/bar/baz:target | +| src | The source file. | Label | optional | None | +| tool | The location of the tool to use. | Label | optional | //foo/bar/baz:target | diff --git a/test/testdata/providers_for_attributes_test/golden.md b/test/testdata/providers_for_attributes_test/golden.md index f50f049a..24ebf27c 100755 --- a/test/testdata/providers_for_attributes_test/golden.md +++ b/test/testdata/providers_for_attributes_test/golden.md @@ -18,12 +18,12 @@ This rule does things. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | -| fifth | - | Label | optional | None | -| first | this is the first attribute. | Dictionary: Label -> String | optional | {} | -| fourth | - | Label | optional | None | -| second | - | List of labels | optional | [] | -| sixth | - | Label | optional | None | -| third | - | Label | optional | None | +| fifth | - | Label | optional | None | +| first | this is the first attribute. | Dictionary: Label -> String | optional | {} | +| fourth | - | Label | optional | None | +| second | - | List of labels | optional | [] | +| sixth | - | Label | optional | None | +| third | - | Label | optional | None | diff --git a/test/testdata/py_rule_test/golden.md b/test/testdata/py_rule_test/golden.md index c52885d3..0550bf97 100755 --- a/test/testdata/py_rule_test/golden.md +++ b/test/testdata/py_rule_test/golden.md @@ -18,11 +18,11 @@ This rule does python-related things. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | -| fifth | Hey look, its the fifth thing! | Boolean | optional | True | +| fifth | Hey look, its the fifth thing! | Boolean | optional | True | | first | this is the first doc string! | Label | required | | -| fourth | the fourth doc string. | Boolean | optional | False | +| fourth | the fourth doc string. | Boolean | optional | False | | second | - | Dictionary: String -> String | required | | -| sixth | it's the sixth thing. | List of integers | optional | [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] | +| sixth | it's the sixth thing. | List of integers | optional | [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] | | third | - | Label | required | | diff --git a/test/testdata/repo_rules_test/golden.md b/test/testdata/repo_rules_test/golden.md index b47857b6..87391e35 100755 --- a/test/testdata/repo_rules_test/golden.md +++ b/test/testdata/repo_rules_test/golden.md @@ -19,6 +19,6 @@ Minimal example of a repository rule. | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this repository. | Name | required | | | repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). | Dictionary: String -> String | required | | -| useless | This argument will be ingored. You don't have to specify it, but you may. | String | optional | "ignoreme" | +| useless | This argument will be ingored. You don't have to specify it, but you may. | String | optional | "ignoreme" | diff --git a/test/testdata/simple_test/golden.md b/test/testdata/simple_test/golden.md index ccebdef4..b203bd23 100755 --- a/test/testdata/simple_test/golden.md +++ b/test/testdata/simple_test/golden.md @@ -19,7 +19,7 @@ This is my rule. It does stuff. | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first doc string | Label | required | | -| fourth | fourth doc string | Boolean | optional | False | +| fourth | fourth doc string | Boolean | optional | False | | second | - | Dictionary: String -> String | required | | | third | - | Label | required | |