Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Expose the out File in a provider #82

Open
UebelAndre opened this issue Dec 18, 2020 · 2 comments
Open

Expose the out File in a provider #82

UebelAndre opened this issue Dec 18, 2020 · 2 comments
Labels
P4 type: feature request

Comments

@UebelAndre
Copy link

I've noticed on one of the projects I work on which uses stardoc that users will update rendered output files to change documentation and commit that back only to have someone else come by and re-run the stardoc target and delete all the changes made in the previous commit. I'd like to be able to test that subsequent runs of the stardoc target match what's currently committed but there doesn't seem to be any provider being returned by the rule with which to perform this test. Is this something that needs to change in upstream Bazel or is it sufficient to update it in this repo?
@UebelAndre UebelAndre changed the title Allow the stardoc rule to return a provider containg the generated markdown files Allow the stardoc rule to return a provider containing the generated markdown files Dec 18, 2020
@brandjon
Copy link
Member

I imagine you can write a macro to produce golden tests, which you instantiate once for each stardoc target. The golden test would take in the checked-in documentation file as the golden input, and the out attribute of the stardoc target as the file under test, and simply fail if they differ.

You can also wrap all your uses of the stardoc rule with this macro, so you implicitly get a test without having to write any extra BUILD file content.

Perhaps there might be other reasons to expose the out file in a provider, but I can't think of them at the moment.

@brandjon brandjon changed the title Allow the stardoc rule to return a provider containing the generated markdown files Expose the out File in a provider Jan 12, 2021
@brandjon
Copy link
Member

Note that the test you're describing is the subject of FR #16.

jbdalido pushed a commit to jbdalido/multirun that referenced this issue Jan 15, 2024
feat(buildozer): add documentation for the buildozer rule
85196ad 
This patch introduces Stardoc to this workspace, and adds a series of
targets that ultimately generate an output containing the rule reference
for `//buildozer:def.bzl%_buildozer`, stripping the underscore for a
nicer user experience.

It's difficult to say whether or not this is the best way to go about
this, as what we're really doing is generating documentation for a
private symbol (`_buildozer`), and then defining a genrule to invoke
`sed` and remove the offending underscore. This rule is private because
we expose the rule through a public macro `buildozer`, however, stardoc
is incapable of generating complete documentation for the macro
(including attributes from the proxied rule, which is what we'd want for
friendly documentation -- see bazelbuild/stardoc#82).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
P4 type: feature request
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@brandjon @UebelAndre