Add advanced topics documentation (#18)upstream/0.4.0

5 files changed, 93 insertions, 5 deletions

diff --git a/README.md b/README.md
index 27a2aae..5cff3d9 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,7 @@ page per `.bzl`file.
 * How to [set up Stardoc for your project](docs/getting_started_stardoc.md)
 * Writing [docstrings](docs/writing_stardoc.md)
 * How to [integrate Stardoc with your build](docs/generating_stardoc.md).
+* See also [Advanced Topics](docs/advanced_stardoc_usage.md).
 
 ## About Stardoc
 
diff --git a/docs/advanced_stardoc_usage.md b/docs/advanced_stardoc_usage.md
new file mode 100644
index 0000000..ce3c069
--- /dev/null
+++ b/docs/advanced_stardoc_usage.md
@@ -0,0 +1,87 @@
+<nav class="toc">
+  <h2>Contents</h2>
+  <ul>
+    <li><a href="#docstring-formatting">Docstring Formatting</a></li>
+    <li><a href="#custom-output">Custom Output</a></li>
+  </ul>
+</nav>
+
+This document covers a number of advanced topics pertaining to using Stardoc.
+
+
+<a name="docstring-formatting"></a>
+## Docstring Formatting
+
+You may want to inline various kinds of formatting in the docstrings adjacent
+to your Starlark code. Use standard markdown formatting constructs instead of
+HTML tags.
+
+For example:
+```python
+def my_function(foo, bar):
+  """Does some cool stuff.
+
+  Oh, by the way, have you heard about [Stardoc](https://github.com/bazelbuild/stardoc)?
+
+  Args:
+    foo: You don't know what a **foo** is?
+    bar: Two variables, `x` and `y`, walk in to a bar...
+  """
+  ...
+```
+
+Markdown formatting constructs are handled appropriately by Stardoc's default
+output format ("markdown_tables"), even as part of a table.
+
+
+<a name="custom-output"></a>
+## Custom Output
+
+Stardoc's output format is customizable; while Stardoc's output is markdown
+by default, you may define a different output format for your documentation.
+
+Customization is done at the level of "output templates". To customize the
+doc output for a particular type of Starlark definition (such as a "rule" or a
+"function"), you will need to:
+
+1. Create a new custom output template to describe how this type of object should
+   be rendered.
+2. In your `stardoc()` target, set the matching `_template` attribute to point to
+   your new output template.
+
+For example, you might want to change the way rule documentation is generated.
+You might create a new output template file `package/rule.vm` and then define your
+`stardoc` target as follows:
+
+```python
+stardoc(
+    name = "my_docs",
+    input = "my_rule.bzl",
+    out = "my_rule_doc.md",
+    rule_template = "//package:rule.vm",
+)
+```
+
+The default values for the available templates may be found under
+[templates/markdown_tables](../stardoc/templates/markdown_tables). See the
+[Stardoc rule documentation](stardoc_rule.md) for a comprehensive list of which
+'_template' attributes are available.
+
+
+### Writing a custom output template
+
+Stardoc's output templates are defined using
+[Velocity Template Language (VTL)](https://velocity.apache.org/engine/1.7/user-guide.html)
+with utilities and model objects available in the evaluation context.
+
+The full comprehensive list of available utilities top-level objects is available in
+[the source for MarkdownRenderer](https://github.com/bazelbuild/bazel/blob/3fcfbe14ddec34889c5e3fe33415af2cf9124e7c/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java#L100).
+
+Information available for raw model objects (such rule information) is defined by
+Stardoc's underlying [proto schema](https://github.com/bazelbuild/bazel/blob/5eeccd8a647df10d154d3b86e9732e7f263c96db/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto).
+
+This is a particularly advanced feature of Stardoc, so we would recommend using
+one of the existing canonical [templates](../stardoc/templates/markdown_tables) as a
+springboard to get started.
+
+
diff --git a/docs/stardoc_rule.md b/docs/stardoc_rule.md
index ee22571..71200a0 100644
--- a/docs/stardoc_rule.md
+++ b/docs/stardoc_rule.md
@@ -23,7 +23,7 @@ This rule is an experimental replacement for the existing skylark_doc rule.
 | name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
 | 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 |
 | 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 | [] |
-| format |  The format of the output file.   | String | optional | "markdown" |
+| 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.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //stardoc:templates/markdown_tables/func.vm |
 | 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 |
 | input |  The starlark file to generate documentation for.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
diff --git a/docs/writing_stardoc.md b/docs/writing_stardoc.md
index a365381..6a042c2 100644
--- a/docs/writing_stardoc.md
+++ b/docs/writing_stardoc.md
@@ -3,7 +3,7 @@
   <ul>
     <li><a href="#rule-documentation">Rule Documentation</a></li>
     <li><a href="#provider-documentation">Provider Documentation</a></li>
-    <li><a href="#macro-documentation">Macro Documentation</a></li>
+    <li><a href="#macro-documentation">Macro / Function Documentation</a></li>
   </ul>
 </nav>
 
@@ -82,9 +82,9 @@ Contains information about some of my favorite things.
 ```
 
 <a name="macro-documentation"></a>
-## Macro Documentation
+## Macro / Function Documentation
 
-[Starlark Macros](https://bazel.build/docs/skylark/macros.html) are documented
+Functions and [Starlark Macros](https://bazel.build/docs/skylark/macros.html) are documented
 using docstrings similar to Python docstring format:
 
 ```python
diff --git a/stardoc/stardoc.bzl b/stardoc/stardoc.bzl
index a1f461f..456aca7 100644
--- a/stardoc/stardoc.bzl
+++ b/stardoc/stardoc.bzl
@@ -124,7 +124,7 @@ This rule is an experimental replacement for the existing skylark_doc rule.
             providers = [StarlarkLibraryInfo],
         ),
         "format": attr.string(
-            doc = "The format of the output file.",
+            doc = "The format of the output file. Valid values: 'markdown' or 'proto'.",
             default = "markdown",
             values = ["markdown", "proto"],
         ),