bazelbuild / bazelbuild/stardoc

Example section no longer recognized in docstrings

Open
#47 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

Skydoc recognizes special sections in docstrings such as `Args:` and `Example:`. Stardoc still recognizes `Args:` but no longer recognizes `Example:`. Given the following docstring:
```bzl
def some_function(name, arg):
"""This is some function.

Example:
Here is an example:

```bzl
foo = some_function("name", "arg")
```

Args:
name: The name.
arg: The argument.
"""
```
I would expect output containing markdown along the lines of

### Examples
Here is an example:
```bzl
foo = some_function("name", "arg")
```
### Attributes
...

However, Stardoc no longer generates a section (or a proto entry) for examples.

We have several such examples in the `rules_haskell` documentation ([source](https://github.com/tweag/rules_haskell/blob/v0.11/haskell/defs.bzl#L348), [rendered](https://release.api.haskell.build/haskell/defs.html#haskell_toolchain_library_examples)).

A workaround is to use level 3 headings (`###`) in the docstring directly. However, this makes the `Example` and `Args` sections inconsistent in the source docstring.

I did not compare other special sections, e.g. `Returns:`. However, looking at the [proto](https://github.com/bazelbuild/stardoc/blob/master/stardoc/proto/stardoc_output.proto) it seems that `Args:` is the only section that Stardoc recognizes.

How should users migrating from Skydoc to Stardoc handle such sections? Could support for further sections be added to Stardoc?

Contributor guide

Open the contributing guide

Research direction

Start with stardoc/proto/stardoc_output.proto and the section handling for Args:, then trace how recognized docstring sections reach generated Markdown. Compare the supplied Example docstring with the expected output. Done means example content is represented in the proto and rendered as an Examples section, with coverage for the shown input.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.