Generate API documentation using Stardoc#139
Merged
mergify[bot] merged 14 commits intomasterfrom Nov 30, 2020
Merged
Conversation
Profpatsch
approved these changes
Sep 9, 2020
Contributor
Profpatsch
left a comment
Profpatsch
left a comment
There was a problem hiding this comment.
I think you still need to add the check script to CI.
Other than that, LGTM.
|
|
||
| %nixpkgs% | ||
|
|
||
| %toolchains_go% |
Contributor
There was a problem hiding this comment.
slight nitpick: if you use {{}} instead, it’s a bit more visible
Contributor
|
Nvm, the test is automatically picked up by |
Some functionality was only documented in the README but not in the docstrings of the corresponding rules. This adds such missing documentation to the docstrings.
These `bzl_library` targets are required to build Stardoc documentation for `//nixpkgs:toolchains/go.bzl` which loads `rules_go`.
We use custom templates to match the header levels with the README.
This substitutes the Stardoc generated API documentation into the README template and defines automation to update the project README file and test that it is up-to-date on CI.
The stardoc templates applied `htmlEscape` when this is not necessary for markdown output. As a result `<>` characters that appeared within code snippets where translated to html entities which would then render as `<`/`>`.
A PR fixing the issue of unexposed bzl_library targets for rules_go has been fixed on rules_go master by now.
To avoid the following type of error on CI ``` ERROR: /var/lib/buildkite-agent-agent/.cache/bazel/_bazel_buildkite-agent-agent/3cdbb0e8c4afb0ca9493ed6bd8d63bbb/external/bazel_tools/tools/jdk/BUILD:346:14: Action external/bazel_tools/tools/jdk/platformclasspath_classes/DumpPlatformClassPath.class failed (Exit 1) javac failed: error executing command external/remotejdk11_linux/bin/javac -source 8 -target 8 -Xlint:-options -cp external/remotejdk11_linux/lib/tools.jar -d bazel-out/host/bin/external/bazel_tools/tools/jdk/platformclasspath_classes ... (remaining 1 argument(s) skipped) ```
aherrmann
commented
Nov 30, 2020
Contributor
Author
aherrmann
left a comment
aherrmann
left a comment
There was a problem hiding this comment.
- Rebased this PR on latest master.
- Update the README to include
nixpkgs_cc_configure_deprecated. - The docstring of the new
nixpkgs_cc_configuretriggered an issue with the stardoc templates which applied html escape which is not necessary for markdown output. This caused verbatim entities like<to show up in the rendered README. This is fixed by not applying html escape. - Updated rules_go which now includes the necessary
bzl_librarytargets upstream: bazel-contrib/rules_go#2621 . - The use of Starlark triggered issues with the JDK on NixOS on CI. These are fixed by updating nixpkgs to include NixOS/nixpkgs#98611 and including a JDK in the Nix shell.
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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 #138
stardoctargets fornixpkgs/nixpkgs.bzlandnixpkgs/toolchains/go.bzl.