No docs for 0.9 versions #716
Comments
|
It's manual. I have not found the time payoff in automating it robustly. Doing 'latest' is easy, or not, depending on what we consider latest to mean. The versioned releases are their own question. I don't think having a distinct text for every release adds value. It encourages web search to find obsolete docs. OTOH, some people do want the docs for the specific thing they are using. |
|
I'd like to fix this permanently to reduce the maintenance burden in this repo. I have the time to automate it robustly. https://github.com/bazel-contrib/rules-template/tree/main/docs is the pattern used in a dozen rulesets. It's just a regular test that asserts the markdown at HEAD always matches the stardoc output at HEAD. Every PR updates the docs. Can I send you a PR for this, rather than a special effort for 0.9? I think we should cut releases regularly, but the more effort required, the less likely we are to find the time to perform them. |
|
How does this account for the post processing pipeline that assembles the
unified doc set and fixes the bad stardoc generation.
…On Tue, Aug 22, 2023 at 10:38 AM Alex Eagle ***@***.***> wrote:
I'd like to fix this permanently to reduce the maintenance burden in this
repo. I have the time to automate it robustly.
https://github.com/bazel-contrib/rules-template/tree/main/docs is the
pattern used in a dozen rulesets. It's just a regular test that asserts the
markdown at HEAD always matches the stardoc output at HEAD. Every PR
updates the docs.
Users can use the GitHub UI to read docs at any tag they choose.
Can I send you a PR for this, rather than a special effort for 0.9? I
think we should cut releases regularly, but the more effort required, the
less likely we are to find the time to perform them.
—
Reply to this email directly, view it on GitHub
<#716 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAXHHHH4I3I2THEDM7BJL43XWS77ZANCNFSM6AAAAAA2JSIFDI>
.
You are receiving this because you commented.Message ID:
***@***.***>
|
|
There's no post-processing. We can make a unified experience with a table of contents like https://github.com/aspect-build/bazel-lib#public-api Would you like a PR to see what this will look like? |
|
I'm not going to fork stardoc. I will keep nudging them to fix it instead.
How about if the update rule from the template were modified to take two
parameters
- the target which generates the doc file(s)
- the page(s) to place them at.
That would incorporate any doc generation scheme, stardoc or not.
…On Tue, Aug 22, 2023 at 1:24 PM Alex Eagle ***@***.***> wrote:
There's no post-processing. We can make a unified experience with a table
of contents like https://github.com/aspect-build/bazel-lib#public-api
and for bad stardoc generation, I either fix that upstream or use a fork
of stardoc with some of my fixes.
Would you like a PR to see what this will look like?
—
Reply to this email directly, view it on GitHub
<#716 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAXHHHEUUIA62YJUUKCBMWTXWTTLHANCNFSM6AAAAAA2JSIFDI>
.
You are receiving this because you commented.Message ID:
***@***.***>
|
|
Can you point to the stardoc bug? I wonder if it's the dedenting issue that caused me to fork but was recently fixed. |
|
bazelbuild/stardoc#120 There are probably others. The non-generated text that I need could be put in the silverlight template. |
|
Thanks, I replied to all three of those issues with the techniques we use for Aspect's rulesets. IMHO we do a really nice job providing high-quality, readable API docs for users, without having to invent any mechanisms that live in the ruleset repo to workaround stardoc issues. If you have any time, I'd love to spend 15min walking through that with you. |
|
There are docs for 0.9 now, so this is solved as reported. I get the sense that you're not really interested in automating the docs process and don't want to make a big deal out of it. |
|
There is some push from internal security teams to redo the release process
in specific ways. I'm in negotiation with them about their requests
…On Sun, Oct 1, 2023, 5:37 PM Alex Eagle ***@***.***> wrote:
Closed #716 <#716> as
completed.
—
Reply to this email directly, view it on GitHub
<#716 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAXHHHGVUCQJDW2S5UZQDEDX5GEZZANCNFSM6AAAAAA2JSIFDI>
.
You are receiving this because you commented.Message ID:
***@***.***>
|
|
Could I get a contact info from someone there? I'd like to get the Bazel-contrib rules-template that all the community rules are based on |
|
+Tobias Werth ***@***.***>
The best contact for Bazel policy is Tobi, or myself if strictly about
rules_license or rules_pkg.
…On Mon, Oct 2, 2023 at 3:33 AM Alex Eagle ***@***.***> wrote:
Could I get a contact info from someone there? I'd like to get the
Bazel-contrib rules-template that all the community rules are based on
—
Reply to this email directly, view it on GitHub
<#716 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAXHHHHQWOB3ZTLTWLON5Y3X5IKYNANCNFSM6AAAAAA2JSIFDI>
.
You are receiving this because you commented.Message ID:
***@***.***>
|
|
Probably better to take this to a dedicated issue: bazel-contrib/rules-template#99 |
https://github.com/bazelbuild/rules_pkg/blob/main/docs/latest.md documents 0.8.2
Is this a manual process on releases?
The text was updated successfully, but these errors were encountered: