-
Notifications
You must be signed in to change notification settings - Fork 512
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
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 bazelbuild#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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"comment_bait"? I'm unfamiliar with this term -- what does it mean by "bait" ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
.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:
Work towards #1332