bazelbuild / bazelbuild/stardoc

Add a page layout template with parsed directives in comments

Open
#23 0 comments 0 reactions 0 assignees View on GitHub
P4 type: feature request
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.