search

bazelbuild / rules_pkg

Bazel rules for creating packages of many types (zip, tar, deb, rpm, ...)
Apache License 2.0
214 stars 167 forks source link

a way to consolidate documentation changes #800

Open jmhodges opened 6 months ago

jmhodges commented 6 months ago

In trying to figure out the current status of the strip_prefix = "." bugs (#354, #82), I noticed a documentation PR that adjusted the docs for strip_prefix in v0.8.0 but didn't do so in for v0.9.1 (PR in question). See the documentation site and specifically the v0.9.1 and v0.8.0 versions of the pkg_tar docs.

It'd be nice to have an automatic way for docs to get carried into new versions automatically. Or to generate docs from the skylark code itself.

(I'm not sure what the latest state of skylark-to-markdown generation is or anything. I'm just a normal user who was confused if 0.9.1 had changed the behavior of strip_prefix or something)

(Also, I got those documentation pages from the "Documentation" link the README.)

aiuto commented 6 months ago

The docs should be generated from the source. I'm not sure why the change to tar.bzl did not propagate through to the 0.9.1 generated docs. In #801 it seems to be there. That was built simply by running the doc generator.

I'm not sure what the latest state of skylark-to-markdown generation is or anything

Stardoc is missing a few critical pieces, so I post process around to those to produce rules_pkg docs. It's a bit of a hack, and always lower priority than the core work of the package.