docs: allow manual edits to generated docs#1478
Conversation
9469f48 to
9018777
Compare
e3d30db to
8fd7109
Compare
Before this PR the documentation used to be next to the source. With the adjustment of how we generate the markdown files, we can keep user friendly documentation in markdown and leave the API docs in the `.bzl` source code. This improve the maintainability of the docs as editors have better support for editing markdown in markdown files as opposed to docstrings within `.bzl` files. NOTE: This is implemented via a genrule in order to not expose a macro as an consumable API. Summary: - chore: mark the documentation files as non-generated - chore: chmod -x markdown files - feat: adjust doc generation to retain headers and modify the header - refactor: move the docs from .bzl and improve them Work towards bazel-contrib#1332
db7baa3 to
edc9e98
Compare
|
You sure you don't want to just bite the bullet and setup readthedocs? It lets us create rich docs, gives us versioned docs, integrates with PRs, is locally runnable/previewable, and sphinx's plugin system gives us a lot of future options :). I've been pretty impressed and happy with it. I've already reserved the project name on rtd (https://readthedocs.org/projects/rules-python/) |
| ], | ||
| outs = [k + ".md_"], | ||
| cmd = ";".join([ | ||
| "sed -En '/{comment_bait}/q;p' <$(location {first}) > $@", |
There was a problem hiding this comment.
"comment_bait"? I'm unfamiliar with this term -- what does it mean by "bait" ?
There was a problem hiding this comment.
I wanted to have a word to express an idea of some phrase that is used to match when doing text processing. Something that is only there to be replaced later.
|
I agree with the long term solution being RTD. I'll create a separate issue. If anyone would like an easy way to contribute to open source, that would be a good first task. That said, I'll merge this one for now. |
Before this PR the documentation used to be next to the source. With
the adjustment of how we generate the markdown files, we can keep user
friendly documentation in markdown and leave the API docs in the
.bzlsource code. This improve the maintainability of the docs as editors
have better support for editing markdown in markdown files as opposed to
docstrings within
.bzlfiles.NOTE: This is implemented via a genrule in order to not expose a macro as an
consumable API.
Summary:
Work towards #1332