sphinxdocs/docs/starlark-docgen.md

# Starlark docgen

Using the `sphinx_stardoc` rule, API documentation can be generated from bzl
source code. This rule requires both MyST-based markdown and the `sphinx_bzl`
Sphinx extension are enabled. This allows source code to use Markdown and
Sphinx syntax to create rich documentation with cross references, types, and
more.


## Configuring Sphinx

While the `sphinx_stardoc` rule doesn't require Sphinx itself, the source
it generates requires some additional Sphinx plugins and config settings.

When defining the `sphinx_build_binary` target, also depend on:
* `@rules_python//sphinxdocs/src/sphinx_bzl:sphinx_bzl`
* `myst_parser` (e.g. `@pypi//myst_parser`)
* `typing_extensions` (e.g. `@pypi//myst_parser`)

```
sphinx_build_binary(
    name = "sphinx-build",
    deps = [
        "@rules_python//sphinxdocs/src/sphinx_bzl",
        "@pypi//myst_parser",
        "@pypi//typing_extensions",
        ...
    ]
)
```

In `conf.py`, enable the `sphinx_bzl` extension, `myst_parser` extension,
and the `colon_fence` MyST extension.

```
extensions = [
    "myst_parser",
    "sphinx_bzl.bzl",
]

myst_enable_extensions = [
    "colon_fence",
]
```

## Generating docs from bzl files

To convert the bzl code to Sphinx doc sources, `sphinx_stardocs` is the primary
rule to do so. It takes a list of `bzl_library` targets or files and generates docs for
each. When a `bzl_library` target is passed, the `bzl_library.srcs` value can only
have a single file.

Example:

```
sphinx_stardocs(
    name = "my_docs",
    srcs = [
      ":binary_bzl",
      ":library_bzl",
    ]
)

bzl_library(
   name = "binary_bzl",
   srcs = ["binary.bzl"],
   deps = ...
)

bzl_library(
   name = "library_bzl",
   srcs = ["library.bzl"],
   deps = ...
)
```

## User-defined types

While Starlark doesn't have user-defined types as a first-class concept, it's
still possible to create such objects using `struct` and lambdas. For the
purposes of documentation, they can be documented by creating a module-level
`struct` with matching fields *and* also a field named `TYPEDEF`. When the
`sphinx_stardoc` rule sees a struct with a `TYPEDEF` field, it generates doc
using the {rst:directive}`bzl:typedef` directive and puts all the struct's fields
within the typedef. The net result is the rendered docs look similar to how
a class would be documented in other programming languages.

For example, a the Starlark implemenation of a `Square` object with a `area()`
method would look like:

```

def _Square_typedef():
    """A square with fixed size.

    :::{field} width
    :type: int
    :::
    """

def _Square_new(width):
    """Creates a Square.

    Args:
        width: {type}`int` width of square

    Returns:
        {type}`Square`
    """
    self = struct(
        area = lambda *a, **k: _Square_area(self, *a, **k),
        width = width
    )
    return self

def _Square_area(self, ):
   """Tells the area of the square."""
   return self.width * self.width

Square = struct(
  TYPEDEF = _Square_typedef,
  new = _Square_new,
  area = _Square_area,
)
```

This will then genereate markdown that looks like:

```
::::{bzl:typedef} Square
A square with fixed size

:::{bzl:field} width
:type: int
:::
:::{bzl:function} new()
...args etc from _Square_new...
:::
:::{bzl:function} area()
...args etc from _Square_area...
:::
::::
```

Which renders as:

:::{bzl:currentfile} //example:square.bzl
:::

::::{bzl:typedef} Square
A square with fixed size

:::{bzl:field} width
:type: int
:::
:::{bzl:function} new()
...
:::
:::{bzl:function} area()
...
:::
::::