bazelbuild / bazelbuild/stardoc
Add a page layout template with parsed directives in comments
- Dominant language
- Java
- Stars
- 118
- Forks
- 51
- PR merge metrics
- No merged PRs in 30d
Description
The Asylo project is interested in producing its .bzl file documentation with stardoc. Currently [it is hand-written](https://asylo.dev/docs/reference/api/bazel/sgx_deps.bzl.v1.html) and therefore [out of date](https://github.com/google/asylo/blob/master/asylo/bazel/sgx_deps.bzl)
We want to be able to drive more of the page layout ourselves. Right now there are templates for the individual types of Starlark constructs, but here is no template for the overall page layout.
The layout in stardoc is alphabetical order only, with no user-provided header, footer, or ability to add descriptive interludes. This makes documentation of concepts that are shared amongst documented constructs hard.
What I'd like to see is a page template that can reference variables that are declared in parsed comments, and metadata attached to various documentable constructs.
Say we have a .bzl file:
```
# stardoc:block{my_variable}
# content
# more content
def macro1(arg):
"""Documentation"""
stuff()
# stardoc:let{other_variable}{4}
# stardoc:meta:group{top_group}
a = rule(implementation = _impl; attrs = {...})
```
The tag stardoc:block binds the content of the rest of the comment to the declared variable. That variable can be referenced in the page template for the stardoc target. This could be in a docInfo object as either a field (`docInfo.my_variable`) or as a map lookup (`docInfo.var["my_variable"]`); I don't particularly care, so whichever is easier.
Then we have a page.vm template file:
```
---
${docInfo.my_variable}
---
#foreach ($construct in $docInfo.getSortedConstructsByGroup("top_group"))
${construct.render()}
#end
#foreach ($construct in $docInfo.getSortedConstructs())
#if (!$construct.in_group("top_group"))
${construct.render()}
#end
#end
```
I'm sure metadata is a whole different thing than just binding variables to values. So I'm okay with this feature request getting split into the page template with simple variables and page template with attached-metadata separate feature requests.
Right now, the Asylo project does post-processing on the md files we generate given the supposed source .bzl file, and tosses in a header that's defined by a specially-tagged comment block. We'd really like to better group our documented constructs to talk about rules here, providers there, or "this bunch of conceptually similar things" and that. An added bonus with using templates and stardoc is that unbound variables could cause warnings, and we could catch missing Jekyll metadata (in the ---/--- block).
Contributor guide
Research direction
Start with the .bzl example and the proposed page.vm template, then identify Stardoc's existing construct-template and docInfo entry points. Define the page-level template scope around parsed comment variables and construct metadata or grouping. Done means a page template can render the requested variables and grouped constructs, with unbound variables producing warnings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100