Separate generating documentation per module #202
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
fricklerhandwerk
force-pushed
the
issue-197
branch
7 times, most recently
from
9573bec to
768df13
Compare
fricklerhandwerk
force-pushed
the
issue-197
branch
2 times, most recently
from
28cc36e to
bb267c9
Compare
aherrmann
reviewed
Mar 22, 2022
fricklerhandwerk
force-pushed
the
issue-197
branch
from
08a52c6 to
2b49081
Compare
rename its internal source collection `nixpkgs`.
ideally we would already operate within `bzlmod` here, but we do not even have all dependencies present in [BCR][bcr] as of today. it is another can of worms detailed in [#181][181]. here we just isolate `rules_nixpkgs_core` as a proper self-contained repository as far as possible. [bcr]: https://github.com/bazelbuild/bazel-central-registry/tree/92bb87fc41d549a47297af67c4135111308b7b03 [181]: #181
remove unused README templates, as rendering is now self-contained. motivation: `docs` package is for external use by other modules. modules will have their own documentation rules, and we do not want to introduce artificial packages in each just for that. this change requires clearly distinguishing between the transient, generated file and the source file that we create with `copy_files`. that was not necessary before, as the transient and source files lived in different directories. since Bazel does not have a way to express this distinction, encode the distinction with (arbitrarily) differing file names. for now decide against encoding this in the rules, as the mechanism would be obfuscated.
preserve existing helpers in case we ever need to do more file copying in a similar fashion.
also a few cleanups to clarify internal dependencies.
This reverts commit 3754098. taking a different approach to render module documentation...
invocations `bazel run` within `toolchains/cc` for some reason are not idempotent (at least on Darwin) and on the second run throw this error: rules_nixpkgs/toolchains/cc/BUILD.bazel:38:9: Generating proto for Starlark doc for __README.md failed: missing input file '//:bazel-out/_tmp/actions/stderr-12' run `bazel clean` to avoid this. it may also be possible to work around this with adding to `.bazelignore`.
these files are already made accessible by `file_group("srcs")`.
letting Bazel ignores them prevents issues with idempotency of builds note that `.bazelignore` has to be a proper file, symlinks do not behave as expected.
otherwise the file must already be present to do the build
render documentation for original workspace based on separate modules, only using `stardoc` templates. this lets us get rid of additional template files and a lot of noisy helper code. add rule aliases for backwards compatibility.
this removes the requirement of having the generated file already present in the source tree. otherwise, if it does not exist, `cp` will fail with "Permission denied". note that we had to explicitly make use of `POSIX_SH` provided by the build itself, as `--no-preserve` is unique to `coreutils` and not available on e.g. BSD or Darwin.
this is to have as little repetition as currently possible, and while it looks ugly, it is intended to be only temporary until the sub-repositories are proper `bzlmod` modules. `WORKSPACE`-based documentation is still rendered the same way, and will not be changed, to keep compatibility. at some point, once we have modules, we will remove the temporary sub-module `WORKSPACE` files, and the top level will import their local dependencies as packages again.
lumping these together forced strict toolchain-specific dependencies on all users, while these are normally only needed for development (in this case, rendering documentation only).
do not generate for Go as that would require aliasing the Go library, which in turn would introduce a strict dependency on `@io_bazel_rules_go`. instead link to the existing module `README.md`.
fricklerhandwerk
force-pushed
the
issue-197
branch
from
2b49081 to
a38f803
Compare
|
@aherrmann Fixed all the comments and issues. |
aherrmann
reviewed
Mar 25, 2022
There was a problem hiding this comment.
Good work, this looks great!
Only one comment: #202 (comment)
aherrmann
approved these changes
Mar 25, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
closes #197
this is a huge diff, unfortunately. most of the noise comes from unavoidable redundancy in
WORKSPACEfiles per module for backwards compatibility, and the rendered documentation checked into version control. tried to keep a narrative in commit history. it probably makes sense to just look at the result, possibly excluding the last commit, which only updates theREADMEs. to inspect motivation per line one has to resort togit blame, sorry for the inconvenience.key takeaways:
README.mdrenders from the same data