Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[RFC] Do not print the table row if the docstring is empty. #46

Closed
wants to merge 3 commits into from
Closed

[RFC] Do not print the table row if the docstring is empty. #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8c51351
Do not print the line if the docstring is empty.
fenghaolw Feb 15, 2020
ca420cb
Updates for other templates.
fenghaolw Feb 15, 2020
65108f9
Update golden file tests.
fenghaolw Feb 15, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions docs/stardoc_rule.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,19 +20,19 @@ This rule is an experimental replacement for the existing skylark_doc rule.

| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a name="stardoc-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a name="stardoc-aspect_template"></a>aspect_template | The input file template for generating documentation of aspects. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/aspect.vm |
| <a name="stardoc-deps"></a>deps | A list of skylark_library dependencies which the input depends on. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a name="stardoc-format"></a>format | The format of the output file. Valid values: 'markdown' or 'proto'. | String | optional | "markdown" |
| <a name="stardoc-func_template"></a>func_template | The input file template for generating documentation of functions. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/func.vm |
| <a name="stardoc-header_template"></a>header_template | The input file template for the header of the output documentation. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/header.vm |
| <a name="stardoc-input"></a>input | The starlark file to generate documentation for. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a name="stardoc-out"></a>out | The (markdown) file to which documentation will be output. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a name="stardoc-provider_template"></a>provider_template | The input file template for generating documentation of providers. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/provider.vm |
| <a name="stardoc-renderer"></a>renderer | The location of the renderer tool. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:renderer |
| <a name="stardoc-rule_template"></a>rule_template | The input file template for generating documentation of rules. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/rule.vm |
| <a name="stardoc-semantic_flags"></a>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.<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify <code>--incompatible_foo_semantic=false</code>, then this attribute should contain "--incompatible_foo_semantic=false". | List of strings | optional | [] |
| <a name="stardoc-stardoc"></a>stardoc | The location of the stardoc tool. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:stardoc |
| <a name="stardoc-symbol_names"></a>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 | [] |
| <a name="stardoc-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a name="stardoc-aspect_template"></a>aspect_template | The input file template for generating documentation of aspects. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/aspect.vm |
| <a name="stardoc-deps"></a>deps | A list of skylark_library dependencies which the input depends on. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a name="stardoc-format"></a>format | The format of the output file. Valid values: 'markdown' or 'proto'. | String | optional | "markdown" |
| <a name="stardoc-func_template"></a>func_template | The input file template for generating documentation of functions. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/func.vm |
| <a name="stardoc-header_template"></a>header_template | The input file template for the header of the output documentation. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/header.vm |
| <a name="stardoc-input"></a>input | The starlark file to generate documentation for. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a name="stardoc-out"></a>out | The (markdown) file to which documentation will be output. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a name="stardoc-provider_template"></a>provider_template | The input file template for generating documentation of providers. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/provider.vm |
| <a name="stardoc-renderer"></a>renderer | The location of the renderer tool. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:renderer |
| <a name="stardoc-rule_template"></a>rule_template | The input file template for generating documentation of rules. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/rule.vm |
| <a name="stardoc-semantic_flags"></a>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.<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify <code>--incompatible_foo_semantic=false</code>, then this attribute should contain "--incompatible_foo_semantic=false". | List of strings | optional | [] |
| <a name="stardoc-stardoc"></a>stardoc | The location of the stardoc tool. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:stardoc |
| <a name="stardoc-symbol_names"></a>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 | [] |


4 changes: 3 additions & 1 deletion stardoc/templates/markdown_tables/aspect.vm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ $aspectInfo.getDocString()
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
#foreach ($attribute in $aspectInfo.getAttributeList())
| <a name="${aspectName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue |
#if(!$attribute.docString.isEmpty())
| <a name="${aspectName}-${attribute.name}"></a>$attribute.name | ${util.markdownCellFormat($attribute.docString)} | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue |
#end
#end
#end
4 changes: 3 additions & 1 deletion stardoc/templates/markdown_tables/func.vm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ ${funcInfo.docString}
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
#foreach ($param in $funcInfo.getParameterList())
| <a name="${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()) <code>$param.getDefaultValue()</code> #else none #end|
#if(!$param.docString.isEmpty())
| <a name="${funcInfo.functionName}-${param.name}"></a>$param.name | ${util.markdownCellFormat($param.docString)} | #if(!$param.getDefaultValue().isEmpty()) <code>$param.getDefaultValue()</code> #else none #end|
#end
#end
#end
4 changes: 3 additions & 1 deletion stardoc/templates/markdown_tables/provider.vm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ ${providerInfo.docString}
| Name | Description |
| :------------- | :------------- |
#foreach ($field in $providerInfo.fieldInfoList)
| <a name="${providerName}-${field.name}"></a>$field.name | #if(!$field.docString.isEmpty()) ${util.markdownCellFormat($field.docString)} #else - #end |
#if(!$field.docString.isEmpty())
| <a name="${providerName}-${field.name}"></a>$field.name | ${util.markdownCellFormat($field.docString)} |
#end
#end
#end
4 changes: 3 additions & 1 deletion stardoc/templates/markdown_tables/rule.vm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ ${ruleInfo.docString}
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
#foreach ($attribute in $ruleInfo.getAttributeList())
| <a name="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue |
#if(!$attribute.docString.isEmpty())
| <a name="${ruleName}-${attribute.name}"></a>$attribute.name | ${util.markdownCellFormat($attribute.docString)} | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue |
#end
#end
#end
6 changes: 1 addition & 5 deletions test/testdata/android_basic_test/golden.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,6 @@ This rule does android-related things.

| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a name="android_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a name="android_related_rule-first"></a>first | - | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a name="android_related_rule-fourth"></a>fourth | - | Boolean | optional | False |
| <a name="android_related_rule-second"></a>second | - | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | required | |
| <a name="android_related_rule-third"></a>third | - | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a name="android_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |


12 changes: 6 additions & 6 deletions test/testdata/angle_bracket_test/golden.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ Rule with <brackets>

| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a name="my_anglebrac-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a name="my_anglebrac-useless"></a>useless | Args with some tags: &lt;tag1&gt;, &lt;tag2&gt; | String | optional | "Find <brackets>" |
| <a name="my_anglebrac-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a name="my_anglebrac-useless"></a>useless | Args with some tags: &lt;tag1&gt;, &lt;tag2&gt; | String | optional | "Find <brackets>" |


<a name="#bracketuse"></a>
Expand All @@ -34,9 +34,9 @@ Information with <brackets>

| Name | Description |
| :------------- | :------------- |
| <a name="bracketuse-foo"></a>foo | A string representing &lt;foo&gt; |
| <a name="bracketuse-bar"></a>bar | A string representing bar |
| <a name="bracketuse-baz"></a>baz | A string representing baz |
| <a name="bracketuse-foo"></a>foo | A string representing &lt;foo&gt; |
| <a name="bracketuse-bar"></a>bar | A string representing bar |
| <a name="bracketuse-baz"></a>baz | A string representing baz |


<a name="#bracket_function"></a>
Expand All @@ -57,6 +57,6 @@ This rule runs checks on <angle brackets>.

| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a name="bracket_function-name"></a>name | an arg with **formatted** docstring. | none |
| <a name="bracket_function-name"></a>name | an arg with **formatted** docstring. | none |


6 changes: 1 addition & 5 deletions test/testdata/apple_basic_test/golden.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,6 @@ This rule does apple-related things.

| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a name="apple_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a name="apple_related_rule-first"></a>first | - | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a name="apple_related_rule-fourth"></a>fourth | - | Boolean | optional | False |
| <a name="apple_related_rule-second"></a>second | - | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | required | |
| <a name="apple_related_rule-third"></a>third | - | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a name="apple_related_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |


8 changes: 2 additions & 6 deletions test/testdata/aspect_test/golden.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ my_aspect_impl(<a href="#my_aspect_impl-ctx">ctx</a>)

| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a name="my_aspect_impl-ctx"></a>ctx | <p align="center"> - </p> | none |


<a name="#my_aspect"></a>
Expand All @@ -42,9 +41,7 @@ This is my aspect. It does stuff.

| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a name="my_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a name="my_aspect-first"></a>first | - | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a name="my_aspect-second"></a>second | - | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | required | |
| <a name="my_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |


<a name="#other_aspect"></a>
Expand All @@ -70,7 +67,6 @@ This is another aspect.

| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a name="other_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a name="other_aspect-third"></a>third | - | Integer | required | |
| <a name="other_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |


Loading