search

bazelbuild / stardoc

Stardoc: Starlark Documentation Generator
Apache License 2.0
108 stars 45 forks source link

Expose the `out` File in a provider #82

Open UebelAndre opened 3 years ago

UebelAndre commented 3 years ago

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?

brandjon commented 3 years ago

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 commented 3 years ago

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