| Age | Commit message (Collapse) | Author |
|---|
|
Original change: https://android-review.googlesource.com/c/platform/external/stardoc/+/2924556
Change-Id: Icd7f3a65eba0eaf2edac7e9ee6af56eb54321c99
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
|
|
This reverts commit 16b44b4e060da38bf5613220593fc48350a0aa80.
Reason for revert: change breaks kleaf_docs build and there are no easy forward fix that cuts the protobuf dependency, which requires a working toolchain that compiles C++ code correctly.
Bug: 321898888
Change-Id: I845e6c2c874d6b7ec1d403b9482f63c7996815c0
|
|
Original change: https://android-review.googlesource.com/c/platform/external/stardoc/+/2863358
Change-Id: If97afa3f90932aa17926fb6bd874cdee60a34ba4
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
|
|
Bug: 276493276
Change-Id: Ia35937702bbf7634a760801e6cf0c3d28d4436de
|
|
... and fix Windows CI failure (see https://github.com/bazelbuild/continuous-integration/issues/1012)
|
|
--incompatible_disable_starlark_host_transitions (#179)
And to make sure we stay unbroken, add the flag to our ci config - which on Windows requires setting `BAZELISK_SHUTDOWN=1` to work around https://github.com/bazelbuild/continuous-integration/issues/1012
Fixes #145
|
|
|
|
Surprisingly, the release tarballs of Stardoc 0.6 almost works with Bazel 5 - except for two usages of the dict union operator.
Temporarily (until ~ Stardoc 0.7 release, which will require Bazel 7) replace the union operator with dict.update; it doesn't affect readability much.
Fixes #175
|
|
(#176)
Since we no longer have a single source of truth for maven artifacts, we need a consistency test. Use some old-school sed to extract the STARDOC_MAVEN_ARTIFACTS list from MODULE.bazel and deps.bzl, and add a test to ensure they are consistent. And - for good measure - add a similar test to ensure the version number in version.bzl and MODULE.bazel is consistent too.
Fixes #174
|
|
|
|
supported (#171)
|
|
Since we are building the renderer from source and using rules_jvm_external to pull in Maven deps, the WORKSPACE setup for a user of Stardoc is now significantly more complicated; the user will now need to do the multi-step rules_jvm_external initialization and maven_install.
For convenience, let's wrap maven_install in a macro - and finally split out the legacy-test-only maven deps into their own .json file and repo.
Update stardoc_repositories to pull in all the new deps we need to build Java code.
Update maintainer guide.
|
|
We want https://github.com/bazelbuild/bazel/commit/b71b2df2b22e052f8540a23051b589c6ef870d0a in order to dedent and trim doc strings from all sources (not just functions, but also rules, providers, attributes, etc.).
|
|
Most Stardoc users are probably documenting their rules for users from other repos - so we ought to render labels in the repo being documented with the repo name.
|
|
it properly (#167)
In Markdown table cells, apply HTML escaping only to code blocks, and apply it properly
Since #161 removed HTML escaping for defaults and function docstrings, we should do the same for attribute and param docs in table cells.
The only limitations Markdown places on table cells are:
* no pipe characters (they must be escaped with a backslash)
* no newlines (they must be transformed into `<br>` or an HTML entity)
The latter restriction makes it impossible to have a fenced code block inside a table cell.
Therefore:
* we do not escape HTML or Markdown markup outside a fenced code block
* we keep existing logic for escaping newlines outside a fenced code block
* we fix fence detection (e.g. allowing more than 3 fence characters to support embedded code blocks in code blocks, allowing tildes as fence characters, properly handling language names, etc.);
* in code block content, we escape HTML, and we escape newlines as HTML entities (since `<br>` does not work in a `<pre><code>` block) - finally fixing code block newlines in table cells.
This is a followup to #161.
Partially addresses #118
|
|
|
|
* When available (i.e. in Bazel 7, or in current development Bazel at HEAD), try use the `starlark_doc_extract` native rule for doc extraction instead of the legacy pre-built extraction jar. This behavior can be disabled by passing `use_starlark_doc_extract = False` to the `stardoc` macro.
* Add templates and markdown rendering functionality for repository rule and module extension info protos (which are output by `starlark_doc_extract`).
* Temporary wart: for module extensions, by default we would want the summary blurb to look something like
```
my_ext = use_extension("@my_local_repo//some:file.bzl", "my_ext")
my_ext.tag(foo, bar)
```
but alas, we don't have a good way to get the name of the local repo from Starlark when bzlmod is enabled.
* ... and of course, update tests. Which means in some cases, we have to fork the golden files into current (i.e. `starlark_doc_extract`-enabled) and legacy flavors.
Fixes #69
Fixes #76
Fixes #81
Fixes #123
|
|
Reverts #133 so that HTML escaping is not applied to Markdown. Instead, Markdown content such as docstrings can use HTML formatting and escape angle brackets with backslashes, HTML entities or inline code segments. Default values are embedded in inline code segments instead of `<code>` tags, which does not require escaping.
As a result, docstrings behave just like regular Markdown contexts while default values are rendered without smart quotes and can contain both `<` and `` ` `` without causing escaping issues.
Also includes tests based on #138.
Fixes #137
Closes #138
Fixes #142
Closes #143
Requires https://github.com/bazelbuild/bazel/pull/18867
Co-authored-by: Adam Azarchs <adam.azarchs@10xgenomics.com>
|
|
|
|
for templating (#163)
Internal tooling complains about any new Velocity usage
|
|
Moving from https://github.com/bazelbuild/bazel/tree/3d2604806a9747f317c5b560bbf89cdc1be033ba
* src/main/java/com/google/devtools/build/skydoc/renderer/RendererOptions.java and src/main/java/com/google/devtools/build/skydoc/renderer/RendererMain.java have been changed to use JCommander instead of Bazel's options library for command-line arg parsing. All other .java files have been copied from Bazel without any changes and without any file/directory renames.
* integration tests from src/test/java/com/google/devtools/build/skydoc/testdata in Bazel have been merged into tests/testdata in Stardoc where appropriate (filter_rules_test, function_basic_test, function_wrap_multiple_lines_test, multi_level_namespace_test_with_allowlist, provider_basic_test, pure_markdown_template_test, repo_rules_test)
* updated Stardoc's deps and to allow building the renderer. In particular, we now are forced to depend on rules_jvm_external unconditionally, even in releases.
* removed renderer_binary.jar
|
|
(#159)
I forgot to bump the rules_java dep in MODULE.bazel.
We ought to have a consistency check for this...
|
|
Update rules_java dep to fix "No matching toolchains" errors with Bazel at HEAD, i.e. after https://github.com/bazelbuild/bazel/commit/975866a3e09212766bd353a90a8c42efe91d53ab
This error warrants an immediate release because it affects users of Stardoc releases, not just Stardoc itself.
See https://buildkite.com/bazel/bazel-skylib/builds/2692#0188728a-5bf4-4bb0-8d3a-6bc726a54f26 for an example failure.
|
|
Our internal system complains about the lack of license header in a .bzl file.
|
|
In preparation for switching to starlark_doc_extract, we need to fix Stardoc tests to use .bzl files that can really be loaded by Bazel. This means:
* getting rid of misuses of aspect api
* getting rid of old Android and Java symbols
* getting rid of generated_bzl_test entirely, since Bazel cannot load dynamically generated .bzl modules.
Also fix update-stardoc-tests.sh script - we need to ignore the _stardoc java_binary outputs introduced by #141.
|
|
Needed for a bzlmod-compatible release
|
|
Required updating the pinned Bazel commit and importing a patch to rules_jvm_external from the Bazel source tree.
Fixes #110
|
|
|
|
Input .bzl files are turned into runfiles of a custom Stardoc binary, which allows reusing the Java runfiles library to load the files while taking repository mappings into account.
|
|
|
|
Needed for bureaucratic compliance reasons.
|
|
|
|
|
|
Original change: https://android-review.googlesource.com/c/platform/external/stardoc/+/2292919
Change-Id: I8eb29a4c893987eecf3f325a775055978e13d0f6
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
|
|
290c4708ab
Original change: https://android-review.googlesource.com/c/platform/external/stardoc/+/2291529
Change-Id: Id2757e205e84b3885ecac7dc5151460a8273ba59
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
|
|
Original change: https://android-review.googlesource.com/c/platform/external/stardoc/+/2292919
Change-Id: I68ee3b25732db916c2080fb07df957f57e73cc51
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
|
|
Original change: https://android-review.googlesource.com/c/platform/external/stardoc/+/2291529
Change-Id: I90d0862db184d09e26890523695de4751d6d1c77
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
|
|
Original change: https://android-review.googlesource.com/c/platform/external/stardoc/+/2292919
Change-Id: I93970b877221089ca41995a376e0b06b0d9ec9c0
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
|
|
Original change: https://android-review.googlesource.com/c/platform/external/stardoc/+/2291529
Change-Id: I3624bb83c47ee17ca1ce050718aacab2d3742594
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
|
|
Test: TH
Change-Id: Ic0a605e5718d4c9bd8079d919a5b23f1ca4854c5
Signed-off-by: Yifan Hong <elsk@google.com>
|
|
Change-Id: Ia38b870c188683b015b7f56a2d1bb0defe408c50
Signed-off-by: Yifan Hong <elsk@google.com>
|
|
Resolves config_setting visibility failures from https://github.com/bazelbuild/bazel/issues/12933:
```
ERROR: /var/lib/buildkite-agent/builds/bk-docker-zr2k/bazel-downstream-projects/stardoc/distro/BUILD:33:8: in pkg_tar_impl rule //distro:distro_bins: target '@rules_pkg//pkg/private:private_stamp_detect' is not visible from target '//distro:distro_bins'. Check the visibility declaration of the former target if you think the dependency is legitimate
```
See https://buildkite.com/bazel/bazelisk-plus-incompatible-flags/builds/1320#018435e1-7429-4329-808a-731599f24623.
|
|
* Expose stardoc() output files as runfiles
There's currently a nuisance with the `stardoc()` rule that presents
itself in `rules_python`:
$ git clone https://github.com/bazelbuild/rules_python.git
$ cd rules_python
$ git checkout d314e96aaab18f60df50400d61214f7c1d71b8e6
$ bazel run //docs:update
cp: cannot stat 'bazel-bin/docs/packaging.md_': No such file or directory
cp: cannot stat 'bazel-bin/docs/pip.md_': No such file or directory
cp: cannot stat 'bazel-bin/docs/pip_repository.md_': No such file or directory
cp: cannot stat 'bazel-bin/docs/python.md_': No such file or directory
A sample of the targets involved look like so:
$ bazel cquery --output=build //docs:update + //docs:packaging-docs
INFO: Invocation ID: 5fd7a652-0b0d-4827-98f5-c345b38b2178
INFO: Analyzed 2 targets (0 packages loaded, 0 targets configured).
INFO: Found 2 targets...
# /home/jenkins/repos/rules_python/docs/BUILD:153:10
sh_binary(
name = "update",
target_compatible_with = [],
data = ["//docs:packaging-docs", "//docs:pip-docs", "//docs:pip-repository", "//docs:core-docs"],
srcs = ["//docs:update.sh"],
)
# Rule update instantiated at (most recent call last):
# /home/jenkins/repos/rules_python/docs/BUILD:153:10 in <toplevel>
# /home/jenkins/repos/rules_python/docs/BUILD:121:8
stardoc(
name = "packaging-docs",
target_compatible_with = [],
input = "//python:packaging.bzl",
deps = ["//docs:packaging_bzl"],
out = "//docs:packaging.md_",
)
# Rule packaging-docs instantiated at (most recent call last):
# /home/jenkins/repos/rules_python/docs/BUILD:121:8 in <toplevel>
# Rule stardoc defined at (most recent call last):
# /bazel-cache/phil/bazel/_bazel_phil/adc54b5b09500e464f8a73095f3bd8e3/external/io_bazel_stardoc/stardoc/stardoc.bzl:110:15 in <toplevel>
The `update` target could instead reference the `*.md_` files directly
instead of referencing the `stardoc()` targets. But it's not obvious
that this is the desired work flow. It feels like users should be able
to depend on the `stardoc()` target instead of its predeclared output.
This patch fixes this by adding the predeclared outputs to the
target's runfiles. That lets the `rules_python` doc update target work
again.
$ bazel run //docs:update
'bazel-bin/docs/packaging.md_' -> 'docs/packaging.md'
'bazel-bin/docs/pip.md_' -> 'docs/pip.md'
'bazel-bin/docs/pip_repository.md_' -> 'docs/pip_repository.md'
'bazel-bin/docs/python.md_' -> 'docs/python.md'
|
|
|
|
Needed to fix LabelParser to not crash on @@ syntax.
Unbreaks Skylib; see https://buildkite.com/bazel/bazel-skylib/builds/2346#01837d20-1ec8-4e50-937c-7f3dbefed313
|
|
|
|
Specifically, we were failing to escape <brackets> in:
* module docstrings;
* function docstrings, including args, returns, and deprecated sections;
* provider docs & provider field default values;
* rule docs & rule attr default values;
* aspect docs & aspect attr default values.
(We had also failed to format rule and aspect attr default values in `<code>` tags.)
Tests have been updated accordingly.
Fixes #132.
|
|
See #130.
|
|
If you have a bzl file that contains
`@bazel_tools//tools/cpp/toolchain_utils.bzl`, after this commit
https://github.com/bazelbuild/bazel/commit/95f0135fbac934be696676f37e0285b2d311603a
stardoc stopped working because it didn't know about this API, leading
to this crash https://buildkite.com/bazel/rules-apple-darwin/builds/5829#0181f96c-ff6c-449e-936e-c32530bd3360
I assume this is because some of the stardoc internals pulls in the
older version of `ConfigStarlarkCommonApi.java`. This bumps the shas in
the first commit, and rebuilds them in the last commit. Feel free to
drop my rebuilds and do a more trusted rebuild.
Jars regenerated by Alexandre Rostovtsev <arostovtsev@google.com>
|
|
|
