xref: /aosp_15_r20/external/stardoc/docs/generating_stardoc.md (revision b2fa42943c124aa9c7163734493fc7a7559681cf) 
1<nav class="toc">
2  <h2>Contents</h2>
3  <ul>
4    <li><a href="#single-file">Single File</a></li>
5    <li><a href="#files-with-deps">Files with Dependencies</a></li>
6    <li><a href="#multiple-files">Multiple Files</a></li>
7  </ul>
8</nav>
9
10The following are some examples of how to use Stardoc.
11
12<a name="single-file"></a>
13## Single File
14
15Suppose you have a project containing Stardoc rules you want to document:
16
17```
18[workspace]/
19    WORKSPACE
20    checkstyle/
21        BUILD
22        checkstyle.bzl
23```
24
25To generate documentation for the rules in `checkstyle.bzl`, add the
26following target to `rules/BUILD`:
27
28```python
29load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
30
31stardoc(
32    name = "checkstyle-docs",
33    input = "checkstyle.bzl",
34    out = "checkstyle_doc.md",
35)
36```
37
38Running `bazel build //checkstyle:checkstyle-docs` will generate a markdown file
39containing documentation for all Starlark rules defined in `checkstyle.bzl`.
40
41To generate a subset of rules defined in `checkstyle.bzl`, you may specify which
42rule names you specifically want documentation for using the `symbol_names` attribute
43of the `stardoc` rule. If `symbol_names` is specified, only rules matching a name
44in `symbol_names` will be documented:
45
46```python
47load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
48
49stardoc(
50    name = "checkstyle-docs",
51    input = "checkstyle.bzl",
52    out = "checkstyle_doc.md",
53    symbol_names = ["checkstyle_rule", "other_rule"],
54)
55```
56
57<a name="files-with-deps"></a>
58## Files with Dependencies
59
60If you would like to generate documentation for a `.bzl` with dependencies on
61other `.bzl` files, use the `bzl_library` rule to create logical collections of
62Starlark sources and depend on these libraries via the `deps` attribute of your
63`stardoc` target.
64
65Suppose your project has the following structure:
66
67```
68[workspace]/
69    WORKSPACE
70    BUILD
71    checkstyle/
72        BUILD
73        checkstyle.bzl
74    lua/
75        BUILD
76        lua.bzl
77        luarocks.bzl
78```
79
80...and suppose your target `.bzl` file depends on other `.bzl` files in your workspace:
81
82`checkstyle/checkstyle.bzl`:
83
84```python
85load("//lua:lua.bzl", "lua_utility")
86
87lua_utility()
88
89checkstyle_rule = rule(
90    ...
91)
92```
93
94In this case, you can have a `bzl_library` target in `lua/BUILD`:
95
96`lua/BUILD`:
97
98```python
99load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
100
101bzl_library(
102    name = "lua-rules",
103    srcs = [
104        "lua.bzl",
105        "luarocks.bzl",
106    ],
107)
108```
109
110To build documentation for `checkstyle.bzl`, specify the `bzl_library` target
111as a dependency of the `stardoc` target:
112
113`checkstyle/BUILD`:
114
115```python
116load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
117
118stardoc(
119    name = "checkstyle-docs",
120    input = "checkstyle.bzl",
121    out = "checkstyle_doc.md",
122    deps = ["//lua:lua-rules"],
123)
124```
125
126<a name="multiple-files"></a>
127## Multiple Files
128
129If you would like to generate documentation for multiple .bzl files in various
130packages in your workspace, you will need to create a single `.bzl` file that depends
131on all those `.bzl` files. You can then explicitly whitelist rules for which you would
132like documentation to be generated.
133
134For example, you may want to generate documentation for `foo_rule`, `bar_rule`, and
135`baz_rule`, all in different `.bzl` files. First, you would create a single `.bzl` file
136which loads these files and binds the rules to be documented as globals:
137
138`doc_hub.bzl`:
139
140```python
141load("//foo:foo.bzl", _foo_rule = "foo_rule")
142load("//bar:bar.bzl", _bar_rule = "bar_rule")
143load("//baz:baz.bzl", _baz_rule = "baz_rule")
144
145foo_rule = _foo_rule
146bar_rule = _bar_rule
147baz_rule = _baz_rule
148
149# No need for any implementation here. The rules need only be loaded.
150```
151
152A single `stardoc` target can then be used to generate their documentation:
153
154`BUILD`:
155
156```python
157load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
158
159stardoc(
160    name = "my-docs",
161    input = "doc_hub.bzl",
162    out = "docs.md",
163    symbol_names = ["foo_rule", "bar_rule", "baz_rule"],
164)
165```
166
167
168