Add stardoc rule documentation to docs/ (#7)

* Add stardoc rule documentation to docs/

Also ensure (via a test) that this rule documentation is up to date.

7 files changed, 46 insertions, 26 deletions

diff --git a/BUILD b/BUILD
index 408d31f..410334f 100644
--- a/BUILD
+++ b/BUILD
@@ -1,3 +1,10 @@
 licenses(["notice"])  # Apache 2.0
 
 exports_files(["LICENSE"])
+
+filegroup(
+    name = "stardoc_rule_doc",
+    testonly = 1,
+    srcs = ["docs/stardoc_rule.md"],
+    visibility = ["//test:__pkg__"],
+)
diff --git a/README.md b/README.md
index aba176d..27a2aae 100644
--- a/README.md
+++ b/README.md
@@ -5,8 +5,9 @@
 Stardoc is a documentation generator for [Bazel](https://bazel.build) build rules
 written in [Starlark](https://bazel.build/docs/skylark/index.html).
 
-Stardoc provides a Starlark rule (`stardoc`) that can be used to build documentation
-for Starlark rules in Markdown. Stardoc generates one documentation page per `.bzl` file.
+Stardoc provides a Starlark rule (`stardoc`, see [documentation](docs/stardoc_rule.md)) that can
+be used to build documentation for Starlark rules in Markdown. Stardoc generates one documentation
+page per `.bzl`file.
 
 ## Get Started
 
@@ -16,6 +17,7 @@ for Starlark rules in Markdown. Stardoc generates one documentation page per `.b
 
 ## About Stardoc
 
+* Stardoc [rule reference](docs/stardoc_rule.md).
 * How to [contribute to Stardoc](docs/contributing.md)
 
 ## Skydoc deprecation
diff --git a/test/self_doc_golden.md b/docs/stardoc_rule.md
index b6d0091..3b66271 100755..100644
--- a/test/self_doc_golden.md
+++ b/docs/stardoc_rule.md
@@ -30,26 +30,8 @@ This rule is an experimental replacement for the existing skylark_doc rule.
 | provider_template |  The input file template for generating documentation of providers.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional |
 | renderer |  The location of the renderer tool.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional |
 | rule_template |  The input file template for generating documentation of rules.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional |
-| semantic_flags |  A list of canonical flags to affect Starlark semantics for the Starlark interpretter<br>during documentation generation. This should only be used to maintain compatibility with<br>non-default semantic flags required to use the given Starlark symbols.<br>&lt;br&gt;&lt;br&gt;For example, if &lt;code&gt;//foo:bar.bzl&lt;/code&gt; does not build except when a user would specify<br>&lt;code&gt;--incompatible_foo_semantic=false&lt;/code&gt;, then this attribute should contain<br>"--incompatible_foo_semantic=false".   | List of strings | optional |
+| semantic_flags |  A list of canonical flags to affect Starlark semantics for the Starlark interpretter<br>during documentation generation. This should only be used to maintain compatibility with<br>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<br><code>--incompatible_foo_semantic=false</code>, then this attribute should contain<br>"--incompatible_foo_semantic=false".   | List of strings | optional |
 | stardoc |  The location of the stardoc tool.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional |
 | symbol_names |  A list of symbol names to generate documentation for. These should correspond to<br>the names of rule definitions in the input file. If this list is empty, then<br>documentation for all exported rule definitions will be generated.   | List of strings | optional |
 
 
-<a name="#_stardoc_impl"></a>
-
-## _stardoc_impl
-
-<pre>
-_stardoc_impl(<a href="#_stardoc_impl-ctx">ctx</a>)
-</pre>
-
-Implementation of the stardoc rule.
-
-**PARAMETERS**
-
-
-| Name  | Description | Default Value |
-| :-------------: | :-------------: | :-------------: |
-| ctx |  <p align="center"> - </p>   |  none |
-
-
diff --git a/stardoc/BUILD b/stardoc/BUILD
index 115d983..a67873e 100644
--- a/stardoc/BUILD
+++ b/stardoc/BUILD
@@ -32,7 +32,6 @@ stardoc(
     input = ":stardoc.bzl",
     symbol_names = [
         "stardoc",
-        "_stardoc_impl",
     ],
     deps = [":stardoc_lib"],
 )
diff --git a/stardoc/stardoc.bzl b/stardoc/stardoc.bzl
index 0094b2c..a1f461f 100644
--- a/stardoc/stardoc.bzl
+++ b/stardoc/stardoc.bzl
@@ -145,8 +145,9 @@ documentation for all exported rule definitions will be generated.
 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
+
+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".
 """,
             default = [],
diff --git a/test/BUILD b/test/BUILD
index a8d65db..a9a62b1 100644
--- a/test/BUILD
+++ b/test/BUILD
@@ -7,10 +7,10 @@ sh_test(
     srcs = ["diff_test_runner.sh"],
     args = [
         "$(location //stardoc:stardoc_doc.md)",
-        "$(location :self_doc_golden.md)",
+        "$(location //:stardoc_rule_doc)",
     ],
     data = [
-        "self_doc_golden.md",
+        "//:stardoc_rule_doc",
         "//stardoc:stardoc_doc.md",
     ],
 )
diff --git a/update-stardoc-docs.sh b/update-stardoc-docs.sh
new file mode 100755
index 0000000..986f5c2
--- /dev/null
+++ b/update-stardoc-docs.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Copyright 2019 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.
+#
+# Renerates the Stardoc rule documentation from source in @io_bazel.
+#
+# This should only need to be run for cutting a new Stardoc release.
+
+set -eu
+
+echo "** Generating Stardoc documentation..."
+bazel build //stardoc:stardoc_doc.md
+
+echo "** Copying result to docs/stardoc_rule.md ..."
+cp bazel-bin/stardoc/stardoc_doc.md docs/stardoc_rule.md
+
+echo "** Done! Please manually verify the new documentation looks good before committing."
+