Use stardoc to automatically generate README.md #32
Conversation
benradf
force-pushed
the
autogen-stardoc
branch
from
f91a395
to
1cbedcf
Compare
There was a problem hiding this comment.
Thank you, that looks good!
One comment about the shape of the function docstrings.
As written in an inline comment, as a next step this can be used to extend the README to include API docs like function parameters and also document features that are currently undocumented in the README, e.g. see #23 (comment).
| @@ -347,14 +347,72 @@ _sh_posix_config = repository_rule( | |||
| ) | |||
|
|
|||
| def sh_posix_configure(name = "local_posix_config", register = True): | |||
| """Autodetect local Unix commands. | |||
| """## Usage | |||
There was a problem hiding this comment.
It's a bit unusual to have function or rule docstrings start with a heading like that.
rules_nixpkgs generates such headings by placing them into the module docstring, e.g. here. Could the same work here, too?
Relatedly, rules_nixpkgs uses templates that also generate parameter lists and the like, e.g. here. That would be a nice improvement over the current README of rules_sh.
That said, I'm happy to leave these for a follow-up PR and already merge this one as is. After all this one achieves the goal of generating the current README from Startdoc.
There was a problem hiding this comment.
Sounds good - I'll look into this tomorrow if I have time. I've created #33 to track it. Thanks for approving the PR.
This change adds targets for automatically generating
README.mdfrom stardoc docstrings as requested in #24.README.mdis up-to-date:bazel test //sh/docs:check-readmeREADME.mdif necessary:bazel run //sh/docs:update-readmeDue to a stardoc / bzlmod issue these targets are not run for "modules" pipelines on CI. They are also disabled for Windows because it fails to parse the docstring for some reason (I'm guessing line ending differences):