stardoc
stardoc copied to clipboard
bazelbuild
Support getting a page preamble
Looks like the markdown generated starts out with a ## [NAME] for everything thing documented, but there doesn't seem to be a way to get any preamble on to the page, especially a # [TITLE] since that likely will be used by some system.
The easiest might be to just support a title on the rule to insert this vs. and then let something like bazelbuild/skydoc#159 end up providing any content after the title before the listing of symbols.
The file-level docstring would provide an overview, but likely wouldn't map the the # title directive well.
Could you elaborate a little bit on this feature request? We have:
Support module docstrings: https://github.com/bazelbuild/stardoc/issues/25 And we now support custom output templates
Is this feature request for processing some sort of top-level header (comment) metadata? Could you provide an example of what you'd like? :)
Most module docstrings seem like that are more just descriptions (for example https://github.com/bazelbuild/bazel-skylib/blob/master/lib/collections.bzl#L15), so it didn't really seem like a logical place to insert the documentation page title, etc. So having a way to insert some preamble that wasn't in the bzl file seemed like it might make sense.
But with custom templates, this might not apply any more.
If I'm reading the java right, I think the template engine extracts the module doc string, but the default template for a file doesn't attempt to make use of it.
