1<nav class="toc"> 2 <h2>Contents</h2> 3 <ul> 4 <li><a href="#docstring-formatting">Docstring Formatting</a></li> 5 <li><a href="#custom-output">Custom Output</a></li> 6 </ul> 7</nav> 8 9This document covers a number of advanced topics pertaining to using Stardoc. 10 11 12<a name="docstring-formatting"></a> 13## Docstring Formatting 14 15You may want to inline various kinds of formatting in the docstrings adjacent 16to your Starlark code. Use standard markdown formatting constructs instead of 17HTML tags. 18 19For example: 20```python 21def my_function(foo, bar): 22 """Does some cool stuff. 23 24 Oh, by the way, have you heard about [Stardoc](https://github.com/bazelbuild/stardoc)? 25 26 Args: 27 foo: You don't know what a **foo** is? 28 bar: Two variables, `x` and `y`, walk in to a bar... 29 """ 30 ... 31``` 32 33Markdown formatting constructs are handled appropriately by Stardoc's default 34output format ("markdown_tables"), even as part of a table. 35 36 37<a name="custom-output"></a> 38## Custom Output 39 40Stardoc's output format is customizable; while Stardoc's output is markdown 41by default, you may define a different output format for your documentation. 42 43Customization is done at the level of "output templates". To customize the 44doc output for a particular type of Starlark definition (such as a "rule" or a 45"function"), you will need to: 46 471. Create a new custom output template to describe how this type of object should 48 be rendered. 492. In your `stardoc()` target, set the matching `_template` attribute to point to 50 your new output template. 51 52For example, you might want to change the way rule documentation is generated. 53You might create a new output template file `package/rule.vm` and then define your 54`stardoc` target as follows: 55 56```python 57stardoc( 58 name = "my_docs", 59 input = "my_rule.bzl", 60 out = "my_rule_doc.md", 61 rule_template = "//package:rule.vm", 62) 63``` 64 65The default values for the available templates may be found under 66[templates/markdown_tables](../stardoc/templates/markdown_tables). See the 67[Stardoc rule documentation](stardoc_rule.md) for a comprehensive list of which 68'_template' attributes are available. 69 70 71### Writing a custom output template 72 73Stardoc's output templates are defined using 74[Velocity Template Language (VTL)](https://velocity.apache.org/engine/1.7/user-guide.html) 75with utilities and model objects available in the evaluation context. 76 77The full comprehensive list of available utilities top-level objects is available in 78[the source for MarkdownRenderer](https://github.com/bazelbuild/bazel/blob/3fcfbe14ddec34889c5e3fe33415af2cf9124e7c/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java#L100). 79 80Information available for raw model objects (such rule information) is defined by 81Stardoc's underlying [proto schema](https://github.com/bazelbuild/bazel/blob/5eeccd8a647df10d154d3b86e9732e7f263c96db/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto). 82 83This is a particularly advanced feature of Stardoc, so we would recommend using 84one of the existing canonical [templates](../stardoc/templates/markdown_tables) as a 85springboard to get started. 86 87 88