Fix rendering of examples

Author: rickeylev

sphinxdocs/docs/sphinx-bzl.md

@@ -227,6 +227,11 @@ The documentation renders using RST notation (`.. directive::`), not
 MyST notation.
 :::
 
+Directives can be nested, but [the inner directives must have **fewer** colons
+than outer
+directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives).
+
+
 :::{rst:directive} .. bzl:currentfile:: file
 
 This directive indicates the Bazel file that objects defined in the current
@@ -237,46 +242,85 @@ files, and `//foo:BUILD.bazel` for things in BUILD files.
 :::
 
 
-:::{rst:directive} .. bzl:target:: target
+:::::{rst:directive} .. bzl:target:: target
 
 Documents a target. It takes no directive options. The format of `target`
 can either be a fully qualified label (`//foo:bar`), or the base target name
 relative to `{bzl:currentfile}`.
 
-```
+````
 :::{bzl:target} //foo:target
 
 My docs
 :::
-```
+````
+
+:::::
 
 :::{rst:directive} .. bzl:flag:: target
 
 Documents a flag. It has the same format as `{bzl:target}`
 :::
 
+::::::{rst:directive} .. bzl:typedef:: typename
 
-:::{rst:directive} .. bzl:typedef:: typename
+Documents a user-defined structural "type".  These are typically generated by
+the {obj}`sphinx_stardoc` rule after following [User-defined types] to create a
+struct with a `TYPEDEF` field, but can also be manually defined if there's
+no natural place for it in code, e.g. some ad-hoc structural type.
 
-Documents a user-defined structural "type".  These are typically generated
-by following [User-defined types] to create a struct with a `TYPEDEF` field.
-
-```
+`````
 ::::{bzl:typedef} Square
+Doc about Square
 
 :::{bzl:field} width
 :type: int
 :::
 
 :::{bzl:function} new(size)
+  ...
 :::
 
 :::{bzl:function} area()
+  ...
 :::
 ::::
-```
+`````
 
-Note that, due to a Sphinx and/or MyST bug, the number of colons for the
-outer typedef directive must be greater than the inner directives. Otherwise,
-only the first nested directive is parsed as part of the type def.
-:::
+Note that MyST requires the number of colons for the outer typedef directive
+to be greater than the inner directives. Otherwise, only the first nested
+directive is parsed as part of the typedef, but subsequent ones are not.
+::::::
+
+:::::{rst:directive} .. bzl:field:: fieldname
+
+Documents a field of an object. These are nested within some other directive,
+typically `{bzl:typedef}`
+
+Directive options:
+* `:type:` specifies the type of the field
+
+````
+:::{bzl:field} fieldname
+:type: int | None | str
+
+Doc about field
+````
+:::::
+
+:::::{rst:directive} .. bzl:provider-field:: fieldname
+
+Documents a field of a provider. The directive itself is autogenerated by
+`sphinx_stardoc`, but the content is simply the documentation string specified
+in the provider's field.
+
+Directive options:
+* `:type:` specifies the type of the field
+
+````
+:::{bzl:provider-field} fieldname
+:type: depset[File] | None
+
+Doc about the provider field
+````
+:::::

sphinxdocs/docs/starlark-docgen.md

@@ -85,7 +85,8 @@ using the {rst:directive}`bzl:typedef` directive and puts all the struct's field
 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 `Square` object with a `area()` method would look like:
+For example, a the Starlark implemenation of a `Square` object with a `area()`
+method would look like:
 
 ```
 
@@ -133,16 +134,19 @@ A square with fixed size
 :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
 

sphinxdocs/src/sphinx_bzl/bzl.py

@@ -825,6 +825,7 @@ class _BzlTypedef(_BzlObject):
 
     A typedef describes objects with well known attributes.
 
+    `````
     ::::{bzl:typedef} Square
 
     :::{bzl:field} width
@@ -837,6 +838,7 @@ class _BzlTypedef(_BzlObject):
     :::{bzl:function} area()
     :::
     ::::
+    `````
     """