xref: /aosp_15_r20/external/stardoc/docs/skydoc_deprecation.md (revision b2fa42943c124aa9c7163734493fc7a7559681cf) 
1## Why was Skydoc deprecated?
2
3Skydoc functioned by evaluating Starlark files as if they were Python. Unfortunately, while
4Starlark is **similar** to Python, there are some important syntactic differences between
5the languages. Assuming compatibility between the languages was inherently brittle, and resulted
6in a maintenance burden on the Starlark code. Specifically, if one of your transitive dependencies
7were to adopt a Starlark-compatible, Python-incompatible construct, your Skydoc integration would
8break!
9
10Skydoc still exists under [bazelbuild/skydoc](https://github.com/bazelbuild/skydoc), as it's a
11nontrivial migration to Stardoc, but Skydoc is completely unsupported as of September 2019.
12The [bazelbuild/skydoc](https://github.com/bazelbuild/skydoc) will be archived by end of 2019.
13
14## How to migrate
15
16Stardoc is not a drop-in replacement for Skydoc. Its usage is slightly different, and it has some
17new features. It's recommended to take a look at the root Stardoc documentation, but here is
18a brief summary of some things to note for migration:
19
20### Docstring specification
21
22Stardoc uses inline documentation strings instead of Python-style docstrings.
23For example, Skydoc documentation may have been specified with:
24
25```python
26my_rule = rule(
27    implementation = _my_rule_impl,
28    attrs = {
29        "srcs": attr.label_list(),
30        "deps": attr.label_list(),
31    },
32)
33"""Example rule documentation.
34
35Example:
36  Here is an example of how to use this rule.
37
38Args:
39  srcs: Source files used to build this target.
40  deps: Dependencies for this target.
41"""
42```
43
44...the equivalent for Stardoc is:
45
46```python
47my_rule = rule(
48    implementation = _my_rule_impl,
49    doc = """
50Example rule documentation.
51
52Example:
53  Here is an example of how to use this rule.
54""",
55    attrs = {
56        "srcs" : attr.label_list(
57            doc = "Source files used to build this target.",
58        ),
59        "deps" : attr.label_list(
60            doc = "Dependencies for this target.",
61        ),
62    }
63)
64```
65
66### Different Starlark Rule
67
68Stardoc uses a different Starlark rule than Skydoc with different attributes.
69
70See [Generating Documentation](generating_stardoc.md) for a
71tutorial on using the new rule, and the
72[Build Rule Reference](docs/stardoc_reference.md) for information
73about the new `stardoc` rule itself.
74
75### Starlark Dependencies
76
77Stardoc depends on your `bzl` file, all of its dependencies, and all of its **transitive**
78dependencies, so that it can fully evaluate your Starlark code.
79`bazel-skylib`'s `bzl_library` is the recommend approach for tracking `bzl` dependencies.
80
81For example, suppose your `mypackage/foo.bzl` file depends on `other/package/bar.bzl`, which
82depends on `third/package/baz.bzl`.
83
84**BUILD**:
85
86```python
87load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
88
89stardoc(
90    name = "foo_docs",
91    input = "foo.bzl",
92    out = "foo_doc.md",
93    deps = ["//other/package:bar"],
94)
95```
96
97**other/package/BUILD**:
98
99```python
100load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
101
102bzl_library(
103    name = "bar",
104    srcs = ["bar.bzl"],
105    deps = ["//third/package:baz"],
106)
107```
108
109**third/package/BUILD**:
110
111```python
112load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
113
114bzl_library(
115    name = "baz",
116    srcs = ["baz.bzl"],
117)
118```
119
120Thus, each `.bzl` file should appear in the `srcs` of a `bzl_library` target defined in the same
121package. The `deps` of this `bzl_library` should be (only) the `bzl_library` targets corresponding
122to the files that are _directly_ `load()`ed by the `srcs`. This structure mirrors that of other
123`<language>_library` rules in Bazel.
124
125This migration might involve creating a large number of new `bzl_library` targets,
126but this work is useful beyond Stardoc. For example, `bzl_library` can be also used to gather
127transitive Starlark dependencies for use in shell tests or other test frameworks.
128
129See [Generating Documentation](docs/generating_stardoc.md) for
130a tutorial.
131
132## Migration Issues
133
134If you run into any issues migrating, please file a
135[GitHub issue](https://github.com/bazelbuild/stardoc/issues).
136
137
138