pax_global_header00006660000000000000000000000064151364252110014512gustar00rootroot0000000000000052 comment=58f90b8c564891b0888929e56c8c0116c9420eb4 stardoc-0.8.1/000077500000000000000000000000001513642521100131575ustar00rootroot00000000000000stardoc-0.8.1/.bazelci/000077500000000000000000000000001513642521100146465ustar00rootroot00000000000000stardoc-0.8.1/.bazelci/presubmit.yml000066400000000000000000000071441513642521100174110ustar00rootroot00000000000000--- matrix: platform: - ubuntu2004 - macos .noenable_bzlmod_flags: &noenable_bzlmod_flags ? "--noenable_bzlmod" ? "--enable_workspace" .windows_flags: &windows_flags # Workaround for https://github.com/bazelbuild/continuous-integration/issues/1012 ? "--noexperimental_repository_cache_hardlinks" .common_task_config: &common_task_config build_targets: - "//..." test_targets: - "//..." .noenable_bzlmod_task_config: &noenable_bzlmod_task_config build_flags: *noenable_bzlmod_flags build_targets: # Note that //distro/... cannot be loaded in legacy WORKSPACE mode due to repo name change - "//:*" - "//src/..." - "//stardoc/..." - "//test/..." test_flags: *noenable_bzlmod_flags test_targets: # Most tests will not pass in legacy WORKSPACE mode due to repo name change - "//test:multiple_files_noenable_bzlmod_test" - "//test:same_level_file_noenable_bzlmod_test" - "//test:table_of_contents_noenable_bzlmod_test" - "//test:local_repository_test" .windows_task_config: &windows_task_config <<: *common_task_config build_flags: *windows_flags test_flags: *windows_flags tasks: build_and_test: <<: *common_task_config name: Build and test platform: ${{ platform }} test_targets: # Non-manual tests + manual tests requiring stable Bazel - "//..." - "//test:symbolic_macro_inherit_attrs_test" skip_in_bazel_downstream_pipeline: "Includes manual golden tests requiring stable Bazel" build_and_test_windows: <<: *windows_task_config name: Build and test - Windows platform: windows test_targets: # Non-manual tests + manual tests requiring stable Bazel - "//..." - "//test:repo_rules_bazel_8_test" - "//test:symbolic_macro_inherit_attrs_bazel_8_test" - "//test:table_of_contents_bazel_8_test" skip_in_bazel_downstream_pipeline: "Includes manual golden tests requiring stable Bazel" build_and_test_last_green: <<: *common_task_config name: Build and test - Bazel last green platform: ${{ platform }} bazel: last_green test_targets: # Non-manual tests + manual tests requiring Bazel at HEAD - "//..." build_and_test_last_green_windows: <<: *windows_task_config name: Build and test - Bazel last green - Windows platform: windows bazel: last_green test_targets: # Non-manual tests + manual tests requiring Bazel at HEAD - "//..." bzlmod_usage: <<: *common_task_config name: Stardoc Bzlmod module usage test platform: ${{ platform }} working_directory: test/bzlmod bzlmod_usage_windows: <<: *windows_task_config name: Stardoc Bzlmod module usage test - Windows platform: windows working_directory: test/bzlmod bazel_8_tests: name: Stardoc golden tests requiring Bazel 8 platform: ubuntu2004 bazel: 8.5.1 test_targets: - "//test:repo_rules_bazel_8_test" - "//test:symbolic_macro_inherit_attrs_bazel_8_test" - "//test:table_of_contents_bazel_8_test" skip_in_bazel_downstream_pipeline: Manual tests requiring an older Bazel version bazel_8_noenable_bzlmod: <<: *noenable_bzlmod_task_config name: Build and test - legacy WORKSPACE setup platform: ubuntu2004 bazel: 8.5.1 skip_in_bazel_downstream_pipeline: WORKSPACE tests requiring an older Bazel version bazel_7_tests: name: Stardoc golden tests requiring Bazel 7 platform: ubuntu2004 bazel: 7.7.1 test_targets: - "//test:proto_format_test" - "//test:macro_kwargs_legacy_test" skip_in_bazel_downstream_pipeline: Manual tests requiring an older Bazel version buildifier: latest stardoc-0.8.1/.bazelignore000066400000000000000000000000141513642521100154540ustar00rootroot00000000000000test/bzlmod stardoc-0.8.1/.bazelrc000066400000000000000000000005221513642521100146010ustar00rootroot00000000000000# Prevent build failure if jdk > 21 is installed as the default system jdk # See https://github.com/bazelbuild/stardoc/pull/263#issuecomment-2502032361 build --java_runtime_version=21 # Incompatible flags which we always want in development build --incompatible_disable_starlark_host_transitions build --incompatible_disallow_empty_glob stardoc-0.8.1/.bcr/000077500000000000000000000000001513642521100140035ustar00rootroot00000000000000stardoc-0.8.1/.bcr/config.yml000066400000000000000000000001021513642521100157640ustar00rootroot00000000000000fixedReleaser: login: tetromino email: arostovtsev@google.com stardoc-0.8.1/.bcr/metadata.template.json000066400000000000000000000006301513642521100202670ustar00rootroot00000000000000{ "homepage": "https://github.com/bazelbuild/stardoc", "maintainers": [ { "name": "Alexandre Rostovtsev", "email": "arostovtsev@google.com", "github": "tetromino" }, { "name": "Jon Brandvein", "email": "brandjon@google.com", "github": "brandjon" } ], "repository": [ "github:bazelbuild/stardoc" ], "versions": [], "yanked_versions": {} } stardoc-0.8.1/.bcr/presubmit.yml000066400000000000000000000003761513642521100165460ustar00rootroot00000000000000matrix: platform: - debian10 - ubuntu2004 - macos - windows bazel: - 8.x - 7.x tasks: verify_targets: name: Verify build targets platform: ${{ platform }} bazel: ${{ bazel }} build_targets: - '@stardoc//stardoc/...' stardoc-0.8.1/.bcr/source.template.json000066400000000000000000000002041513642521100200040ustar00rootroot00000000000000{ "integrity": "**leave this alone**", "url": "https://github.com/{OWNER}/{REPO}/releases/download/{TAG}/{REPO}-{TAG}.tar.gz" } stardoc-0.8.1/.github/000077500000000000000000000000001513642521100145175ustar00rootroot00000000000000stardoc-0.8.1/.github/workflows/000077500000000000000000000000001513642521100165545ustar00rootroot00000000000000stardoc-0.8.1/.github/workflows/create_archive_and_notes.sh000077500000000000000000000060671513642521100241220ustar00rootroot00000000000000#!/usr/bin/env bash # Copyright 2023 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. set -o errexit -o nounset -o pipefail # Set by GH actions, see # https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables TAG=${GITHUB_REF_NAME} ARCHIVE="stardoc-$TAG.tar.gz" bazel build //distro:distro # Copy it locally so release.yml sees it cp bazel-bin/distro/stardoc-*.tar.gz $ARCHIVE SHA=$(shasum -a 256 $ARCHIVE | awk '{print $1}') cat > release_notes.txt << EOF ## MODULE.bazel setup Add to your \`MODULE.bazel\` file: \`\`\`starlark bazel_dep(name = "stardoc", version = "${TAG}") \`\`\` By default - in other words, when using Bzlmod for dependency management - Stardoc uses @stardoc as its repo name. The legacy WORSKSPACE setup (see below) used @io_bazel_stardoc instead. For compatibility with the legacy WORKSPACE setup, you may add repo_name = "io_bazel_stardoc" to the bazel_dep call. ## Legacy WORKSPACE setup To use Stardoc, add the following to your WORKSPACE file: \`\`\`starlark load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") http_archive( name = "io_bazel_stardoc", sha256 = "${SHA}", url = "https://github.com/bazelbuild/stardoc/releases/download/${TAG}/stardoc-${TAG}.tar.gz", ) load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") stardoc_repositories() load("@rules_java//java:rules_java_deps.bzl", "rules_java_dependencies") rules_java_dependencies() load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") protobuf_deps() load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps") rules_jvm_external_deps() load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup") rules_jvm_external_setup() load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps") stardoc_external_deps() load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install") stardoc_pinned_maven_install() \`\`\` The sequence of function calls and load statements after the io_bazel_stardoc repository definition ensures that this repository's dependencies are loaded (each function call defines additional repositories for Stardoc's dependencies, which are then used by subsequent load statements). Note that WORKSPACE files are sensitive to the order of dependencies. If, after updating to a newer version of Stardoc, you encounter "not a valid maven_install.json file" or other repository fetch errors (example: #186), try moving the Stardoc dependency block above or below other dependencies in your WORKSPACE file. EOF stardoc-0.8.1/.github/workflows/release.yml000066400000000000000000000025361513642521100207250ustar00rootroot00000000000000# Copyright 2024 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # Cut a release whenever a new tag is pushed to the repo. name: Release on: push: tags: - "[0-9]+.[0-9]+" - "[0-9]+.[0-9]+.[0-9]+" jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Bazel uses: bazel-contrib/setup-bazel@0.9.1 - name: Create release archive and notes run: .github/workflows/create_archive_and_notes.sh - name: Draft a release uses: softprops/action-gh-release@v2 with: draft: true # Use GH feature to populate the changelog automatically generate_release_notes: true body_path: release_notes.txt fail_on_unmatched_files: true files: stardoc-*.tar.gz stardoc-0.8.1/.gitignore000066400000000000000000000003661513642521100151540ustar00rootroot00000000000000*~ .*.swp /.classpath /.factorypath /.idea/ /.ijwb/ /.project /.settings /WORKSPACE.user.bzl /base_workspace/* /bazel-stardoc /bazel-bin /bazel-genfiles /bazel-out /bazel-testlogs /bazel.iml /output/ /production /.sass-cache /test/bzlmod/bazel-* stardoc-0.8.1/AUTHORS000066400000000000000000000004611513642521100142300ustar00rootroot00000000000000# This the official list of Bazel authors for copyright purposes. # This file is distinct from the CONTRIBUTORS files. # See the latter for an explanation. # Names should be added to this file as: # Name or Organization # The email address is not required for organizations. Google Inc. stardoc-0.8.1/BUILD000066400000000000000000000024041513642521100137410ustar00rootroot00000000000000load("@rules_license//rules:license.bzl", "license") package(default_applicable_licenses = [":license"]) license( name = "license", package_name = "bazelbuild/stardoc", license_kinds = ["@rules_license//licenses/spdx:Apache-2.0"], ) licenses(["notice"]) exports_files( ["LICENSE"], visibility = ["//visibility:public"], ) # Inputs for distro transformations and consistency tests. exports_files( [ "WORKSPACE", "WORKSPACE.bzlmod", "MODULE.bazel", "deps.bzl", "version.bzl", ], visibility = ["//:__subpackages__"], ) filegroup( name = "stardoc_rule_doc", testonly = 1, srcs = ["docs/stardoc_rule.md"], visibility = ["//test:__pkg__"], ) # Sources needed for release tarball. filegroup( name = "distro_srcs", srcs = [ "AUTHORS", "BUILD", "CHANGELOG.md", "CONTRIBUTORS", "LICENSE", "maven_install.json", "//src/main/java/com/google/devtools/build/stardoc/renderer:srcs", "//src/main/java/com/google/devtools/build/stardoc/rendering:srcs", "//stardoc:distro_srcs", "//stardoc/private:distro_srcs", "//stardoc/proto:distro_srcs", ] + glob(["*.bzl"]), visibility = ["//:__subpackages__"], ) stardoc-0.8.1/CHANGELOG.md000066400000000000000000000231371513642521100147760ustar00rootroot00000000000000## Release 0.8.1 Bugfix release: fixes compatibility issues with Bazel 9.0. **New features** - Adds support for `LABEL_LIST_DICT` attribute type and `exec_group_compatible_with` common attribute (#279) **Contributors** Alex Eagle, Alexandre Rostovtsev, Fabian Meumertzheim, Ivo List, Jon Brandvein, Nevena Kotlaja, Philipp Stephani, Thomas Van Lenten, Xùdōng Yáng, Yun Peng ## Release 0.8.0 **New Features** - Adds support for documenting symbolic macros when using Bazel 8.0.1 or newer. (Note that the original Bazel 8.0.0 release had a bug causing macro documentation emitted by Stardoc to be be incomplete.) (#267) **Contributors** Alexandre Rostovtsev, Keith Smiley, Richard Levasseur ## Release 0.7.2 Bugfix release: fixes compatibility issues with Bazel 7.4 and 8.0. Note that this release breaks compatibility with g++ 7.5 (the default compiler in the Ubuntu 18.04 image) - a new transitive dep requires a newer c++ compiler version. **Contributors** Alexandre Rostovtsev, Hemanshu Vadehra, Philip Zembrod, Richard Levasseur ## Release 0.7.1 **Notable Changes** - Really fix building with `--incompatible_disallow_empty_glob` (#238). - Auxiliary rule targets created by `stardoc()` macro now include provided `tags` (#247) **Contributors** Alexandre Rostovtsev, Lukács Berki, yashathwani ## Release 0.7.0 This release requires Bazel 7 or newer. By default - when using Bzlmod for dependency management - Stardoc now uses `@stardoc` as its repo name. For compatibility with the legacy WORKSPACE-based setup (which used `@io_bazel_stardoc` as the repo name) and ease of migration, you may load Stardoc via ```bzl bazel_dep(name = "stardoc", repo_name = "io_bazel_stardoc", ...) ``` in your `MODULE.bazel` file. **New Features** - Add support for a table of contents template (#203). This is disabled by default, but Stardoc comes with an example template that you can use. To enable, set `table_of_contents_template`, for example: ```bzl stardoc( ..., table_of_contents_template = "@stardoc//stardoc:templates/markdown_tables/table_of_contents.vm", ) ``` - Add support for a footer template (#206). This is disabled by default; to enable, set `footer_template` to a .vm file, which you will need to provide. - Add support for providing stamping to Stardoc templates (#205). To use, use `$util.formatBuildTimestamp` and `$stamping` in a template file (`footer_template` - see above - is recommended for this); for example: ```vm Built on `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "yyyy-MM-dd HH:mm")` ``` - Render documentation for provider `init` callbacks (#224) - Properly render `*args`, `*`, and `**kwargs` in summaries (#231). This requires Bazel 8 (prerelease 20240603 or newer). - Include `load` statement in summaries (#216) **Incompatible Changes** - The legacy extractor has been removed (#212). Stardoc always uses the `starlark_doc_extract`-based extractor. The `stardoc`, `semantic_flags`, and `use_starlark_doc_extract` arguments to `stardoc()` macro have been removed. - Stardoc uses Bzlmod by default for dependency management (#213). This means that by default, Stardoc now uses `@stardoc` as its repo name. **Contributors** Alex Humesky, Alexandre Rostovtsev, Fabian Meumertzheim, Grzegorz Lukasik, Xùdōng Yáng, Yun Peng ## Release 0.6.2 Bugfix release: bumps `rules_jvm_external` dependency to support building with `--incompatible_disable_starlark_host_transitions` **Contributors** Alexandre Rostovtsev ## Release 0.6.1 Bugfix release: fix `rules_jvm_external` pin warnings. This release temporarily restores compatibility with Bazel 5 (manually tested). Note that normally we only test Stardoc with the current stable Bazel and with Bazel at HEAD - not with older releases. We make no promises about maintaining compatibility with Bazel 5. **Contributors** Alexandre Rostovtsev ## Release 0.6.0 **New Features** - Stardoc no longer escapes HTML tags in documentation. Feel free to use HTML formatting in your docs! We now also have much-improved rendering for fenced code blocks in attribute docs, and render attribute default values using Markdown instead of HTML markup. (#161, #167) - Stardoc now dedents and trims all doc strings - not only in macros (#170). This means you can have ```bzl my_rule = rule( doc = """ This is my rule. Here is more info about it. ... """, ... ) ``` and Stardoc will dedent and trim the doc to ``` This is my rule. Here is more info about it. ... ``` - When using Bazel 7 or newer (or current Bazel HEAD), Stardoc will by default use the native `starlark_doc_extract` rule internally (#166). This means, in particular: * correct default values for rule attributes in all cases * documentation for module extensions * more complete documentation for repository rules * by default (this can be turned off via `render_main_repo_name = False`), we will render labels in your main repo with a repo component: your main module name (when using bzlmod) or WORKSPACE name (#168). You may temporarily disable the new extractor by calling Stardoc with `use_starlark_doc_extract = False`. However, after Bazel 7 is released, we plan to remove this argument and always use the new extractor. **Incompatible Changes** - The Markdown renderer now uses Google EscapeVelocity instead of Apache Velocity for templating. The templating engines are _almost_ compatible, with the exception of escapes in string literals: if in your template you had a string literal with a character escape, you would need to expand it. For example, instead of ```velocity ${funcInfo.docString.replaceAll("\n", " ")} ``` you would need ```velocity ${funcInfo.docString.replaceAll(" ", " ")} ``` - When using the native `starlark_doc_extract` extractor, Stardoc requires two additional templates: `repository_rule_template` and `module_extension_template`. If you are using custom templates, you will probably want to define these, following the examples in `stardoc/templates/markdown_tables`. - When using the native `starlark_doc_extract` extractor, Stardoc cannot document generated .bzl files any more - because Bazel cannot `load()` generated .bzl files. **Other Notable Changes** - The Markdown renderer's source now lives in the Stardoc repo; we build the renderer from source instead of using a bundled jar. Unfortunately, if you are not using bzlmod, this requires a rather complicated WORKSPACE setup; see https://github.com/bazelbuild/stardoc/releases/tag/0.6.0 **Contributors** Alexandre Rostovtsev, Fabian Meumertzheim ## Release 0.5.6 (initially tagged as 0.5.5) Bugfix release: update `@rules_java` dependency to fix breakage with Bazel at HEAD. **Contributors** Alexandre Rostovtsev ## Release 0.5.4 **New Features** - Stardoc supports bzlmod! (#141, special thanks to Fabian Meumertzheim) - Stardoc output files are now exposed in stardoc() target runfiles (#139) **Contributors** Alexandre Rostovtsev, Fabian Meumertzheim, Greg Estren, Ivo List, Keith Smiley, lberki, Philipp Schrader ## Release 0.5.3 Bugfix release: fixes angle bracket escaping and a crash on labels with `@@` **Contributors** Alexandre Rostovtsev, Jon Shea ## Release 0.5.2 Bugfix release: fixes crash with `config_common.toolchain_type`. **Contributors** Alexandre Rostovtsev, Keith Smiley ## Release 0.5.1 Bugfix release: minor fixes, including a fix for build failure due to missing zlib version. **Contributors** aiuto, Alexandre Rostovtsev, Brian Silverman, Casey, Xùdōng Yáng ## Release 0.5.0 This release includes many fixes for Stardoc's markdown output, plus: **New Features** - Raw protobuf output via `format = "proto"` (#20) - Stardoc now outputs documentation for macro returns and deprecations (#75) as well as module (file) docstrings (#100) **Contributors** Alexandre Rostovtsev, Alex Eagle, Andrew Z Allen, Chris Rebert, c-parsons, Ivo List, Jon Brandvein, Laurent Le Brun, Max Vorobev, pbatg, Philipp Wollermann, Samuel Giddins, Thomas Van Lenten, Tiago Quelhas, Xùdōng Yáng, Yiting Wang ## Release 0.4.0 First release of **Stardoc** under the new repository location [bazelbuild/stardoc](https://github.com/bazelbuild/stardoc). Please use this repository for future Stardoc releases instead of its old location. See [Getting Started](https://github.com/bazelbuild/stardoc/blob/4378e9b6bb2831de7143580594782f538f461180/docs/getting_started_stardoc.md) for updated setup information. There are **many** new features since the last release. A summary of major features: - Changed the default Stardoc output format to use pure-markdown tables instead of HTML tables. This output format is fully compatible with markdown formatting constructs. For example, use `**bold**` instead of `bold`. The `<`. and `>` characters are escaped in this output format. - Stardoc now supports custom formatting. See [Custom Output documentation](https://github.com/bazelbuild/stardoc/blob/4378e9b6bb2831de7143580594782f538f461180/docs/advanced_stardoc_usage.md#custom-output) for details. - `aspect()` definitions are now documented by Stardoc. - Module definitions (structs which combine series of functions in a 'namespace') are now documetned by Stardoc. - Attribute default-value information is now included in output. **Huge Thanks to [kendalllaneee](https://github.com/kendalllaneee) and [blossommojekwu](https://github.com/blossommojekwu) for their work on many of the features in this release.** stardoc-0.8.1/CODEOWNERS000066400000000000000000000000151513642521100145460ustar00rootroot00000000000000* @tetromino stardoc-0.8.1/CONTRIBUTING.md000066400000000000000000000026721513642521100154170ustar00rootroot00000000000000Want to contribute? Great! First, read this page (including the small print at the end). ### Before you contribute **Before we can use your code, you must sign the [Google Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual?csw=1) (CLA)**, which you can do online. The CLA is necessary mainly because you own the copyright to your changes, even after your contribution becomes part of our codebase, so we need your permission to use and distribute your code. We also need to be sure of various other things — for instance that you'll tell us if you know that your code infringes on other people's patents. You don't have to sign the CLA until after you've submitted your code for review and a member has approved it, but you must do it before we can put your code into our codebase. Before you start working on a larger contribution, you should get in touch with us first. Use the issue tracker to explain your idea so we can help and possibly guide you. ### Code reviews and other contributions. **All submissions, including submissions by project members, require review.** Please follow the instructions in [the contributors documentation](https://bazel.build/contribute). ### The small print Contributions made by corporations are covered by a different agreement than the one above, the [Software Grant and Corporate Contributor License Agreement](https://cla.developers.google.com/about/google-corporate). stardoc-0.8.1/CONTRIBUTORS000066400000000000000000000011121513642521100150320ustar00rootroot00000000000000# People who have agreed to one of the CLAs and can contribute patches. # The AUTHORS file lists the copyright holders; this file # lists people. For example, Google employees are listed here # but not in AUTHORS, because Google holds the copyright. # # https://developers.google.com/open-source/cla/individual # https://developers.google.com/open-source/cla/corporate # # Names should be added to this file as: # Name Jon Brandvein Chris Parsons Jingwen Chen Laurent Le Brun stardoc-0.8.1/LICENSE000066400000000000000000000261361513642521100141740ustar00rootroot00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. stardoc-0.8.1/MODULE.bazel000066400000000000000000000024711513642521100151670ustar00rootroot00000000000000module( name = "stardoc", version = "0.8.1", bazel_compatibility = [">=7.0.0"], compatibility_level = 1, ) bazel_dep(name = "protobuf", version = "29.0", repo_name = "com_google_protobuf") bazel_dep(name = "bazel_skylib", version = "1.7.1") bazel_dep(name = "rules_java", version = "8.6.1") bazel_dep(name = "rules_jvm_external", version = "6.6") bazel_dep(name = "rules_license", version = "1.0.0") # Maven artifacts required by Stardoc; keep consistent with deps.bzl STARDOC_MAVEN_ARTIFACTS = [ "com.beust:jcommander:1.82", "com.google.escapevelocity:escapevelocity:1.1", "com.google.guava:guava:31.1-jre", "com.google.truth:truth:1.1.3", "junit:junit:4.13.2", ] maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven") maven.install( name = "stardoc_maven", artifacts = STARDOC_MAVEN_ARTIFACTS, fail_if_repin_required = True, lock_file = "//:maven_install.json", repositories = [ "https://repo1.maven.org/maven2", ], strict_visibility = True, ) use_repo(maven, "stardoc_maven") ### INTERNAL ONLY - lines after this are not included in the release packaging. # # Dev-only and test-only dependencies bazel_dep(name = "rules_pkg", version = "1.0.1", dev_dependency = True) bazel_dep(name = "rules_shell", version = "0.4.0", dev_dependency = True) stardoc-0.8.1/README.md000066400000000000000000000037341513642521100144450ustar00rootroot00000000000000# Stardoc - Starlark Documentation Generator [![Build status](https://badge.buildkite.com/d8594eb71e4869c792cce22428b08e03b345f9c65dc603d70b.svg?branch=master)](https://buildkite.com/bazel/stardoc) Stardoc is a documentation generator for [Bazel](https://bazel.build) APIs such as custom rules written in [Starlark](https://bazel.build/rules/language). Stardoc provides a Bazel rule (`stardoc`, see [documentation](docs/stardoc_rule.md)) that can be used to generate Markdown documentation for Starlark rules. Stardoc generates one documentation page per `.bzl` file. ## Design and Alternatives Stardoc runs a [Velocity template](https://velocity.apache.org/engine/1.7/user-guide.html) on the output of the [native.starlark_doc_extract](https://bazel.build/reference/be/general#starlark_doc_extract) rule. Modules published to the Bazel Central Registry do not need to use Stardoc. They can simply publish the `starlark_doc_extract` outputs as a release artifact. See https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/stardoc.md. ## Get Started * How to [set up Stardoc for your project](docs/getting_started_stardoc.md) * Writing [docstrings](docs/writing_stardoc.md) * How to [integrate Stardoc with your build](docs/generating_stardoc.md). * See also [Advanced Topics](docs/advanced_stardoc_usage.md). ## About Stardoc * Stardoc [rule reference](docs/stardoc_rule.md). * How to [contribute to Stardoc](docs/contributing.md) ## Project Status ### Skydoc deprecation Stardoc is a replacement for the **deprecated** "Skydoc" documentation generator. See [Skydoc Deprecation](docs/skydoc_deprecation.md) for details on the deprecation and migration details. ### Future plans See our [future plans](docs/future_plans.md) for refactoring Stardoc to be more consistent with how Bazel evaluates .bzl files, and what it means for maintenance of this project. ### Maintainer's guide See the [maintaner's guide](docs/maintainers_guide.md) for instructions for cutting a new release. stardoc-0.8.1/WORKSPACE000066400000000000000000000061721513642521100144460ustar00rootroot00000000000000workspace(name = "io_bazel_stardoc") load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") load(":setup.bzl", "stardoc_repositories") stardoc_repositories() load("@rules_java//java:rules_java_deps.bzl", "rules_java_dependencies") rules_java_dependencies() load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") protobuf_deps() load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps") rules_jvm_external_deps() load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup") rules_jvm_external_setup() load(":deps.bzl", "stardoc_external_deps") stardoc_external_deps() load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install") stardoc_pinned_maven_install() ### INTERNAL ONLY - lines after this are not included in the release packaging. # # Include dependencies which are only needed for development of Stardoc here. load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") # Needed for generating the Stardoc release binary. git_repository( name = "io_bazel", commit = "ff36d875b9b236ad141dce40e65cae5f4ffbfdcb", # Bazel 7.0.1 - 2024-01-18 patch_cmds = [ # Used by update-release-binary.sh for vendoring files from @io_bazel "git log -n 1 --format=%H > .io_bazel.sha", ], remote = "https://github.com/bazelbuild/bazel.git", ) # The following binds are needed for building protobuf java libraries. bind( name = "guava", actual = "@io_bazel//third_party:guava", ) bind( name = "gson", actual = "@io_bazel//third_party:gson", ) bind( name = "error_prone_annotations", actual = "@io_bazel//third_party:error_prone_annotations", ) # Needed for //distro:__pkg__ http_archive( name = "rules_pkg", sha256 = "d20c951960ed77cb7b341c2a59488534e494d5ad1d30c4818c736d57772a9fef", urls = [ "https://mirror.bazel.build/github.com/bazelbuild/rules_pkg/releases/download/1.0.1/rules_pkg-1.0.1.tar.gz", "https://github.com/bazelbuild/rules_pkg/releases/download/1.0.1/rules_pkg-1.0.1.tar.gz", ], ) load("@rules_pkg//:deps.bzl", "rules_pkg_dependencies") rules_pkg_dependencies() # Needed for tests http_archive( name = "rules_shell", sha256 = "3e114424a5c7e4fd43e0133cc6ecdfe54e45ae8affa14fadd839f29901424043", strip_prefix = "rules_shell-0.4.0", url = "https://github.com/bazelbuild/rules_shell/releases/download/v0.4.0/rules_shell-v0.4.0.tar.gz", ) load("@rules_shell//shell:repositories.bzl", "rules_shell_dependencies", "rules_shell_toolchains") rules_shell_dependencies() rules_shell_toolchains() # Needed only for testing stardoc across local-repository bounds. local_repository( name = "stardoc", # alias the Bzlmod name of the Stardoc repo for local_repository_test path = ".", ) local_repository( name = "local_repository_test", path = "test/testdata/local_repository_test", ) load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies") rules_proto_dependencies() load("@rules_proto//proto:setup.bzl", "rules_proto_setup") rules_proto_setup() load("@rules_proto//proto:toolchains.bzl", "rules_proto_toolchains") rules_proto_toolchains() stardoc-0.8.1/WORKSPACE.bzlmod000066400000000000000000000003751513642521100157330ustar00rootroot00000000000000### INTERNAL ONLY - lines after this are not included in the release packaging. # Needed only for testing stardoc across local-repository bounds. local_repository( name = "local_repository_test", path = "test/testdata/local_repository_test", ) stardoc-0.8.1/deps.bzl000066400000000000000000000040021513642521100146170ustar00rootroot00000000000000# Copyright 2023 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """WORKSPACE dependency definitions for Stardoc.""" load("@rules_jvm_external//:defs.bzl", "maven_install") load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies") load("@rules_proto//proto:setup.bzl", "rules_proto_setup") load("@rules_python//python:repositories.bzl", "py_repositories") # Maven artifacts required by Stardoc; keep consistent with MODULE.bazel STARDOC_MAVEN_ARTIFACTS = [ "com.beust:jcommander:1.82", "com.google.escapevelocity:escapevelocity:1.1", "com.google.guava:guava:31.1-jre", "com.google.truth:truth:1.1.3", "junit:junit:4.13.2", ] def stardoc_external_deps(): """ Sets up Stardoc's workspace dependencies. Requires stardoc_repositories() to be called first. Normally should be followed up by ```bzl load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install") stardoc_pinned_maven_install() ``` """ maven_install( name = "stardoc_maven", artifacts = STARDOC_MAVEN_ARTIFACTS, fail_if_repin_required = True, maven_install_json = "@io_bazel_stardoc//:maven_install.json", repositories = [ "https://repo1.maven.org/maven2", ], strict_visibility = True, ) py_repositories() rules_proto_dependencies() # Note rules_proto_setup() requires @bazel_features - we define it in stardoc_repositories() rules_proto_setup() stardoc-0.8.1/distro/000077500000000000000000000000001513642521100144635ustar00rootroot00000000000000stardoc-0.8.1/distro/BUILD000066400000000000000000000020621513642521100152450ustar00rootroot00000000000000load("@rules_pkg//:pkg.bzl", "pkg_tar") load("@stardoc//:version.bzl", "version") load(":distro.bzl", "strip_internal_only") package( default_applicable_licenses = ["//:license"], default_visibility = ["//visibility:private"], ) alias( name = "distro", actual = "stardoc-%s" % version, ) strip_internal_only( name = "distro_module_bazel", src = "//:MODULE.bazel", out = "MODULE.bazel", ) strip_internal_only( name = "distro_workspace", src = "//:WORKSPACE", out = "WORKSPACE", ) strip_internal_only( name = "distro_workspace_bzlmod", src = "//:WORKSPACE.bzlmod", out = "WORKSPACE.bzlmod", ) # Build the artifact to put on the github release page. pkg_tar( name = "stardoc-%s" % version, srcs = [ "distro_module_bazel", "distro_workspace", "distro_workspace_bzlmod", "//:distro_srcs", ], extension = "tar.gz", mode = "0644", # Make it owned by root so it does not have the uid of the CI robot. owner = "0.0", package_dir = "", strip_prefix = ".", ) stardoc-0.8.1/distro/distro.bzl000066400000000000000000000022011513642521100164730ustar00rootroot00000000000000# Copyright 2024 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Macros related to distro tarball packaging""" def strip_internal_only(name, src, out): """Strip an internal-only block from a file Removes everything starting with `### INTERNAL ONLY` and ending with `### END INTERNAL ONLY` (or up to the end of the file). Args: name: Target name src: Input file out: Output file """ native.genrule( name = name, srcs = [src], outs = [out], cmd = "sed -e '/### INTERNAL ONLY/,/### END INTERNAL ONLY/d' $(location %s) >$@" % src, ) stardoc-0.8.1/docs/000077500000000000000000000000001513642521100141075ustar00rootroot00000000000000stardoc-0.8.1/docs/advanced_stardoc_usage.md000066400000000000000000000111031513642521100210750ustar00rootroot00000000000000 This document covers a number of advanced topics pertaining to using Stardoc. ## Docstring Formatting You may want to inline various kinds of formatting in the docstrings adjacent to your Starlark code. Use standard markdown formatting constructs instead of HTML tags. For example: ```starlark def my_function(foo, bar): """Does some cool stuff. Oh, by the way, have you heard about [Stardoc](https://github.com/bazelbuild/stardoc)? Args: foo: You don't know what a **foo** is? bar: Two variables, `x` and `y`, walk in to a bar... """ ... ``` Markdown formatting constructs are handled appropriately by Stardoc's default output format ("markdown_tables"), even as part of a table. ## Custom Output Stardoc's output format is customizable; while Stardoc's output is markdown by default, you may define a different output format for your documentation. Customization is done at the level of "output templates". To customize the doc output for a particular type of Starlark definition (such as a "rule" or a "function"), you will need to: 1. Create a new custom output template to describe how this type of object should be rendered. 2. In your `stardoc()` target, set the matching `_template` attribute to point to your new output template. For example, you might want to change the way rule documentation is generated. You might create a new output template file `package/rule.vm` and then define your `stardoc` target as follows: ```python stardoc( name = "my_docs", input = "my_rule.bzl", out = "my_rule_doc.md", rule_template = "//package:rule.vm", ) ``` The default values for the available templates may be found under [templates/markdown_tables](../stardoc/templates/markdown_tables). See the [Stardoc rule documentation](stardoc_rule.md) for a comprehensive list of which '_template' attributes are available. ### Writing a custom output template Stardoc's output templates are defined using [Velocity Template Language (VTL)](https://velocity.apache.org/engine/1.7/user-guide.html) with utilities and model objects available in the evaluation context. The full comprehensive list of available utilities top-level objects is available in [the source for MarkdownRenderer](../src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java). Information available for raw model objects (such rule information) is defined by Stardoc's underlying [proto schema](../stardoc/proto/stardoc_output.proto), vendored [from the Bazel source tree](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto). This is a particularly advanced feature of Stardoc, so we would recommend using one of the existing canonical [templates](../stardoc/templates/markdown_tables) as a springboard to get started. ## Proto Output Stardoc provides the option to output documentation information in raw proto format. You may find this useful if you need output customization beyond Stardoc's current custom-output-template capabilities: you might prefer to build your own custom output renderer binary using the data that Stardoc acquires by fully evaluating a Starlark file. If your changes could be incorporated into Stardoc, please first consider [contributing](contributing.md) instead. The proto schema may be found under [stardoc/proto/stardoc_output.proto](../stardoc/proto/stardoc_output.proto), vendored [from the Bazel source tree](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto). To configure stardoc to output raw proto instead of markdown, use the `format` attribute of the [stardoc rule](stardoc_rule.md#stardoc-format). Specify `"proto"`. An example: ```starlark stardoc( name = "docs_proto_output", out = "doc_output.raw", input = ":my_rule.bzl", deps = [":my_lib"], format = "proto", ) # Define a proto_library target to incorporate the stardoc_output_proto proto_library( name = "stardoc_output_proto", srcs = ["@stardoc//stardoc/proto:stardoc_output.proto"], ) # You'll need to define your own rendering target. This might be a # `genrule` or your own custom rule. genrule( name = "docs_markdown_output", tools = ["my_renderer.sh"], srcs = ["doc_output.raw"], outs = ["doc_output.md"], cmd = "$(location :my_renderer.sh) $@ $(SRCS)", ) ``` stardoc-0.8.1/docs/contributing.md000066400000000000000000000053231513642521100171430ustar00rootroot00000000000000Before contributing, please see the note on our [current priorities](future_plans.md). In short, we're able to take bugfixes to critical features, but cannot guarantee that we'll be able to review new features in a timely manner. To contribute to Stardoc, first see the official [contributing notice](../CONTRIBUTING.md), then feel free to fork the [Stardoc](https://github.com/bazelbuild/stardoc) GitHub repository and start submitting pull requests. In general, we prefer contributions that fix bugs or add features (as opposed to purely stylistic, refactoring, or "cleanup" changes). Please check with us by opening a [GitHub Issue](https://github.com/bazelbuild/stardoc/issues) or starting a [GitHub Discussion](https://github.com/bazelbuild/bazel/discussions). ## Stardoc code structure * Stardoc internally relies on Bazel's `starlark_doc_extract` rule to extract documentation in [proto format](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/stardoc_output.proto) (vendored into Stardoc's repo in [stardoc/proto/stardoc_output.proto](../src/proto/stardoc_output.proto)) * The [src](../src) directory contains Stardoc's renderer, written in Java, which transforms the proto output into Markdown. * The [stardoc](../stardoc) directory contains the Starlark rule and wrapper macro which serves as the entry point for Stardoc users, and the default Velocity templates which configure Markdown output. * Java unit tests live in the [src/test](../src/test/) directory, while integration tests are in the [test](../test/) directory. ## Contributing to Stardoc * Stardoc is part of the Bazel project. Read the [Bazel governance plan](https://www.bazel.build/governance.html) and Stardoc's [contribution guidelines](../CONTRIBUTING.md). * Open an [Issue](https://github.com/bazelbuild/stardoc/issues) or discuss your plan or design on [Github Discussions](https://github.com/bazelbuild/bazel/discussions) * Prepare a Git commit that implements your feature or bug fix. Don't forget to add tests and reference the corresponding bug, if any. * Open a [Pull Request](https://github.com/bazelbuild/stardoc/pulls) on the Stardoc repository. This will require that you have signed a [Contributor License Agreement](https://cla.developers.google.com/). * Complete a code review with a [core contributor](#core-contributors). Amend your patch by making additional commits or rebasing with HEAD if there are conflicts with new commits on the master branch. * Once the code review is complete, your reviewer will squash/merge your pull request to the master branch. ## Core Contributors The current group of Stardoc core contributors are: * [brandjon](https://github.com/brandjon) * [tetromino](https://github.com/tetromino) stardoc-0.8.1/docs/future_plans.md000066400000000000000000000067421513642521100171510ustar00rootroot00000000000000**Last updated:** January 2021. **Summary:** We'll be redesigning how Stardoc works, and deprioritizing feature requests and minor bugs until that work is complete (targeting 2021 Q2). ## Technical motivation Stardoc is currently the recommended tool for generating documentation of Starlark rules. It [replaces](skydoc_deprecation.md) *Sky*doc, the previous tool, which worked by evaluating .bzl files in a Python interpreter, using fake versions of functions from Bazel's Build Language. Mocking is an inherently problematic approach for two reasons: 1. It creates a maintenance burden for the tool maintainer (us). We have to ensure that the mocked definitions stay up-to-date as Bazel changes. These include not just `rule()` and `provider()`, but also a number of other symbols that don't directly affect documentation but still require stubs. 2. It puts a constraint on the user: All of their documented .bzl files, as well as all of the .bzl dependencies they transitively load, must be compatible with the mock evaluation. This means users must be vigilant about writing Starlark code that lies in the intersection of what is understood as valid by Bazel and by Stardoc. The Python-based Skydoc experienced an extreme version of this problem because it didn't even treat .bzl files as being written in the Starlark language. However, the Java-based Stardoc still uses mocking -- not of the Starlark language, but of Bazel's Build Language functions. In addition, Stardoc's mocking approach tightly integrates it with Bazel. Indeed much of its source code lives inside the bazelbuild/bazel repository. This makes refactoring and evolving the Bazel source code more difficult. While the Starlark language has a specification and several implementations, the Build Language is more complicated and has only one accurate implementation: Bazel. Any tooling that operates on BUILD and .bzl files must carefully consider whether it is feasible to ask Bazel for the authoritative information. The alternative, falling back on simulation, not only produces less accurate results, but ties our hands as we try to improve Bazel. ## Our plans We will rewrite the part of Stardoc that extracts documentation information from .bzl files, so that instead of using mocking to pseudo-evaluate individual .bzl files, it performs a real Bazel evaluation of the workspace. Think of how `bazel query` is used to dump out information from Bazel's loading phase about the target dependency graph. Now imagine that it's extended to also dump out the rules and providers declared in the .bzl files used by a build, and that this dump also includes their docstrings. This approach intersects other work we are doing to simplify and better specify Bazel's loading phase, so that users have access to all sorts of information that was previously not readily available. Note that this new internal approach does not necessarily have to mean the user's workflow changes. You could still write a target in your BUILD file to say exactly what content you want documented and how you'd like it formatted. The rendering logic may very well continue to live outside of Bazel, in the bazelbuild/stardoc repository. ## Prioritization We're aiming to explore this design in more concrete detail in 2021 Q1, and implement it in Q2. In the meantime, *we will not be focusing on improvements to the current implementation of Stardoc*, even the formatting parts which might remain the same. We still commit to keeping Stardoc working for its existing essential use cases. stardoc-0.8.1/docs/generating_stardoc.md000066400000000000000000000102441513642521100202740ustar00rootroot00000000000000 The following are some examples of how to use Stardoc. **Note**: By default - in other words, when using Bzlmod for dependency management - Stardoc uses `@stardoc` as its repo name. However, if you are using the legacy `WORSKPACE`-based setup for dependency management, replace `@stardoc` with `@io_bazel_stardoc` in the examples below. ## Single File Suppose you have a project containing Stardoc rules you want to document: ``` [workspace]/ WORKSPACE checkstyle/ BUILD checkstyle.bzl ``` To generate documentation for the rules in `checkstyle.bzl`, add the following target to `checkstyle/BUILD`: ```starlark load("@stardoc//stardoc:stardoc.bzl", "stardoc") stardoc( name = "checkstyle-docs", input = "checkstyle.bzl", out = "checkstyle_doc.md", ) ``` Running `bazel build //checkstyle:checkstyle-docs` will generate a markdown file containing documentation for all Starlark rules defined in `checkstyle.bzl`. To generate a subset of rules defined in `checkstyle.bzl`, you may specify which rule names you specifically want documentation for using the `symbol_names` attribute of the `stardoc` rule. If `symbol_names` is specified, only rules matching a name in `symbol_names` will be documented: ```starlark load("@stardoc//stardoc:stardoc.bzl", "stardoc") stardoc( name = "checkstyle-docs", input = "checkstyle.bzl", out = "checkstyle_doc.md", symbol_names = ["checkstyle_rule", "other_rule"], ) ``` ## Files with Dependencies If you would like to generate documentation for a `.bzl` with dependencies on other `.bzl` files, use the `bzl_library` rule to create logical collections of Starlark sources and depend on these libraries via the `deps` attribute of your `stardoc` target. Suppose your project has the following structure: ``` [workspace]/ WORKSPACE BUILD checkstyle/ BUILD checkstyle.bzl lua/ BUILD lua.bzl luarocks.bzl ``` ...and suppose your target `.bzl` file depends on other `.bzl` files in your workspace: `checkstyle/checkstyle.bzl`: ```starlark load("//lua:lua.bzl", "lua_utility") lua_utility() checkstyle_rule = rule( ... ) ``` In this case, you can have a `bzl_library` target in `lua/BUILD`: `lua/BUILD`: ```python load("@bazel_skylib//:bzl_library.bzl", "bzl_library") bzl_library( name = "lua-rules", srcs = [ "lua.bzl", "luarocks.bzl", ], ) ``` To build documentation for `checkstyle.bzl`, specify the `bzl_library` target as a dependency of the `stardoc` target: `checkstyle/BUILD`: ```starlark load("@stardoc//stardoc:stardoc.bzl", "stardoc") stardoc( name = "checkstyle-docs", input = "checkstyle.bzl", out = "checkstyle_doc.md", deps = ["//lua:lua-rules"], ) ``` ## Multiple Files If you would like to generate documentation for multiple .bzl files in various packages in your workspace, you will need to create a single `.bzl` file that depends on all those `.bzl` files. You can then explicitly whitelist rules for which you would like documentation to be generated. For example, you may want to generate documentation for `foo_rule`, `bar_rule`, and `baz_rule`, all in different `.bzl` files. First, you would create a single `.bzl` file which loads these files and binds the rules to be documented as globals: `doc_hub.bzl`: ```starlark load("//foo:foo.bzl", _foo_rule = "foo_rule") load("//bar:bar.bzl", _bar_rule = "bar_rule") load("//baz:baz.bzl", _baz_rule = "baz_rule") foo_rule = _foo_rule bar_rule = _bar_rule baz_rule = _baz_rule # No need for any implementation here. The rules need only be loaded. ``` A single `stardoc` target can then be used to generate their documentation: `BUILD`: ```python load("@stardoc//stardoc:stardoc.bzl", "stardoc") stardoc( name = "my-docs", input = "doc_hub.bzl", out = "docs.md", symbol_names = ["foo_rule", "bar_rule", "baz_rule"], ) ``` stardoc-0.8.1/docs/getting_started_stardoc.md000066400000000000000000000030711513642521100213400ustar00rootroot00000000000000Stardoc is a documentation generator for [Bazel](https://bazel.build) build rules written in [Starlark](https://bazel.build/rules/language). Stardoc provides a Starlark rule (`stardoc`) that can be used to build Markdown documentation for Starlark rules, providers, and functions. Starlark generates one documentation page per `stardoc` target. If you are new to writing build rules for Bazel, please read the Bazel documentation on [writing extensions](https://bazel.build/extending/concepts) ## Setup Add a `bazel_dep` invocation for Stardoc to your `MODULE.bazel` file, as shown in the `MODULE.bazel` setup section for [the current Stardoc release](https://github.com/bazelbuild/stardoc/releases). Then add ```starlark load("@stardoc//stardoc:stardoc.bzl", "stardoc") ``` to your `BUILD` or .bzl file to start using the `stardoc` rule. ## Legacy WORKSPACE setup Edit your `WORKSPACE` file as shown in the `WORKSPACE` setup section for [the current Stardoc release](https://github.com/bazelbuild/stardoc/releases). Then add ```starlark load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") ``` to your `BUILD` or .bzl file to start using the `stardoc` rule. Note that if you are using `WORKSPACE` for dependency management, Stardoc's repo name is `@io_bazel_stardoc`, not `@stardoc`. ## Next Steps Now you are ready to document your Starlark rules. * Learn about the [docstring format](writing_stardoc.md) used to document Starlark rules. * Learn about how you can use Stardoc's [build rules](generating_stardoc.md) to generate your documentation in Markdown format. stardoc-0.8.1/docs/maintainers_guide.md000066400000000000000000000131071513642521100201220ustar00rootroot00000000000000# Stardoc Maintainer's Guide ## Updating Proto Stardoc proto definition is vendored from the Bazel source tree at https://github.com/bazelbuild/bazel/tree/master/src/main/protobuf/stardoc_output.proto To update the proto definition from Bazel's master branch, run `update-release-binary.sh` To vendor the proto definition from a particular branch or commit in the Bazel tree, run `BAZEL_BRANCH=$BRANCH_OR_SHA ./update-release-binary.sh` ## Making a New Release 1. Verify tests. Verify that dependencies are consistent between `setup.bzl` + `WORKSPACE` and `MODULE.bazel`. 2. Update `CHANGELOG.md` at the top. You may want to use the following \ template: -------------------------------------------------------------------------------- ## Release $VERSION **New Features** - Feature - Feature **Incompatible Changes** - Change - Change **Contributors** Name 1, Name 2, Name 3 (alphabetically) -------------------------------------------------------------------------------- 3. Bump `version` in `version.bzl` *and* `MODULE.bazel` to the new version. 4. Ensure that the commits for steps 1-3 have been merged. All further steps must be performed on a single, known-good git commit. 5. `bazel build //distro` 6. Copy the `stardoc-$VERSION.tar.gz` tarball to the mirror (you'll need Bazel developer gcloud credentials; assuming you are a Bazel developer, you can obtain them via `gcloud init`): ```bash gsutil cp bazel-bin/distro/stardoc-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz gsutil setmeta -h "Cache-Control: public, max-age=31536000" "gs://bazel-mirror/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz" ``` 7. Obtain checksum for release notes: ```bash sha256sum bazel-bin/distro/stardoc-$VERSION.tar.gz ``` 8. Draft a new release with a new tag named $VERSION in github. Attach `stardoc-$VERSION.tar.gz` to the release. For the release notes, use the CHANGELOG.md entry plus the following template: -------------------------------------------------------------------------------- **MODULE.bazel setup** ```starlark bazel_dep(name = "stardoc", version = "$VERSION") ``` By default - in other words, when using Bzlmod for dependency management - Stardoc uses `@stardoc` as its repo name. The legacy `WORSKSPACE` setup (see below) used `@io_bazel_stardoc` instead. For compatibility with the legacy `WORKSPACE` setup, you may add `repo_name = "io_bazel_stardoc"` to the `bazel_dep` call. **Legacy WORKSPACE setup** To use Stardoc, add the following to your `WORKSPACE` file: ```starlark load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") http_archive( name = "io_bazel_stardoc", sha256 = "$SHA256SUM", urls = [ "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz", "https://github.com/bazelbuild/stardoc/releases/download/$VERSION/stardoc-$VERSION.tar.gz", ], ) load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") stardoc_repositories() load("@rules_java//java:rules_java_deps.bzl", "rules_java_dependencies") rules_java_dependencies() load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") protobuf_deps() load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps") rules_jvm_external_deps() load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup") rules_jvm_external_setup() load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps") stardoc_external_deps() load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install") stardoc_pinned_maven_install() ``` The sequence of function calls and load statements after the `io_bazel_stardoc` repository definition ensures that this repository's dependencies are loaded (each function call defines additional repositories for Stardoc's dependencies, which are then used by subsequent load statements). Note that `WORKSPACE` files are sensitive to the order of dependencies. If, after updating to a newer version of Stardoc, you encounter "not a valid maven_install.json file" or other repository fetch errors (example: #186), try moving the Stardoc dependency block above or below other dependencies in your `WORKSPACE` file. **Using the rules** See [the source](https://github.com/bazelbuild/stardoc/tree/$VERSION). -------------------------------------------------------------------------------- 9. Obtain [Subresource Integrity](https://w3c.github.io/webappsec-subresource-integrity/#integrity-metadata-description) format checksum for bzlmod: ```bash echo -n sha256-; cat bazel-bin/distro/stardoc-$VERSION.tar.gz | openssl dgst -sha256 -binary | base64 ``` 10. Create a PR at [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry) to update the registry's versions of Stardoc. Use https://github.com/bazelbuild/bazel-central-registry/pull/677 as the model; you will need to update `modules/stardoc/metadata.json` to list the new version in `versions`, and create new $VERSION subdirectories for the updated module, using the latest existing version subdirectories as the guide. Use Subresource Integrity checksums obtained above in the new `source.json` file. Ensure that the `MODULE.bazel` file you add in the new $VERSION subdirectory exactly matches the `MODULE.bazel` file packaged in the stardoc-$VERSION.tar.gz tarball - or buildkite checks will fail. 11. Once the Bazel Central Registry PR is merged, uncomment the MODULE.bazel block in the release description.stardoc-0.8.1/docs/skydoc_deprecation.md000066400000000000000000000077401513642521100203120ustar00rootroot00000000000000## Why was Skydoc deprecated? Skydoc functioned by evaluating Starlark files as if they were Python. Unfortunately, while Starlark is **similar** to Python, there are some important syntactic differences between the languages. Assuming compatibility between the languages was inherently brittle, and resulted in a maintenance burden on the Starlark code. Specifically, if one of your transitive dependencies were to adopt a Starlark-compatible, Python-incompatible construct, your Skydoc integration would break! Skydoc still exists under [bazelbuild/skydoc](https://github.com/bazelbuild/skydoc), as it's a nontrivial migration to Stardoc, but Skydoc is completely unsupported as of September 2019. The [bazelbuild/skydoc](https://github.com/bazelbuild/skydoc) will be archived by end of 2019. ## How to migrate Stardoc is not a drop-in replacement for Skydoc. Its usage is slightly different, and it has some new features. It's recommended to take a look at the root Stardoc documentation, but here is a brief summary of some things to note for migration: ### Docstring specification Stardoc uses inline documentation strings instead of Python-style docstrings. For example, Skydoc documentation may have been specified with: ```python my_rule = rule( implementation = _my_rule_impl, attrs = { "srcs": attr.label_list(), "deps": attr.label_list(), }, ) """Example rule documentation. Example: Here is an example of how to use this rule. Args: srcs: Source files used to build this target. deps: Dependencies for this target. """ ``` ...the equivalent for Stardoc is: ```python my_rule = rule( implementation = _my_rule_impl, doc = """ Example rule documentation. Example: Here is an example of how to use this rule. """, attrs = { "srcs" : attr.label_list( doc = "Source files used to build this target.", ), "deps" : attr.label_list( doc = "Dependencies for this target.", ), } ) ``` ### Different Starlark Rule Stardoc uses a different Starlark rule than Skydoc with different attributes. See [Generating Documentation](generating_stardoc.md) for a tutorial on using the new rule, and the [Build Rule Reference](docs/stardoc_reference.md) for information about the new `stardoc` rule itself. ### Starlark Dependencies Stardoc depends on your `bzl` file, all of its dependencies, and all of its **transitive** dependencies, so that it can fully evaluate your Starlark code. `bazel-skylib`'s `bzl_library` is the recommend approach for tracking `bzl` dependencies. For example, suppose your `mypackage/foo.bzl` file depends on `other/package/bar.bzl`, which depends on `third/package/baz.bzl`. **BUILD**: ```python load("@stardoc//stardoc:stardoc.bzl", "stardoc") stardoc( name = "foo_docs", input = "foo.bzl", out = "foo_doc.md", deps = ["//other/package:bar"], ) ``` **other/package/BUILD**: ```python load("@bazel_skylib//:bzl_library.bzl", "bzl_library") bzl_library( name = "bar", srcs = ["bar.bzl"], deps = ["//third/package:baz"], ) ``` **third/package/BUILD**: ```python load("@bazel_skylib//:bzl_library.bzl", "bzl_library") bzl_library( name = "baz", srcs = ["baz.bzl"], ) ``` Thus, each `.bzl` file should appear in the `srcs` of a `bzl_library` target defined in the same package. The `deps` of this `bzl_library` should be (only) the `bzl_library` targets corresponding to the files that are _directly_ `load()`ed by the `srcs`. This structure mirrors that of other `_library` rules in Bazel. This migration might involve creating a large number of new `bzl_library` targets, but this work is useful beyond Stardoc. For example, `bzl_library` can be also used to gather transitive Starlark dependencies for use in shell tests or other test frameworks. See [Generating Documentation](docs/generating_stardoc.md) for a tutorial. ## Migration Issues If you run into any issues migrating, please file a [GitHub issue](https://github.com/bazelbuild/stardoc/issues). stardoc-0.8.1/docs/stardoc_rule.md000066400000000000000000000132011513642521100171140ustar00rootroot00000000000000 Starlark rule for stardoc: a documentation generator tool written in Java. ## stardoc
load("@stardoc//stardoc:stardoc.bzl", "stardoc")

stardoc(*, name, input, out, deps, format, symbol_names, renderer, aspect_template, func_template,
        macro_template, header_template, table_of_contents_template, provider_template, rule_template,
        repository_rule_template, module_extension_template, footer_template, render_main_repo_name,
        stamp, **kwargs)
Generates documentation for exported starlark rule definitions in a target starlark file. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name of the stardoc target. | none | | input | The starlark file to generate documentation for (mandatory). | none | | out | The file to which documentation will be output (mandatory). | none | | deps | A list of bzl_library dependencies which the input depends on. | `[]` | | format | The format of the output file. Valid values: 'markdown' or 'proto'. | `"markdown"` | | symbol_names | A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated. | `[]` | | renderer | The location of the renderer tool. | `Label("@stardoc//stardoc:renderer")` | | aspect_template | The input file template for generating documentation of aspects | `Label("@stardoc//stardoc:templates/markdown_tables/aspect.vm")` | | func_template | The input file template for generating documentation of functions, including legacy macros. | `Label("@stardoc//stardoc:templates/markdown_tables/func.vm")` | | macro_template | The input file template for generating documentation of symbolic macros. | `Label("@stardoc//stardoc:templates/markdown_tables/macro.vm")` | | header_template | The input file template for the header of the output documentation. | `Label("@stardoc//stardoc:templates/markdown_tables/header.vm")` | | table_of_contents_template | The input file template for the table of contents of the output documentation. This is unset by default for backwards compatibility. Use `Label("@stardoc//stardoc:templates/markdown_tables/table_of_contents.vm")` for the default template. | `None` | | provider_template | The input file template for generating documentation of providers. | `Label("@stardoc//stardoc:templates/markdown_tables/provider.vm")` | | rule_template | The input file template for generating documentation of rules. | `Label("@stardoc//stardoc:templates/markdown_tables/rule.vm")` | | repository_rule_template | The input file template for generating documentation of repository rules. | `Label("@stardoc//stardoc:templates/markdown_tables/repository_rule.vm")` | | module_extension_template | The input file template for generating documentation of module extensions. | `Label("@stardoc//stardoc:templates/markdown_tables/module_extension.vm")` | | footer_template | The input file template for generating the footer of the output documentation. Optional. | `None` | | render_main_repo_name | Render labels in the main repository with a repo component (either the module name or workspace name). | `True` | | stamp | Whether to provide stamping information to templates, where it can be accessed via `$util.formatBuildTimestamp()` and`$stamping`. Example:
Built on `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "yyyy-MM-dd HH:mm")`
Possible values:
  • `stamp = 1`: Always provide stamping information, even in [--nostamp](https://bazel.build/docs/user-manual#stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.
  • `stamp = 0`: Do not provide stamping information.
  • `stamp = -1`: Provide stamping information only if the [--stamp](https://bazel.build/docs/user-manual#stamp) flag is set.
Stamped targets are not rebuilt unless their dependencies change. | `-1` | | kwargs | Further arguments to pass to stardoc. | none | stardoc-0.8.1/docs/writing_stardoc.md000066400000000000000000000077601513642521100176450ustar00rootroot00000000000000 When generating documentation, Stardoc parses the `.bzl` file to extract the inline documentation as well as evaluates the Starlark code to determine the types for rule attributes. Stardoc will, by default, generate documentation for all rules, macros, and functions reachable from a target `.bzl` file. See [Generating Stardoc](generating_stardoc.md) for details on limiting the symbols for which stardoc generates documentation. ## Rule Documentation When generating documentation, Stardoc parses the `.bzl` file to extract the inline documentation as well as evaluates the Starlark code to determine the types for rule attributes. Private rule attributes (attributes with names that begin with `_`) will not appear in generated documentation. [Starlark Rules](https://bazel.build/rules/rules-tutorial) are declared using the `rule()` function as global variables. General rule documentation should be supplied in the `doc` parameter of the `rule()` function. Likewise, supply attribute documentation in the `doc` parameter of attribute schema-defining functions, such as `attr.label()`. ```python my_rule = rule( implementation = _my_rule_impl, doc = """ Example rule documentation. Example: Here is an example of how to use this rule. """, attrs = { "srcs" : attr.label_list( doc = "Source files used to build this target.", ), "deps" : attr.label_list( doc = "Dependencies for this target.", ), } ) ``` The `name` attribute that is common to all rules is documented by default. ## Provider Documentation [Starlark Providers](https://docs.bazel.build/versions/master/skylark/rules.html#providers) are documented similarly to rules: using docstrings specified as parameters during creation of the provider. General provider documentation can be specified using the `doc` parameter to the `provider()` function. Field-related documentation can be specified by passing a map to the `fields` parameter of the `provider()` function. Keys are required field names, and values are their corresponding docstrings. ```python MyInfo = provider( doc = """ A provider with some really neat documentation. Contains information about some of my favorite things. """, fields = {'favorite_food' : 'A string representing my favorite food', 'favorite_color' : 'A string representing my favorite color'} ) ``` ## Macro / Function Documentation Functions and [Starlark Macros](https://bazel.build/extending/legacy-macros) are documented using docstrings similar to Python docstring format: ```python def rat_check(name, srcs=[], format, visibility): """Runs Apache Rat license checks on the given source files. This rule runs [Apache Rat](http://creadur.apache.org/rat/) license checks on a given set of source files. Use `bazel build` to run the check. Args: name: A unique name for this rule. srcs: Source files to run the Rat license checks against. Note that the Bazel glob() function can be used to specify which source files to include and which to exclude. format: The format to write the Rat check report in. visibility: The visibility of this rule. """ if format not in ['text', 'html', 'xml']: fail('Invalid format: %s' % format, 'format') _rat_check( name = name, srcs = srcs, format = format, visibility = visibility, ) ``` Parameters are documented in a special `Args:` section. Begin the documentation for each parameter on an indented line with the parameter name followed by a colon `:`. The documentation for a parameter can span multiple lines as long as each line is indented from the first line. stardoc-0.8.1/maven_install.json000066400000000000000000000214011513642521100167040ustar00rootroot00000000000000{ "__AUTOGENERATED_FILE_DO_NOT_MODIFY_THIS_FILE_MANUALLY": "THERE_IS_NO_DATA_ONLY_ZUUL", "__INPUT_ARTIFACTS_HASH": -1307151106, "__RESOLVED_ARTIFACTS_HASH": 1764595048, "artifacts": { "com.beust:jcommander": { "shasums": { "jar": "deeac157c8de6822878d85d0c7bc8467a19cc8484d37788f7804f039dde280b1" }, "version": "1.82" }, "com.google.auto.value:auto-value-annotations": { "shasums": { "jar": "37ec09b47d7ed35a99d13927db5c86fc9071f620f943ead5d757144698310852" }, "version": "1.8.1" }, "com.google.code.findbugs:jsr305": { "shasums": { "jar": "766ad2a0783f2687962c8ad74ceecc38a28b9f72a2d085ee438b7813e928d0c7" }, "version": "3.0.2" }, "com.google.errorprone:error_prone_annotations": { "shasums": { "jar": "721cb91842b46fa056847d104d5225c8b8e1e8b62263b993051e1e5a0137b7ec" }, "version": "2.11.0" }, "com.google.escapevelocity:escapevelocity": { "shasums": { "jar": "37e76e4466836dedb864fb82355cd01c3bd21325ab642d89a0f759291b171231" }, "version": "1.1" }, "com.google.guava:failureaccess": { "shasums": { "jar": "a171ee4c734dd2da837e4b16be9df4661afab72a41adaf31eb84dfdaf936ca26" }, "version": "1.0.1" }, "com.google.guava:guava": { "shasums": { "jar": "a42edc9cab792e39fe39bb94f3fca655ed157ff87a8af78e1d6ba5b07c4a00ab" }, "version": "31.1-jre" }, "com.google.guava:listenablefuture": { "shasums": { "jar": "b372a037d4230aa57fbeffdef30fd6123f9c0c2db85d0aced00c91b974f33f99" }, "version": "9999.0-empty-to-avoid-conflict-with-guava" }, "com.google.j2objc:j2objc-annotations": { "shasums": { "jar": "21af30c92267bd6122c0e0b4d20cccb6641a37eaf956c6540ec471d584e64a7b" }, "version": "1.3" }, "com.google.truth:truth": { "shasums": { "jar": "fc0b67782289a2aabfddfdf99eff1dcd5edc890d49143fcd489214b107b8f4f3" }, "version": "1.1.3" }, "junit:junit": { "shasums": { "jar": "8e495b634469d64fb8acfa3495a065cbacc8a0fff55ce1e31007be4c16dc57d3" }, "version": "4.13.2" }, "org.checkerframework:checker-qual": { "shasums": { "jar": "3ea0dcd73b4d6cb2fb34bd7ed4dad6db327a01ebad7db05eb7894076b3d64491" }, "version": "3.13.0" }, "org.hamcrest:hamcrest-core": { "shasums": { "jar": "66fdef91e9739348df7a096aa384a5685f4e875584cce89386a7a47251c4d8e9" }, "version": "1.3" }, "org.ow2.asm:asm": { "shasums": { "jar": "cda4de455fab48ff0bcb7c48b4639447d4de859a7afc30a094a986f0936beba2" }, "version": "9.1" } }, "dependencies": { "com.google.escapevelocity:escapevelocity": [ "com.google.guava:guava" ], "com.google.guava:guava": [ "com.google.code.findbugs:jsr305", "com.google.errorprone:error_prone_annotations", "com.google.guava:failureaccess", "com.google.guava:listenablefuture", "com.google.j2objc:j2objc-annotations", "org.checkerframework:checker-qual" ], "com.google.truth:truth": [ "com.google.auto.value:auto-value-annotations", "com.google.errorprone:error_prone_annotations", "com.google.guava:guava", "junit:junit", "org.checkerframework:checker-qual", "org.ow2.asm:asm" ], "junit:junit": [ "org.hamcrest:hamcrest-core" ] }, "packages": { "com.beust:jcommander": [ "com.beust.ah", "com.beust.jcommander", "com.beust.jcommander.converters", "com.beust.jcommander.defaultprovider", "com.beust.jcommander.internal", "com.beust.jcommander.parser", "com.beust.jcommander.validators" ], "com.google.auto.value:auto-value-annotations": [ "com.google.auto.value", "com.google.auto.value.extension.memoized", "com.google.auto.value.extension.serializable", "com.google.auto.value.extension.toprettystring" ], "com.google.code.findbugs:jsr305": [ "javax.annotation", "javax.annotation.concurrent", "javax.annotation.meta" ], "com.google.errorprone:error_prone_annotations": [ "com.google.errorprone.annotations", "com.google.errorprone.annotations.concurrent" ], "com.google.escapevelocity:escapevelocity": [ "com.google.escapevelocity" ], "com.google.guava:failureaccess": [ "com.google.common.util.concurrent.internal" ], "com.google.guava:guava": [ "com.google.common.annotations", "com.google.common.base", "com.google.common.base.internal", "com.google.common.cache", "com.google.common.collect", "com.google.common.escape", "com.google.common.eventbus", "com.google.common.graph", "com.google.common.hash", "com.google.common.html", "com.google.common.io", "com.google.common.math", "com.google.common.net", "com.google.common.primitives", "com.google.common.reflect", "com.google.common.util.concurrent", "com.google.common.xml", "com.google.thirdparty.publicsuffix" ], "com.google.j2objc:j2objc-annotations": [ "com.google.j2objc.annotations" ], "com.google.truth:truth": [ "com.google.common.truth" ], "junit:junit": [ "junit.extensions", "junit.framework", "junit.runner", "junit.textui", "org.junit", "org.junit.experimental", "org.junit.experimental.categories", "org.junit.experimental.max", "org.junit.experimental.results", "org.junit.experimental.runners", "org.junit.experimental.theories", "org.junit.experimental.theories.internal", "org.junit.experimental.theories.suppliers", "org.junit.function", "org.junit.internal", "org.junit.internal.builders", "org.junit.internal.management", "org.junit.internal.matchers", "org.junit.internal.requests", "org.junit.internal.runners", "org.junit.internal.runners.model", "org.junit.internal.runners.rules", "org.junit.internal.runners.statements", "org.junit.matchers", "org.junit.rules", "org.junit.runner", "org.junit.runner.manipulation", "org.junit.runner.notification", "org.junit.runners", "org.junit.runners.model", "org.junit.runners.parameterized", "org.junit.validator" ], "org.checkerframework:checker-qual": [ "org.checkerframework.checker.builder.qual", "org.checkerframework.checker.calledmethods.qual", "org.checkerframework.checker.compilermsgs.qual", "org.checkerframework.checker.fenum.qual", "org.checkerframework.checker.formatter.qual", "org.checkerframework.checker.guieffect.qual", "org.checkerframework.checker.i18n.qual", "org.checkerframework.checker.i18nformatter.qual", "org.checkerframework.checker.index.qual", "org.checkerframework.checker.initialization.qual", "org.checkerframework.checker.interning.qual", "org.checkerframework.checker.lock.qual", "org.checkerframework.checker.nullness.qual", "org.checkerframework.checker.optional.qual", "org.checkerframework.checker.propkey.qual", "org.checkerframework.checker.regex.qual", "org.checkerframework.checker.signature.qual", "org.checkerframework.checker.signedness.qual", "org.checkerframework.checker.tainting.qual", "org.checkerframework.checker.units.qual", "org.checkerframework.common.aliasing.qual", "org.checkerframework.common.initializedfields.qual", "org.checkerframework.common.reflection.qual", "org.checkerframework.common.returnsreceiver.qual", "org.checkerframework.common.subtyping.qual", "org.checkerframework.common.util.report.qual", "org.checkerframework.common.value.qual", "org.checkerframework.dataflow.qual", "org.checkerframework.framework.qual" ], "org.hamcrest:hamcrest-core": [ "org.hamcrest", "org.hamcrest.core", "org.hamcrest.internal" ], "org.ow2.asm:asm": [ "org.objectweb.asm", "org.objectweb.asm.signature" ] }, "repositories": { "https://repo1.maven.org/maven2/": [ "com.beust:jcommander", "com.google.auto.value:auto-value-annotations", "com.google.code.findbugs:jsr305", "com.google.errorprone:error_prone_annotations", "com.google.escapevelocity:escapevelocity", "com.google.guava:failureaccess", "com.google.guava:guava", "com.google.guava:listenablefuture", "com.google.j2objc:j2objc-annotations", "com.google.truth:truth", "junit:junit", "org.checkerframework:checker-qual", "org.hamcrest:hamcrest-core", "org.ow2.asm:asm" ] }, "services": {}, "version": "2" } stardoc-0.8.1/setup.bzl000066400000000000000000000114411513642521100150310ustar00rootroot00000000000000# Copyright 2019 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """WORKSPACE prerequisites for Stardoc.""" load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe") def stardoc_repositories(): """Adds the external repositories for rules used by Stardoc.""" maybe( http_archive, name = "bazel_skylib", sha256 = "bc283cdfcd526a52c3201279cda4bc298652efa898b10b4db0837dc51652756f", urls = [ "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.7.1/bazel-skylib-1.7.1.tar.gz", "https://github.com/bazelbuild/bazel-skylib/releases/download/1.7.1/bazel-skylib-1.7.1.tar.gz", ], ) maybe( http_archive, name = "com_google_protobuf", sha256 = "2e442d21839ec9dbafda4cc9083239aa04e78fc9c27dfa59b5374e968050cd22", strip_prefix = "protobuf-29.0", urls = [ "https://mirror.bazel.build/github.com/protocolbuffers/protobuf/releases/download/v29.0/protobuf-29.0.zip", "https://github.com/protocolbuffers/protobuf/releases/download/v29.0/protobuf-29.0.zip", ], ) maybe( http_archive, name = "rules_java", sha256 = "c5bc17e17bb62290b1fd8fdd847a2396d3459f337a7e07da7769b869b488ec26", url = "https://github.com/bazelbuild/rules_java/releases/download/8.6.1/rules_java-8.6.1.tar.gz", ) # Transitive dep of rules_java, needs to be manually specified when not using bzlmod # See https://github.com/bazelbuild/bazel/issues/21877 maybe( http_archive, name = "platforms", urls = [ "https://mirror.bazel.build/github.com/bazelbuild/platforms/releases/download/1.0.0/platforms-1.0.0.tar.gz", "https://github.com/bazelbuild/platforms/releases/download/1.0.0/platforms-1.0.0.tar.gz", ], sha256 = "3384eb1c30762704fbe38e440204e114154086c8fc8a8c2e3e28441028c019a8", ) RULES_JVM_EXTERNAL_TAG = "6.6" RULES_JVM_EXTERNAL_SHA = "3afe5195069bd379373528899c03a3072f568d33bd96fe037bd43b1f590535e7" maybe( http_archive, name = "rules_jvm_external", strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG, sha256 = RULES_JVM_EXTERNAL_SHA, url = "https://github.com/bazelbuild/rules_jvm_external/releases/download/%s/rules_jvm_external-%s.tar.gz" % (RULES_JVM_EXTERNAL_TAG, RULES_JVM_EXTERNAL_TAG), ) maybe( http_archive, name = "rules_license", sha256 = "26d4021f6898e23b82ef953078389dd49ac2b5618ac564ade4ef87cced147b38", urls = [ "https://mirror.bazel.build/github.com/bazelbuild/rules_license/releases/download/1.0.0/rules_license-1.0.0.tar.gz", "https://github.com/bazelbuild/rules_license/releases/download/1.0.0/rules_license-1.0.0.tar.gz", ], ) # Transitive dep of com_google_protobuf. Unfortunately, protobuf_deps() # pulls in a dep that's too old. maybe( http_archive, name = "rules_proto", sha256 = "6fb6767d1bef535310547e03247f7518b03487740c11b6c6adb7952033fe1295", strip_prefix = "rules_proto-6.0.2", url = "https://github.com/bazelbuild/rules_proto/releases/download/6.0.2/rules_proto-6.0.2.tar.gz", ) # Transitive dep of rules_proto. Pull in explicitly to allow calling both # rules_proto_dependencies() and rules_proto_setup() in stardoc_external_deps() without forcing # users to add yet another intermediate load() in their WORKSPACE files. maybe( http_archive, name = "bazel_features", sha256 = "0f23d75c7623d6dba1fd30513a94860447de87c8824570521fcc966eda3151c2", strip_prefix = "bazel_features-1.4.1", url = "https://github.com/bazel-contrib/bazel_features/releases/download/v1.4.1/bazel_features-v1.4.1.tar.gz", ) # Transitive dep of com_google_protobuf. Unfortunately, protobuf_deps() # pulls in a dep that's too old. maybe( http_archive, name = "rules_python", sha256 = "690e0141724abb568267e003c7b6d9a54925df40c275a870a4d934161dc9dd53", strip_prefix = "rules_python-0.40.0", url = "https://github.com/bazelbuild/rules_python/releases/download/0.40.0/rules_python-0.40.0.tar.gz", ) stardoc-0.8.1/src/000077500000000000000000000000001513642521100137465ustar00rootroot00000000000000stardoc-0.8.1/src/main/000077500000000000000000000000001513642521100146725ustar00rootroot00000000000000stardoc-0.8.1/src/main/java/000077500000000000000000000000001513642521100156135ustar00rootroot00000000000000stardoc-0.8.1/src/main/java/com/000077500000000000000000000000001513642521100163715ustar00rootroot00000000000000stardoc-0.8.1/src/main/java/com/google/000077500000000000000000000000001513642521100176455ustar00rootroot00000000000000stardoc-0.8.1/src/main/java/com/google/devtools/000077500000000000000000000000001513642521100215045ustar00rootroot00000000000000stardoc-0.8.1/src/main/java/com/google/devtools/build/000077500000000000000000000000001513642521100226035ustar00rootroot00000000000000stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/000077500000000000000000000000001513642521100242425ustar00rootroot00000000000000stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/renderer/000077500000000000000000000000001513642521100260505ustar00rootroot00000000000000stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/renderer/BUILD000066400000000000000000000021631513642521100266340ustar00rootroot00000000000000load("@rules_java//java:defs.bzl", "java_binary", "java_library") package(default_applicable_licenses = ["//:license"]) filegroup( name = "srcs", srcs = glob(["**"]), visibility = ["//:__pkg__"], ) java_binary( name = "renderer", jvm_flags = [ # quiet warnings from com.google.protobuf.UnsafeUtil, # see: https://github.com/google/protobuf/issues/3781 # and: https://github.com/bazelbuild/bazel/issues/5599 "--add-opens=java.base/java.nio=ALL-UNNAMED", "--add-opens=java.base/java.lang=ALL-UNNAMED", # ... but only on JDK >= 9 "-XX:+IgnoreUnrecognizedVMOptions", ], main_class = "com.google.devtools.build.stardoc.renderer.RendererMain", visibility = ["//visibility:public"], runtime_deps = [ ":renderer_lib", ], ) java_library( name = "renderer_lib", srcs = glob(["*.java"]), deps = [ "//src/main/java/com/google/devtools/build/stardoc/rendering", "//stardoc/proto:stardoc_output_java_proto", "@stardoc_maven//:com_beust_jcommander", "@stardoc_maven//:com_google_guava_guava", ], ) stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/renderer/FileSystemAccessor.java000066400000000000000000000030721513642521100324640ustar00rootroot00000000000000// Copyright 2019 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.stardoc.renderer; import java.io.FileOutputStream; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; /** Implementation of {@link ProtoFileAccessor} which uses the real filesystem. */ public class FileSystemAccessor implements ProtoFileAccessor { @Override public byte[] getProtoContent(String inputPathString) throws IOException { Path inputPath = Paths.get(inputPathString); byte[] inputContent = Files.readAllBytes(inputPath); return inputContent; } @Override public boolean fileExists(String pathString) { return Files.exists(Paths.get(pathString)); } @Override public void writeToOutputLocation(String outputPathString, byte[] content) throws IOException { try (FileOutputStream outputStream = new FileOutputStream(outputPathString)) { for (byte byteContent : content) { outputStream.write(byteContent); } } } } stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/renderer/ProtoFileAccessor.java000066400000000000000000000031121513642521100322760ustar00rootroot00000000000000// Copyright 2019 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.stardoc.renderer; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos; import java.io.FileOutputStream; import java.io.IOException; /** * Helper to handle Proto file I/O. This abstraction is useful for tests which don't involve actual * file I/O. */ public interface ProtoFileAccessor { /** * Returns the bytes from the raw proto file. * * @param inputPathString the path of the input raw {@link StardocOutputProtos} file. */ byte[] getProtoContent(String inputPathString) throws IOException; /** Returns true if a file exists at the current path. */ boolean fileExists(String pathString); /** * Creates a {@link FileOutputStream} and writes the bytes to the output location. * * @param outputPathString the output location that is being written to * @param content the bytes from input proto file */ void writeToOutputLocation(String outputPathString, byte[] content) throws IOException; } stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/renderer/RendererMain.java000066400000000000000000000362231513642521100312740ustar00rootroot00000000000000// Copyright 2019 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.stardoc.renderer; import static com.google.common.collect.ImmutableList.toImmutableList; import static com.google.common.collect.ImmutableSet.toImmutableSet; import static java.nio.charset.StandardCharsets.UTF_8; import static java.util.Comparator.comparing; import com.beust.jcommander.JCommander; import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; import com.google.common.collect.ImmutableSet; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AspectInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AttributeInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.MacroInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionTagClassInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RepositoryRuleInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RuleInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.StarlarkFunctionInfo; import com.google.devtools.build.stardoc.rendering.MarkdownRenderer; import com.google.devtools.build.stardoc.rendering.MarkdownRenderer.Renderer; import com.google.devtools.build.stardoc.rendering.Stamping; import java.io.FileInputStream; import java.io.IOException; import java.io.PrintWriter; import java.util.ArrayList; import java.util.Comparator; import java.util.List; import java.util.Optional; /** * Main entry point for Renderer binary. * *

This Renderer takes in raw stardoc_proto protos as input and produces rich markdown output. */ public final class RendererMain { @SuppressWarnings("ProtoParseWithRegistry") // See https://github.com/bazelbuild/stardoc/pull/221 public static void main(String[] args) throws IOException { RendererOptions rendererOptions = new RendererOptions(); JCommander jcommander = JCommander.newBuilder().addObject(rendererOptions).build(); jcommander.setProgramName("renderer"); jcommander.parse(args); if (rendererOptions.printHelp) { jcommander.usage(); return; } String inputPath = rendererOptions.inputPath; String outputPath = rendererOptions.outputFilePath; Stamping stamping; if (rendererOptions.stampingStableStatusFilePath != null && rendererOptions.stampingVolatileStatusFilePath != null) { stamping = Stamping.read( rendererOptions.stampingStableStatusFilePath, rendererOptions.stampingVolatileStatusFilePath); } else { stamping = Stamping.empty(); } try (PrintWriter printWriter = new PrintWriter(outputPath, UTF_8) { // Use consistent line endings on all platforms. @Override public void println() { write("\n"); } }) { ModuleInfo moduleInfo = ModuleInfo.parseFrom(new FileInputStream(inputPath)); MarkdownRenderer renderer = new MarkdownRenderer( rendererOptions.headerTemplateFilePath, rendererOptions.tableOfContentsTemplateFilePath, rendererOptions.ruleTemplateFilePath, rendererOptions.providerTemplateFilePath, rendererOptions.funcTemplateFilePath, rendererOptions.macroTemplateFilePath, rendererOptions.aspectTemplateFilePath, rendererOptions.repositoryRuleTemplateFilePath, rendererOptions.moduleExtensionTemplateFilePath, !moduleInfo.getFile().isEmpty() ? Optional.of(moduleInfo.getFile()) : Optional.empty(), rendererOptions.footerTemplateFilePath, stamping); // rules are printed sorted by their qualified name, and their attributes are sorted by name, // with ATTRIBUTE_ORDERING specifying a fixed sort order for some standard attributes. ImmutableList sortedRuleInfos = moduleInfo.getRuleInfoList().stream() .map(RendererMain::withSortedRuleAttributes) .sorted(comparing(RuleInfo::getRuleName)) .collect(toImmutableList()); // providers are printed sorted by their qualified name. ImmutableList sortedProviderInfos = ImmutableList.sortedCopyOf( comparing(ProviderInfo::getProviderName), moduleInfo.getProviderInfoList()); // functions are printed sorted by their qualified name. ImmutableList sortedStarlarkFunctions = ImmutableList.sortedCopyOf( comparing(StarlarkFunctionInfo::getFunctionName), moduleInfo.getFuncInfoList()); // symbolic macros are printed sorted by their qualified name, and their attributes are sorted // by name, with ATTRIBUTE_ORDERING specifying a fixed sort order for some standard // attributes. ImmutableList sortedMacroInfos = moduleInfo.getMacroInfoList().stream() .map(RendererMain::withSortedMacroAttributes) .sorted(comparing(MacroInfo::getMacroName)) .collect(toImmutableList()); // aspects are printed sorted by their qualified name. ImmutableList sortedAspectInfos = ImmutableList.sortedCopyOf( comparing(AspectInfo::getAspectName), moduleInfo.getAspectInfoList()); // Repository rules are printed sorted by their qualified name, and their attributes are // sorted by name, with ATTRIBUTE_ORDERING specifying a fixed sort order for some standard // attributes. ImmutableList sortedRepositoryRuleInfos = moduleInfo.getRepositoryRuleInfoList().stream() .map(RendererMain::withSortedRuleAttributes) .sorted(comparing(RepositoryRuleInfo::getRuleName)) .collect(toImmutableList()); // Module extension are printed sorted by their qualified name, and their tag classes' // attributes are sorted by name, with ATTRIBUTE_ORDERING specifying a fixed sort order for // some standard attributes. ImmutableList sortedModuleExtensionInfos = moduleInfo.getModuleExtensionInfoList().stream() .map(RendererMain::withSortedTagAttributes) .sorted(comparing(ModuleExtensionInfo::getExtensionName)) .collect(toImmutableList()); printWriter.println(renderer.renderMarkdownHeader(moduleInfo)); if (rendererOptions.tableOfContentsTemplateFilePath != null) { printWriter.println( renderer.renderTableOfContents( sortedRuleInfos, sortedProviderInfos, sortedMacroInfos, sortedStarlarkFunctions, sortedAspectInfos, sortedRepositoryRuleInfos, sortedModuleExtensionInfos)); } print(printWriter, renderer::render, sortedRuleInfos); print(printWriter, renderer::render, sortedProviderInfos); print(printWriter, renderer::render, sortedStarlarkFunctions); print(printWriter, renderer::render, sortedMacroInfos); print(printWriter, renderer::render, sortedAspectInfos); print(printWriter, renderer::render, sortedRepositoryRuleInfos); print(printWriter, renderer::render, sortedModuleExtensionInfos); if (rendererOptions.footerTemplateFilePath != null) { printWriter.println(renderer.renderMarkdownFooter(moduleInfo)); } } catch (IOException e) { // Avoid an explicit dependency on the Java protobuf runtime as it should be injected by the // root module via a proto_lang_toolchain. if (e.getClass().getName().equals("com.google.protobuf.InvalidProtocolBufferException")) { throw new IllegalArgumentException("Input file is not a valid ModuleInfo proto.", e); } else { throw e; } } } private static void print(PrintWriter printWriter, Renderer renderer, List infos) throws IOException { for (T info : infos) { printWriter.println(renderer.render(info)); printWriter.println(); } } // A copy of com.google.devtools.build.docgen.DocgenConsts.ATTRIBUTE_ORDERING - we duplicate the // ordering here because we intend to move this file from the Bazel tree to the Stardoc repo. private static final ImmutableMap ATTRIBUTE_ORDERING = ImmutableMap.builder() .put("name", -99) .put("deps", -98) .put("src", -97) .put("srcs", -96) .put("data", -95) .put("resource", -94) .put("resources", -93) .put("out", -92) .put("outs", -91) .put("hdrs", -90) .buildOrThrow(); private static final Comparator ATTRIBUTE_NAME_COMPARATOR = (a, b) -> { int aOrdering = ATTRIBUTE_ORDERING.getOrDefault(a, 0); int bOrdering = ATTRIBUTE_ORDERING.getOrDefault(b, 0); if (aOrdering > bOrdering) { return 1; } else if (aOrdering < bOrdering) { return -1; } else { return Comparator.naturalOrder().compare(a, b); } }; private static RuleInfo withSortedRuleAttributes(RuleInfo ruleInfo) { return ruleInfo.toBuilder() .clearAttribute() .addAllAttribute( ImmutableList.sortedCopyOf( comparing(AttributeInfo::getName, ATTRIBUTE_NAME_COMPARATOR), ruleInfo.getAttributeList())) .build(); } private static RepositoryRuleInfo withSortedRuleAttributes( RepositoryRuleInfo repositoryRuleInfo) { return repositoryRuleInfo.toBuilder() .clearAttribute() .addAllAttribute( ImmutableList.sortedCopyOf( comparing(AttributeInfo::getName, ATTRIBUTE_NAME_COMPARATOR), repositoryRuleInfo.getAttributeList())) .build(); } private static MacroInfo withSortedMacroAttributes(MacroInfo macroInfo) { boolean inheritsFromTest = inheritsFromTestRule(macroInfo); ArrayList attributes = new ArrayList<>(macroInfo.getAttributeList().size() + 1); for (AttributeInfo attributeInfo : macroInfo.getAttributeList()) { if (attributeInfo.getNativelyDefined() && attributeInfo.getDocString().isEmpty()) { // inject doc string for undocumented inherited native attributes String docString = "Inherited rule attribute"; if (COMMON_UNDOCUMENTED_ATTR_NAMES.contains(attributeInfo.getName())) { continue; } else if (COMMON_BASE_ATTR_NAMES.contains(attributeInfo.getName())) { docString = String.format( "%s", attributeInfo.getName(), docString); } else if (inheritsFromTest && COMMON_TEST_ATTR_NAMES.contains(attributeInfo.getName())) { docString = String.format( "%s", attributeInfo.getName(), docString); } else if (COMMON_BINARY_ATTR_NAMES.contains(attributeInfo.getName())) { docString = String.format( "%s", attributeInfo.getName(), docString); } attributes.add(attributeInfo.toBuilder().setDocString(docString).build()); } else { attributes.add(attributeInfo); } } return macroInfo.toBuilder() .clearAttribute() .addAllAttribute( ImmutableList.sortedCopyOf( comparing(AttributeInfo::getName, ATTRIBUTE_NAME_COMPARATOR), attributes)) .build(); } private static final ImmutableSet COMMON_BASE_ATTR_NAMES = ImmutableSet.of( "aspect_hints", "compatible_with", "deprecation", "distribs", "exec_compatible_with", "exec_group_compatible_with", "exec_properties", "features", "package_metadata", "restricted_to", "tags", "target_compatible_with", "testonly", "toolchains", "visibility"); private static final ImmutableSet COMMON_TEST_ATTR_NAMES = ImmutableSet.of( "args", "env", "env_inherit", "size", "timeout", "flaky", "shard_count", "local"); private static final ImmutableSet COMMON_BINARY_ATTR_NAMES = ImmutableSet.of("args", "env", "output_licenses"); // TODO(https://github.com/bazelbuild/bazel/issues/24948): Bazel should explicitly mark these as // undocumented, so we wouldn't need to filter them out. private static final ImmutableSet COMMON_UNDOCUMENTED_ATTR_NAMES = ImmutableSet.of("expect_failure", "transitive_configs"); /** * Heuristically guesses whether the given macro inherits attributes from a test rule (as opposed * to, for example, a binary rule). */ private static boolean inheritsFromTestRule(MacroInfo macroInfo) { ImmutableSet inheritedAttrs = macroInfo.getAttributeList().stream() .filter(AttributeInfo::getNativelyDefined) .map(AttributeInfo::getName) .collect(toImmutableSet()); for (String testAttrName : COMMON_TEST_ATTR_NAMES) { if (!COMMON_BINARY_ATTR_NAMES.contains(testAttrName) && inheritedAttrs.contains(testAttrName)) { return true; } } return false; } private static ModuleExtensionTagClassInfo withSortedTagAttributes( ModuleExtensionTagClassInfo moduleExtensionTagClassInfo) { return moduleExtensionTagClassInfo.toBuilder() .clearAttribute() .addAllAttribute( ImmutableList.sortedCopyOf( comparing(AttributeInfo::getName, ATTRIBUTE_NAME_COMPARATOR), moduleExtensionTagClassInfo.getAttributeList())) .build(); } private static ModuleExtensionInfo withSortedTagAttributes( ModuleExtensionInfo moduleExtensionInfo) { return moduleExtensionInfo.toBuilder() .clearTagClass() .addAllTagClass( moduleExtensionInfo.getTagClassList().stream() .map(RendererMain::withSortedTagAttributes) .collect(toImmutableList())) .build(); } private RendererMain() {} } stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/renderer/RendererOptions.java000066400000000000000000000065571513642521100320520ustar00rootroot00000000000000// Copyright 2023 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.stardoc.renderer; import com.beust.jcommander.Parameter; import com.beust.jcommander.Parameters; /** Contains options for running {@link RendererMain}. */ @Parameters(separators = "=") class RendererOptions { @Parameter( names = "--input", required = true, description = "The path of the proto file that will be converted to markdown") String inputPath; @Parameter( names = "--output", required = true, description = "The path of the file to output documentation into") String outputFilePath; @Parameter( names = "--header_template", required = true, description = "The template for the header string") String headerTemplateFilePath; @Parameter( names = "--table_of_contents_template", description = "The template for the table of contents string") String tableOfContentsTemplateFilePath; @Parameter( names = "--rule_template", required = true, description = "The template for the documentation of a rule") String ruleTemplateFilePath; @Parameter( names = "--provider_template", required = true, description = "The template for the documentation of a provider") String providerTemplateFilePath; @Parameter( names = "--func_template", required = true, description = "The template for the documentation of a function") String funcTemplateFilePath; @Parameter( names = "--macro_template", required = true, description = "The template for the documentation of a symbolic macro") String macroTemplateFilePath; @Parameter( names = "--aspect_template", required = true, description = "The template for the documentation of an aspect") String aspectTemplateFilePath; @Parameter( names = "--repository_rule_template", required = true, description = "The template for the documentation of a repository rule") String repositoryRuleTemplateFilePath; @Parameter( names = "--module_extension_template", required = true, description = "The template for the documentation of a module extension") String moduleExtensionTemplateFilePath; @Parameter(names = "--footer_template", description = "The template for the footer string") String footerTemplateFilePath; @Parameter( names = "--stamping_stable_status_file", description = "The file path to the stable status file for stamping") String stampingStableStatusFilePath; @Parameter( names = "--stamping_volatile_status_file", description = "The file path to the volatile status file for stamping") String stampingVolatileStatusFilePath; @Parameter( names = {"--help", "-h"}, description = "Print help and exit", help = true) boolean printHelp; } stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/rendering/000077500000000000000000000000001513642521100262175ustar00rootroot00000000000000stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/rendering/BUILD000066400000000000000000000010261513642521100270000ustar00rootroot00000000000000load("@rules_java//java:defs.bzl", "java_library") package( default_applicable_licenses = ["//:license"], default_visibility = ["//src:__subpackages__"], ) filegroup( name = "srcs", srcs = glob(["**"]), visibility = ["//:__pkg__"], ) java_library( name = "rendering", srcs = glob( ["*.java"], ), deps = [ "//stardoc/proto:stardoc_output_java_proto", "@stardoc_maven//:com_google_escapevelocity_escapevelocity", "@stardoc_maven//:com_google_guava_guava", ], ) stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java000066400000000000000000000365751513642521100323530ustar00rootroot00000000000000// Copyright 2018 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.stardoc.rendering; import static com.google.common.collect.ImmutableList.toImmutableList; import static com.google.common.collect.ImmutableSet.toImmutableSet; import static java.nio.charset.StandardCharsets.UTF_8; import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AspectInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.FunctionParamInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.MacroInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderFieldInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RepositoryRuleInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RuleInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.StarlarkFunctionInfo; import com.google.escapevelocity.EvaluationException; import com.google.escapevelocity.ParseException; import com.google.escapevelocity.Template; import java.io.FileNotFoundException; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; import java.io.Reader; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.List; import java.util.Optional; /** Produces stardoc output in markdown form. */ public class MarkdownRenderer { public interface Renderer { String render(T info) throws IOException; } // TODO(kendalllane): Refactor MarkdownRenderer to take in something other than filepaths. private final String headerTemplateFilename; private final String tableOfContentsTemplateFilename; private final String ruleTemplateFilename; private final String providerTemplateFilename; private final String functionTemplateFilename; private final String macroTemplateFilename; private final String aspectTemplateFilename; private final String repositoryRuleTemplateFilename; private final String moduleExtensionTemplateFilename; private final Optional entrypointBzlFile; private final String footerTemplateFilename; private final Stamping stamping; public MarkdownRenderer( String headerTemplate, String tableOfContentsTemplateFilename, String ruleTemplate, String providerTemplate, String functionTemplate, String macroTemplate, String aspectTemplate, String repositoryRuleTemplate, String moduleExtensionTemplate, Optional entrypointBzlFile, String footerTemplate, Stamping stamping) { this.headerTemplateFilename = headerTemplate; this.tableOfContentsTemplateFilename = tableOfContentsTemplateFilename; this.ruleTemplateFilename = ruleTemplate; this.providerTemplateFilename = providerTemplate; this.functionTemplateFilename = functionTemplate; this.macroTemplateFilename = macroTemplate; this.aspectTemplateFilename = aspectTemplate; this.repositoryRuleTemplateFilename = repositoryRuleTemplate; this.moduleExtensionTemplateFilename = moduleExtensionTemplate; this.entrypointBzlFile = entrypointBzlFile; this.footerTemplateFilename = footerTemplate; this.stamping = stamping; } /** * Returns a markdown header string that should appear at the top of Stardoc's output, providing a * summary for the input Starlark module. */ public String renderMarkdownHeader(ModuleInfo moduleInfo) throws IOException { ImmutableMap vars = ImmutableMap.of( "util", new MarkdownUtil(entrypointBzlFile), "moduleDocstring", moduleInfo.getModuleDocstring(), "stamping", stamping); Reader reader = readerFromPath(headerTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } /** * Returns a markdown string of a Table of Contents, appearing after the header and before the * documentation. */ public String renderTableOfContents( List ruleInfos, List providerInfos, List macroInfos, List starlarkFunctions, List aspectInfos, List repositoryRuleInfos, List moduleExtensionInfos) throws IOException { ImmutableMap vars = ImmutableMap.of( "util", new MarkdownUtil(entrypointBzlFile), "ruleInfos", ruleInfos, "providerInfos", providerInfos, "macroInfos", macroInfos, "functionInfos", starlarkFunctions, "aspectInfos", aspectInfos, "repositoryRuleInfos", repositoryRuleInfos, "moduleExtensionInfos", moduleExtensionInfos); Reader reader = readerFromPath(tableOfContentsTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } /** * Returns a markdown rendering of rule documentation for the given rule information object with * the given rule name. */ public String render(RuleInfo ruleInfo) throws IOException { ImmutableMap vars = ImmutableMap.of( "util", new MarkdownUtil(entrypointBzlFile), "ruleName", ruleInfo.getRuleName(), "ruleInfo", ruleInfo); Reader reader = readerFromPath(ruleTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } /** * Returns a markdown rendering of provider documentation for the given provider information * object with the given name. * *

For evaluating the provider template, populates the the following constants: * *

    *
  • util - a {@link MarkdownUtil} object *
  • providerName - the provider's name *
  • providerInfo - the {@link ProviderInfo} proto *
  • initParamsWithInferredDocs - the list of the init callback's {@link FunctionParamInfo} * protos, with any undocumented parameters inheriting the doc string of the provider's * field with the same name; or an empty list of the provider doesn't have an init callback *
  • initParamNamesEqualFieldNames - true iff the provider has an init callback and the set of * names of the init callback's parameters equals the set of names of the provider's fields *
  • initParamsHaveDefaultValues - true iff the provider has an init callback and at least one * of the init callback's parameters has a default value specified *
  • initParamsHaveDistinctDocs - true iff the provider has an init callback and at least one * of the init callback's parameters has a docstring which is non-empty and not equal to the * corresponding field's docstring. *
*/ public String render(ProviderInfo providerInfo) throws IOException { ImmutableMap.Builder fieldDocsBuilder = ImmutableMap.builder(); for (ProviderFieldInfo fieldInfo : providerInfo.getFieldInfoList()) { fieldDocsBuilder.put(fieldInfo.getName(), fieldInfo.getDocString()); } ImmutableMap fieldDocs = fieldDocsBuilder.buildOrThrow(); ImmutableList initParamsWithInferredDocs; if (providerInfo.hasInit()) { initParamsWithInferredDocs = providerInfo.getInit().getParameterList().stream() .map(param -> withInferredDoc(param, fieldDocs)) .collect(toImmutableList()); } else { initParamsWithInferredDocs = ImmutableList.of(); } boolean initParamNamesEqualFieldNames = providerInfo.hasInit() && providerInfo.getInit().getParameterList().stream() .map(FunctionParamInfo::getName) .collect(toImmutableSet()) .equals( providerInfo.getFieldInfoList().stream() .map(ProviderFieldInfo::getName) .collect(toImmutableSet())); boolean initParamsHaveDefaultValues = providerInfo.hasInit() && providerInfo.getInit().getParameterList().stream() .filter(param -> !param.getDefaultValue().isEmpty()) .findFirst() .isPresent(); boolean initParamsHaveDistinctDocs = providerInfo.hasInit() && providerInfo.getInit().getParameterList().stream() .filter( param -> !param.getDocString().isEmpty() && !param.getDocString().equals(fieldDocs.get(param.getName()))) .findFirst() .isPresent(); ImmutableMap vars = ImmutableMap.of( "util", new MarkdownUtil(entrypointBzlFile), "providerName", providerInfo.getProviderName(), "providerInfo", providerInfo, "initParamsWithInferredDocs", initParamsWithInferredDocs, "initParamNamesEqualFieldNames", initParamNamesEqualFieldNames, "initParamsHaveDefaultValues", initParamsHaveDefaultValues, "initParamsHaveDistinctDocs", initParamsHaveDistinctDocs); Reader reader = readerFromPath(providerTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } /** * Returns a markdown rendering of a user-defined function's documentation for the function info * object. */ public String render(StarlarkFunctionInfo functionInfo) throws IOException { ImmutableMap vars = ImmutableMap.of("util", new MarkdownUtil(entrypointBzlFile), "funcInfo", functionInfo); Reader reader = readerFromPath(functionTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } /** Returns a markdown rendering of a symbolic macro's documentation for the macro info object. */ public String render(MacroInfo macroInfo) throws IOException { ImmutableMap vars = ImmutableMap.of( "util", new MarkdownUtil(entrypointBzlFile), "macroName", macroInfo.getMacroName(), "macroInfo", macroInfo); Reader reader = readerFromPath(macroTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } /** * Returns a markdown rendering of aspect documentation for the given aspect information object * with the given aspect name. */ public String render(AspectInfo aspectInfo) throws IOException { ImmutableMap vars = ImmutableMap.of( "util", new MarkdownUtil(entrypointBzlFile), "aspectName", aspectInfo.getAspectName(), "aspectInfo", aspectInfo); Reader reader = readerFromPath(aspectTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } /** * Returns a markdown rendering of repository rule documentation for the given repository rule * information object with the given name. */ public String render(RepositoryRuleInfo repositoryRuleInfo) throws IOException { ImmutableMap vars = ImmutableMap.of( "util", new MarkdownUtil(entrypointBzlFile), "ruleName", repositoryRuleInfo.getRuleName(), "ruleInfo", repositoryRuleInfo); Reader reader = readerFromPath(repositoryRuleTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } /** * Returns a markdown rendering of module extension documentation for the given module extension * information object with the given name. */ public String render(ModuleExtensionInfo moduleExtensionInfo) throws IOException { ImmutableMap vars = ImmutableMap.of( "util", new MarkdownUtil(entrypointBzlFile), "extensionName", moduleExtensionInfo.getExtensionName(), "extensionInfo", moduleExtensionInfo); Reader reader = readerFromPath(moduleExtensionTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } /** Returns a markdown header string that should appear at the end of Stardoc's output. */ public String renderMarkdownFooter(ModuleInfo moduleInfo) throws IOException { ImmutableMap vars = ImmutableMap.of("util", new MarkdownUtil(entrypointBzlFile), "stamping", stamping); Reader reader = readerFromPath(footerTemplateFilename); try { return Template.parseFrom(reader).evaluate(vars); } catch (ParseException | EvaluationException e) { throw new IOException(e); } } private static FunctionParamInfo withInferredDoc( FunctionParamInfo paramInfo, ImmutableMap fallbackDocs) { if (paramInfo.getDocString().isEmpty() && fallbackDocs.containsKey(paramInfo.getName())) { return paramInfo.toBuilder() .clearDocString() .setDocString(fallbackDocs.get(paramInfo.getName())) .build(); } else { return paramInfo; } } /** * Returns a reader from the given path. * * @param filePath The given path, either a filesystem path or a java Resource */ private static Reader readerFromPath(String filePath) throws IOException { if (Files.exists(Paths.get(filePath))) { Path path = Paths.get(filePath); return Files.newBufferedReader(path, UTF_8); } InputStream inputStream = MarkdownRenderer.class.getClassLoader().getResourceAsStream(filePath); if (inputStream == null) { throw new FileNotFoundException(filePath + " was not found as a resource."); } return new InputStreamReader(inputStream, UTF_8); } } stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownUtil.java000066400000000000000000000606161513642521100315130ustar00rootroot00000000000000// Copyright 2018 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.stardoc.rendering; import static com.google.common.base.Strings.isNullOrEmpty; import static com.google.common.collect.ImmutableList.toImmutableList; import static com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.FunctionParamRole.PARAM_ROLE_KEYWORD_ONLY; import static com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.FunctionParamRole.PARAM_ROLE_KWARGS; import static com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.FunctionParamRole.PARAM_ROLE_VARARGS; import static java.util.Comparator.naturalOrder; import static java.util.stream.Collectors.joining; import com.google.common.base.Joiner; import com.google.common.base.Splitter; import com.google.common.collect.ImmutableList; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AspectInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.AttributeInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.FunctionParamInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.MacroInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ModuleExtensionTagClassInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderFieldInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.ProviderNameGroup; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RepositoryRuleInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.RuleInfo; import com.google.devtools.build.lib.starlarkdocextract.StardocOutputProtos.StarlarkFunctionInfo; import java.time.Instant; import java.time.ZoneId; import java.time.format.DateTimeFormatter; import java.util.ArrayList; import java.util.List; import java.util.Optional; import java.util.regex.Matcher; import java.util.regex.Pattern; /** Contains a number of utility methods for markdown rendering. */ public final class MarkdownUtil { private final Optional entrypointBzlFile; private static final int MAX_LINE_LENGTH = 100; public MarkdownUtil(Optional entrypointBzlFile) { this.entrypointBzlFile = entrypointBzlFile; } /** * Formats the input string so that it is displayable in a Markdown table cell. This performs the * following operations: * *
    *
  • Trims the string of leading/trailing whitespace. *
  • Escapes pipe characters ({@code |}) as {@code \|}. *
  • Transforms Markdown code blocks ({@code ```}) into HTML preformatted code blocks, and * transforms newlines within those code blocks into character entities *
  • Transforms remaining 'new paragraph' patterns (two or more sequential newline characters) * into line break HTML tags. *
  • Turns remaining newlines into spaces (as they generally indicate intended line wrap). *
* * TODO(https://github.com/bazelbuild/stardoc/issues/118): also format Markdown lists as HTML. */ public static String markdownCellFormat(String docString) { return new MarkdownCellFormatter(docString).format(); } // See https://github.github.com/gfm private static final class MarkdownCellFormatter { // Lines of the input docstring, without newline terminators. private final ImmutableList lines; // Index of the current line in lines, 0-based. int currentLine; // Formatted result. StringBuilder result; private static final Pattern CODE_BLOCK_OPENING_FENCE = Pattern.compile("^ {0,3}(?```+|~~~+) *(?\\w*)[^`~]*$"); MarkdownCellFormatter(String docString) { lines = docString.trim().replace("|", "\\|").lines().collect(toImmutableList()); currentLine = 0; result = new StringBuilder(); } /** Consumes the input and yields the formatted result. */ String format() { boolean prefixContentWithSpace = false; for (; currentLine < lines.size(); currentLine++) { if (formatParagraphBreak()) { prefixContentWithSpace = false; continue; } if (prefixContentWithSpace) { result.append(" "); } prefixContentWithSpace = true; if (formatFencedCodeBlock()) { continue; } result.append(lines.get(currentLine)); } return result.toString(); } /** * If a fenced code block begins at {@link #currentLine}, render to {@link #result}, update * {@link #currentLine} to point to the closing fence, and return true. */ private boolean formatFencedCodeBlock() { // See https://github.github.com/gfm/#fenced-code-blocks Matcher opening = CODE_BLOCK_OPENING_FENCE.matcher(lines.get(currentLine)); if (!opening.matches()) { return false; } Pattern closingFence = Pattern.compile("^ {0,3}" + opening.group("fence") + " *$"); for (int closingLine = currentLine + 1; closingLine < lines.size(); closingLine++) { if (closingFence.matcher(lines.get(closingLine)).matches()) { // We found the closing fence: format the block's contents as HTML. String language = opening.group("lang"); if (language != null && !language.isEmpty()) { result.append("
");
          } else {
            result.append("
");
          }
          int firstContentLine = currentLine + 1;
          for (int i = firstContentLine; i < closingLine; i++) {
            if (i > firstContentLine) {
              result.append(newlineEscape("\n"));
            }
            result.append(htmlEscape(lines.get(i)));
          }
          result.append("
"); currentLine = closingLine; return true; } } // We did not find the closing fence. return false; } /** * If blank lines appear at {@link #currentLine}, render to {@link #result}, update {@link * #currentLine} to point to the last line of the break, and return true. */ private boolean formatParagraphBreak() { int numEmptyLines = 0; for (int i = currentLine; i < lines.size(); i++) { if (lines.get(i).isEmpty()) { numEmptyLines++; } else { break; } } if (numEmptyLines > 0) { result.append("

"); currentLine += numEmptyLines - 1; return true; } return false; } } /** * Return a string that escapes angle brackets for HTML. * *

For example: 'Information with .' becomes 'Information with <brackets>'. */ public static String htmlEscape(String docString) { return docString.replace("<", "<").replace(">", ">"); } /** Returns a string that escapes newlines with HTML entities. */ private static String newlineEscape(String docString) { return docString.replace("\n", " "); } private static final Pattern CONSECUTIVE_BACKTICKS = Pattern.compile("`+"); /** * Returns a Markdown code span (e.g. {@code `return foo;`}) that contains the given literal text, * which may itself contain backticks. * *

For example: * *

    *
  • {@code markdownCodeSpan("foo")} returns {@code "`foo`"} *
  • {@code markdownCodeSpan("fo`o")} returns {@code "``fo`o``"} *
  • {@code markdownCodeSpan("`foo`")} returns {@code "`` foo` ``""} *
*/ public static String markdownCodeSpan(String code) { // https://github.github.com/gfm/#code-span int numConsecutiveBackticks = CONSECUTIVE_BACKTICKS .matcher(code) .results() .map(match -> match.end() - match.start()) .max(naturalOrder()) .orElse(0); String padding = code.startsWith("`") || code.endsWith("`") ? " " : ""; return String.format( "%1$s%2$s%3$s%2$s%1$s", "`".repeat(numConsecutiveBackticks + 1), padding, code); } /** * Return a string representing the rule summary for the given rule with the given name. * *

For example: 'my_rule(foo, bar)'. The summary will contain hyperlinks for each attribute. */ @SuppressWarnings("unused") // Used by markdown template. public String ruleSummary(String ruleName, RuleInfo ruleInfo) { ImmutableList params = ruleInfo.getAttributeList().stream() .map(attributeInfo -> new Param(attributeInfo, ruleName)) .collect(toImmutableList()); return summary(ruleName, params); } /** * Return a string representing the summary for the given provider with the given name. * *

For example: 'MyInfo(foo, bar)'. * *

If the provider has an init callback, the summary will contain hyperlinks for each of the * init callback's parameters; if the provider doesn't have an init callback, the summary will * contain hyperlinks for each field. */ @SuppressWarnings("unused") // Used by markdown template. public String providerSummary(String providerName, ProviderInfo providerInfo) { return providerSummaryImpl(providerName, providerInfo, providerName); } /** Like {@link providerSummary}, but using "$providerName-_init" in HTML anchors. */ @SuppressWarnings("unused") // Used by markdown template. public String providerSummaryWithInitAnchor(String providerName, ProviderInfo providerInfo) { return providerSummaryImpl(providerName, providerInfo, providerName + "-_init"); } private String providerSummaryImpl( String providerName, ProviderInfo providerInfo, String paramAnchorPrefix) { ImmutableList params = providerInfo.hasInit() ? getFunctionParamsInDeclarationOrder(providerInfo.getInit(), paramAnchorPrefix) : providerInfo.getFieldInfoList().stream() .map(fieldInfo -> new Param(fieldInfo, paramAnchorPrefix)) .collect(toImmutableList()); return summary(providerName, params); } /** * Return a string representing the aspect summary for the given aspect with the given name. * *

For example: 'my_aspect(foo, bar)'. The summary will contain hyperlinks for each attribute. */ @SuppressWarnings("unused") // Used by markdown template. public String aspectSummary(String aspectName, AspectInfo aspectInfo) { ImmutableList params = aspectInfo.getAttributeList().stream() .map(attributeInfo -> new Param(attributeInfo, aspectName)) .collect(toImmutableList()); return summary(aspectName, params); } /** * Return a string representing the repository rule summary for the given repository rule with the * given name. * *

For example: 'my_repo_rule(foo, bar)'. The summary will contain hyperlinks for each * attribute. */ @SuppressWarnings("unused") // Used by markdown template. public String repositoryRuleSummary(String ruleName, RepositoryRuleInfo ruleInfo) { ImmutableList params = ruleInfo.getAttributeList().stream() .map(attributeInfo -> new Param(attributeInfo, ruleName)) .collect(toImmutableList()); return summary(ruleName, params); } /** * Return a string representing the module extension summary for the given module extension with * the given name. * *

For example: * *

   * my_ext = use_extension("//some:file.bzl", "my_ext")
   * my_ext.tag1(foo, bar)
   * my_ext.tag2(baz)
   * 
* *

The summary will contain hyperlinks for each attribute. */ @SuppressWarnings("unused") // Used by markdown template. public String moduleExtensionSummary(String extensionName, ModuleExtensionInfo extensionInfo) { StringBuilder summaryBuilder = new StringBuilder(); summaryBuilder.append( String.format( "%s = use_extension(\"%s\", \"%s\")", extensionName, entrypointBzlFile.orElse("..."), extensionName)); for (ModuleExtensionTagClassInfo tagClass : extensionInfo.getTagClassList()) { String callableName = String.format("%s.%s", extensionName, tagClass.getTagName()); ImmutableList params = tagClass.getAttributeList().stream() .map(attributeInfo -> new Param(attributeInfo, callableName)) .collect(toImmutableList()); summaryBuilder.append("\n").append(summary(callableName, params)); } return summaryBuilder.toString(); } /** * Return a string representing the summary for the given user-defined function. * *

For example: 'my_func(foo, bar)'. The summary will contain hyperlinks for each parameter. */ @SuppressWarnings("unused") // Used by markdown template. public String funcSummary(StarlarkFunctionInfo funcInfo) { return summary( funcInfo.getFunctionName(), getFunctionParamsInDeclarationOrder(funcInfo, funcInfo.getFunctionName())); } /** * Return a string representing the summary for the given symbolic macro. * *

For example: 'my_macro(*, name, visibility, foo, bar)'. The summary will contain hyperlinks * for each parameter. */ @SuppressWarnings("unused") // Used by markdown template. public String macroSummary(String macroName, MacroInfo macroInfo) { ImmutableList.Builder paramsBuilder = new ImmutableList.Builder<>(); // All arguments to a symbolic macro are keyword-only paramsBuilder.add(Param.STAR_SEPARATOR); for (AttributeInfo attributeInfo : macroInfo.getAttributeList()) { paramsBuilder.add(new Param(attributeInfo, macroName)); } return summary(macroName, paramsBuilder.build()); } @SuppressWarnings("unused") // Used by markdown template. public String loadStatement(String name) { return entrypointBzlFile .map( file -> String.format( "load(\"%s\", \"%s\")", file, Splitter.on('.').split(name).iterator().next())) .orElse(""); } /** Returns a string representing the summary for a function or other callable. */ private static String summary(String functionName, ImmutableList params) { ImmutableList> paramLines = wrap(functionName, params, MAX_LINE_LENGTH); List paramLinksLines = new ArrayList<>(); for (ImmutableList paramLine : paramLines) { String paramLinksLine = paramLine.stream().map(Param::renderHtml).collect(joining(", ")); paramLinksLines.add(paramLinksLine); } String renderedParams = Joiner.on(",\n" + " ".repeat(functionName.length() + 1)).join(paramLinksLines); return String.format("%s(%s)", functionName, renderedParams); } /** Representation of a callable's parameter in a summary line. */ private static final class Param { // User-visible name, including the leading "*" or "**" for residuals final String name; // HTML anchor for the parameter's detailed documentation elsewhere on the page final Optional anchorName; public static final Param STAR_SEPARATOR = new Param("*", Optional.empty()); private Param(String name, Optional anchorName) { this.name = name; this.anchorName = anchorName; } Param(FunctionParamInfo paramInfo, String anchorPrefix) { switch (paramInfo.getRole()) { case PARAM_ROLE_VARARGS: this.name = "*" + paramInfo.getName(); break; case PARAM_ROLE_KWARGS: this.name = "**" + paramInfo.getName(); break; default: this.name = paramInfo.getName(); break; } this.anchorName = formatAnchorName(paramInfo.getName(), anchorPrefix); } Param(AttributeInfo atrributeInfo, String anchorPrefix) { this.name = atrributeInfo.getName(); this.anchorName = formatAnchorName(atrributeInfo.getName(), anchorPrefix); } Param(ProviderFieldInfo fieldInfo, String anchorPrefix) { this.name = fieldInfo.getName(); this.anchorName = formatAnchorName(fieldInfo.getName(), anchorPrefix); } private static Optional formatAnchorName(String name, String anchorPrefix) { return Optional.of(String.format("%s-%s", anchorPrefix, name)); } String getName() { return this.name; } String renderHtml() { if (anchorName.isPresent()) { return String.format("%s", anchorName.get(), name); } else { return name; } } } private static ImmutableList getFunctionParamsInDeclarationOrder( StarlarkFunctionInfo funcInfo, String anchorPrefix) { List paramInfos = funcInfo.getParameterList(); int nparams = paramInfos.size(); Optional kwargs; if (nparams > 0 && paramInfos.get(nparams - 1).getRole() == PARAM_ROLE_KWARGS) { kwargs = Optional.of(new Param(paramInfos.get(nparams - 1), anchorPrefix)); nparams--; } else { kwargs = Optional.empty(); } Optional varargs; if (nparams > 0 && paramInfos.get(nparams - 1).getRole() == PARAM_ROLE_VARARGS) { varargs = Optional.of(new Param(paramInfos.get(nparams - 1), anchorPrefix)); nparams--; } else { varargs = Optional.empty(); } // Invariant: nparams is now the number of non-residual parameters. ImmutableList.Builder paramsBuilder = new ImmutableList.Builder<>(); int numKwonly = 0; // Add ordinary or positional-only params for (int i = 0; i < nparams; i++) { FunctionParamInfo paramInfo = paramInfos.get(i); if (paramInfo.getRole() == PARAM_ROLE_KEYWORD_ONLY) { numKwonly = nparams - i; break; } paramsBuilder.add(new Param(paramInfo, anchorPrefix)); } // Add *args or (if needed) the "*" separator if (varargs.isPresent() || numKwonly > 0) { paramsBuilder.add(varargs.orElse(Param.STAR_SEPARATOR)); } // Add kwonly params (if any) for (int i = nparams - numKwonly; i < nparams; i++) { paramsBuilder.add(new Param(paramInfos.get(i), anchorPrefix)); } // Add **kwargs kwargs.ifPresent(paramsBuilder::add); return paramsBuilder.build(); } /** * Wraps the given function parameter names to be able to construct a function summary that stays * within the provided line length limit. * * @param functionName the function name. * @param params the function parameter names. * @param maxLineLength the maximal line length. * @return the lines with the wrapped parameter names. */ private static ImmutableList> wrap( String functionName, ImmutableList params, int maxLineLength) { ImmutableList.Builder> paramLines = ImmutableList.builder(); ImmutableList.Builder linesBuilder = new ImmutableList.Builder<>(); int leading = functionName.length(); int length = leading; int punctuation = 2; // cater for left parenthesis/space before and comma after parameter for (Param param : params) { length += param.getName().length() + punctuation; if (length > maxLineLength) { paramLines.add(linesBuilder.build()); length = leading + param.getName().length(); linesBuilder = new ImmutableList.Builder<>(); } linesBuilder.add(param); } paramLines.add(linesBuilder.build()); return paramLines.build(); } /** * Returns a string describing the given attribute's type and whether it is non-configurable. The * description contains a hyperlink if there is a relevant hyperlink to Bazel documentation * available. */ public String attributeTypeString(AttributeInfo attrInfo) { String typeLink; switch (attrInfo.getType()) { case LABEL: case LABEL_LIST: case OUTPUT: typeLink = "https://bazel.build/concepts/labels"; break; case NAME: typeLink = "https://bazel.build/concepts/labels#target-names"; break; case STRING_DICT: case STRING_LIST_DICT: case LABEL_STRING_DICT: typeLink = "https://bazel.build/rules/lib/core/dict"; break; default: typeLink = null; break; } String typeString; if (typeLink == null) { typeString = attributeTypeDescription(attrInfo); } else { typeString = String.format("%s", typeLink, attributeTypeDescription(attrInfo)); } if (attrInfo.getNonconfigurable()) { typeString += "; nonconfigurable"; } return typeString; } public String mandatoryString(AttributeInfo attrInfo) { return attrInfo.getMandatory() ? "required" : "optional"; } /** * Returns "required" if providing a value for this parameter is mandatory. Otherwise, returns * "optional". */ public String mandatoryString(FunctionParamInfo paramInfo) { return paramInfo.getMandatory() ? "required" : "optional"; } public String configurableString(AttributeInfo attrInfo) { return attrInfo.getNonconfigurable() ? "non-configurable" : "configurable"; } /** * Return a string explaining what providers an attribute requires. Adds hyperlinks to providers. */ public String attributeProviders(AttributeInfo attributeInfo) { List providerNames = attributeInfo.getProviderNameGroupList(); List finalProviderNames = new ArrayList<>(); for (ProviderNameGroup providerNameList : providerNames) { List providers = providerNameList.getProviderNameList(); finalProviderNames.add(Joiner.on(", ").join(providers)); } return Joiner.on("; or ").join(finalProviderNames); } private static String attributeTypeDescription(AttributeInfo attrInfo) { switch (attrInfo.getType()) { case NAME: return "Name"; case INT: return "Integer"; case STRING: return "String"; case STRING_LIST: return "List of strings"; case INT_LIST: return "List of integers"; case BOOLEAN: return "Boolean"; case LABEL_STRING_DICT: return "Dictionary: Label -> String"; case LABEL_DICT_UNARY: return "Dictionary: String -> Label"; case STRING_DICT: return "Dictionary: String -> String"; case STRING_LIST_DICT: return "Dictionary: String -> List of strings"; case LABEL_LIST_DICT: return "Dictionary: String -> List of labels"; case LABEL: case OUTPUT: return "Label"; case LABEL_LIST: case OUTPUT_LIST: return "List of labels"; case UNKNOWN: case UNRECOGNIZED: // fall through } // We throw here rather than in the switch statement to support building against an external // .proto definition. throw new IllegalArgumentException( String.format( "Attribute '%s' has unsupported attribute type %d (%s)", attrInfo.getName(), attrInfo.getTypeValue(), attrInfo.getType())); } /** * Formats a build timestamp from stamping with the given format. For example: * *

`$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "yyyy MMM dd, HH:mm") * UTC` */ public String formatBuildTimestamp(String buildTimestampSeconds, String zoneId, String format) { // If stamp is not set to True in the stardoc() rule, then $stamping.volatile.BUILD_TIMESTAMP // will be null, so return the empty string rather than crash. Alternatively, if this function // is called as: // // $util.formatBuildTimestamp("$!stamping.volatile.BUILD_TIMESTAMP", "UTC", "yyyy MMM dd, // HH:mm") // // then buildTimestampSeconds will be the empty string, so return the empty string too. if (isNullOrEmpty(buildTimestampSeconds)) { return ""; } return Instant.ofEpochSecond(Long.parseLong(buildTimestampSeconds)) .atZone(ZoneId.of(zoneId)) .format(DateTimeFormatter.ofPattern(format)); } } stardoc-0.8.1/src/main/java/com/google/devtools/build/stardoc/rendering/Stamping.java000066400000000000000000000040271513642521100306470ustar00rootroot00000000000000// Copyright 2024 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.stardoc.rendering; import com.google.common.collect.ImmutableMap; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.util.List; /** Reads and stores stamping information. */ public final class Stamping { public static Stamping read(String stableStatusFile, String volatileStatusFile) throws IOException { return new Stamping(parse(stableStatusFile), parse(volatileStatusFile)); } public static Stamping empty() { return new Stamping(ImmutableMap.of(), ImmutableMap.of()); } private final ImmutableMap stableInfo; private final ImmutableMap volatileInfo; private static ImmutableMap parse(String path) throws IOException { ImmutableMap.Builder builder = ImmutableMap.builder(); List lines = Files.readAllLines(Path.of(path)); for (String line : lines) { String[] kv = line.split(" ", 2); // split on first space only builder.put(kv[0], kv[1]); } return builder.buildKeepingLast(); } private Stamping( ImmutableMap stableInfo, ImmutableMap volatileInfo) { this.stableInfo = stableInfo; this.volatileInfo = volatileInfo; } public ImmutableMap getStable() { return stableInfo; } public ImmutableMap getVolatile() { return volatileInfo; } } stardoc-0.8.1/src/test/000077500000000000000000000000001513642521100147255ustar00rootroot00000000000000stardoc-0.8.1/src/test/java/000077500000000000000000000000001513642521100156465ustar00rootroot00000000000000stardoc-0.8.1/src/test/java/com/000077500000000000000000000000001513642521100164245ustar00rootroot00000000000000stardoc-0.8.1/src/test/java/com/google/000077500000000000000000000000001513642521100177005ustar00rootroot00000000000000stardoc-0.8.1/src/test/java/com/google/devtools/000077500000000000000000000000001513642521100215375ustar00rootroot00000000000000stardoc-0.8.1/src/test/java/com/google/devtools/build/000077500000000000000000000000001513642521100226365ustar00rootroot00000000000000stardoc-0.8.1/src/test/java/com/google/devtools/build/stardoc/000077500000000000000000000000001513642521100242755ustar00rootroot00000000000000stardoc-0.8.1/src/test/java/com/google/devtools/build/stardoc/rendering/000077500000000000000000000000001513642521100262525ustar00rootroot00000000000000stardoc-0.8.1/src/test/java/com/google/devtools/build/stardoc/rendering/BUILD000066400000000000000000000007601513642521100270370ustar00rootroot00000000000000load("@rules_java//java:defs.bzl", "java_test") package(default_applicable_licenses = ["//:license"]) filegroup( name = "srcs", testonly = 0, srcs = glob(["*"]), visibility = ["//:__pkg__"], ) java_test( name = "MarkdownUtilTest", size = "small", srcs = ["MarkdownUtilTest.java"], deps = [ "//src/main/java/com/google/devtools/build/stardoc/rendering", "@stardoc_maven//:com_google_truth_truth", "@stardoc_maven//:junit_junit", ], ) stardoc-0.8.1/src/test/java/com/google/devtools/build/stardoc/rendering/MarkdownUtilTest.java000066400000000000000000000066731513642521100324110ustar00rootroot00000000000000// Copyright 2023 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.stardoc.rendering; import static com.google.common.truth.Truth.assertThat; import java.util.Optional; import org.junit.Test; import org.junit.runner.RunWith; import org.junit.runners.JUnit4; /** Tests for MarkdownUtil. */ @RunWith(JUnit4.class) public class MarkdownUtilTest { MarkdownUtil util = new MarkdownUtil(Optional.of("//:test.bzl")); @Test public void markdownCodeSpan() { assertThat(MarkdownUtil.markdownCodeSpan("")).isEqualTo("``"); assertThat(MarkdownUtil.markdownCodeSpan("foo bar ")).isEqualTo("`foo bar `"); } @Test public void markdownCodeSpan_backticks() { assertThat(MarkdownUtil.markdownCodeSpan("foo`bar")).isEqualTo("``foo`bar``"); assertThat(MarkdownUtil.markdownCodeSpan("foo``bar")).isEqualTo("```foo``bar```"); assertThat(MarkdownUtil.markdownCodeSpan("foo`bar```baz``quz")) .isEqualTo("````foo`bar```baz``quz````"); } @Test public void markdownCodeSpan_backticksPadding() { assertThat(MarkdownUtil.markdownCodeSpan("`foo")).isEqualTo("`` `foo ``"); assertThat(MarkdownUtil.markdownCodeSpan("``foo")).isEqualTo("``` ``foo ```"); assertThat(MarkdownUtil.markdownCodeSpan("foo`")).isEqualTo("`` foo` ``"); assertThat(MarkdownUtil.markdownCodeSpan("foo``")).isEqualTo("``` foo`` ```"); } @Test public void markdownCellFormat_pipes() { assertThat(MarkdownUtil.markdownCellFormat("foo|bar")).isEqualTo("foo\\|bar"); assertThat(MarkdownUtil.markdownCellFormat("|\\|foobar||")).isEqualTo("\\|\\\\|foobar\\|\\|"); } @Test public void markdownCellFormat_newlines() { assertThat(MarkdownUtil.markdownCellFormat("\nfoo\nbar\n\nbaz\r\n\r\n\r\nqux\r\n")) .isEqualTo("foo bar

baz

qux"); // Newline escapes are not expanded assertThat(MarkdownUtil.markdownCellFormat("hello\\r\\nworld")).isEqualTo("hello\\r\\nworld"); } @Test public void markdownCellFormat_codeBlocks() { assertThat(MarkdownUtil.markdownCellFormat("```\nhello();\n```")) .isEqualTo("

hello();
"); assertThat(MarkdownUtil.markdownCellFormat("```\nhello();\n```\nor\n~~~\nbye();\n~~~")) .isEqualTo("
hello();
or
bye();
"); assertThat(MarkdownUtil.markdownCellFormat("```bash\ncat foo.txt | cmd > /dev/null\n```")) .isEqualTo( "
cat foo.txt \\| cmd > /dev/null
"); assertThat(MarkdownUtil.markdownCellFormat("````\n```\n```\n````")) .isEqualTo("
```
```
"); } @Test public void markdownCellFormat_inlineMarkup() { assertThat(MarkdownUtil.markdownCellFormat("bold italic")) .isEqualTo("bold italic"); assertThat(MarkdownUtil.markdownCellFormat("**bold** _italic_")).isEqualTo("**bold** _italic_"); } } stardoc-0.8.1/stardoc/000077500000000000000000000000001513642521100146165ustar00rootroot00000000000000stardoc-0.8.1/stardoc/BUILD000066400000000000000000000024661513642521100154100ustar00rootroot00000000000000load("@bazel_skylib//:bzl_library.bzl", "bzl_library") load("//stardoc:stardoc.bzl", "stardoc") licenses(["notice"]) package( default_applicable_licenses = ["//:license"], default_visibility = ["//visibility:public"], ) exports_files(glob(["templates/**"])) filegroup( name = "test_deps", testonly = True, srcs = [ "BUILD", ] + glob(["*.bzl"]), visibility = ["//visibility:public"], ) bzl_library( name = "stardoc_lib", srcs = ["stardoc.bzl"], visibility = ["//visibility:public"], deps = [ "//stardoc/private:stardoc_lib", "@bazel_skylib//rules:copy_file", "@rules_java//java:rules", ], ) bzl_library( name = "html_tables_stardoc", srcs = ["html_tables_stardoc.bzl"], visibility = ["//visibility:public"], deps = [ ":stardoc_lib", ], ) stardoc( name = "stardoc_doc", out = "stardoc_doc.md", input = ":stardoc.bzl", symbol_names = [ "stardoc", ], deps = [":stardoc_lib"], ) alias( name = "renderer", actual = "//src/main/java/com/google/devtools/build/stardoc/renderer", ) # Sources needed for release tarball. filegroup( name = "distro_srcs", srcs = [ "BUILD", ] + glob([ "*.bzl", "templates/**", ]), visibility = ["//:__pkg__"], ) stardoc-0.8.1/stardoc/html_tables_stardoc.bzl000066400000000000000000000032321513642521100213440ustar00rootroot00000000000000# Copyright 2019 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Macro for Pure Markdown Stardoc Output Format""" load(":stardoc.bzl", "stardoc") def html_tables_stardoc(name, **kwargs): """Outputs documentation using html_tables templates. Args: name: A unique name for this target. **kwargs: Attributes to be passed along to the stardoc() rule. (May not include the attributes for the stardoc and renderer binaries, format, or templates.) """ stardoc( name = name, format = "markdown", aspect_template = Label("//stardoc:templates/html_tables/aspect.vm"), func_template = Label("//stardoc:templates/html_tables/func.vm"), header_template = Label("//stardoc:templates/html_tables/header.vm"), provider_template = Label("//stardoc:templates/html_tables/provider.vm"), rule_template = Label("//stardoc:templates/html_tables/rule.vm"), repository_rule_template = Label("//stardoc:templates/html_tables/repository_rule.vm"), module_extension_template = Label("//stardoc:templates/html_tables/module_extension.vm"), **kwargs ) stardoc-0.8.1/stardoc/private/000077500000000000000000000000001513642521100162705ustar00rootroot00000000000000stardoc-0.8.1/stardoc/private/BUILD000066400000000000000000000013751513642521100170600ustar00rootroot00000000000000load("@bazel_skylib//:bzl_library.bzl", "bzl_library") load("//stardoc/private:stamp_detector.bzl", "stamp_detector") bzl_library( name = "stardoc_lib", srcs = [ "stamp_detector.bzl", "stardoc.bzl", ], visibility = ["//stardoc:__pkg__"], ) config_setting( name = "stamp_enabled", values = {"stamp": "1"}, visibility = ["//visibility:private"], ) stamp_detector( name = "stamp_detector", enabled = select({ "stamp_enabled": True, "//conditions:default": False, }), visibility = ["//visibility:private"], ) # Sources needed for release tarball. filegroup( name = "distro_srcs", srcs = [ "BUILD", ] + glob([ "*.bzl", ]), visibility = ["//:__pkg__"], ) stardoc-0.8.1/stardoc/private/stamp_detector.bzl000066400000000000000000000021161513642521100220160ustar00rootroot00000000000000# Copyright 2024 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Detector for the --stamp flag""" StampDetectorInfo = provider( doc = "Result of detecting the --stamp flag", fields = { "enabled": "True if --stamp is enabled", }, ) def _stamp_detector_impl(ctx): return [StampDetectorInfo(enabled = ctx.attr.enabled)] stamp_detector = rule( _stamp_detector_impl, doc = """Detects if the --stamp flag is enabled""", attrs = { "enabled": attr.bool(mandatory = True, doc = "True if --stamp flag is enabled"), }, ) stardoc-0.8.1/stardoc/private/stardoc.bzl000066400000000000000000000176671513642521100204610ustar00rootroot00000000000000# Copyright 2018 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Starlark rule for stardoc: a documentation generator tool written in Java.""" load("//stardoc/private:stamp_detector.bzl", "StampDetectorInfo") def _is_stamp_enabled(ctx): if ctx.attr.stamp == 1: return True elif ctx.attr.stamp == 0: return False elif ctx.attr.stamp == -1: return ctx.attr._stamp_detector[StampDetectorInfo].enabled else: fail("`stamp` is expected to be one of [-1, 0, 1]") def _renderer_action_run(ctx, out_file, proto_file): """Helper for declaring the markdown renderer action""" stamp_enabled = _is_stamp_enabled(ctx) renderer_args = ctx.actions.args() renderer_args.add("--input=" + str(proto_file.path)) renderer_args.add("--output=" + str(ctx.outputs.out.path)) renderer_args.add("--aspect_template=" + str(ctx.file.aspect_template.path)) renderer_args.add("--header_template=" + str(ctx.file.header_template.path)) if ctx.attr.table_of_contents_template: renderer_args.add("--table_of_contents_template=" + str(ctx.file.table_of_contents_template.path)) renderer_args.add("--func_template=" + str(ctx.file.func_template.path)) renderer_args.add("--macro_template=" + str(ctx.file.macro_template.path)) renderer_args.add("--provider_template=" + str(ctx.file.provider_template.path)) renderer_args.add("--rule_template=" + str(ctx.file.rule_template.path)) renderer_args.add("--repository_rule_template=" + str(ctx.file.repository_rule_template.path)) renderer_args.add("--module_extension_template=" + str(ctx.file.module_extension_template.path)) if ctx.file.footer_template: renderer_args.add("--footer_template=" + str(ctx.file.footer_template.path)) if stamp_enabled: renderer_args.add("--stamping_stable_status_file=" + str(ctx.info_file.path)) renderer_args.add("--stamping_volatile_status_file=" + str(ctx.version_file.path)) inputs = [ proto_file, ctx.file.aspect_template, ctx.file.header_template, ctx.file.func_template, ctx.file.macro_template, ctx.file.provider_template, ctx.file.rule_template, ctx.file.repository_rule_template, ctx.file.module_extension_template, ] if ctx.attr.table_of_contents_template: inputs.append(ctx.file.table_of_contents_template) if ctx.file.footer_template: inputs.append(ctx.file.footer_template) if stamp_enabled: inputs.append(ctx.info_file) inputs.append(ctx.version_file) renderer = ctx.executable.renderer ctx.actions.run( arguments = [renderer_args], executable = renderer, inputs = inputs, mnemonic = "Renderer", outputs = [out_file], progress_message = ("Converting proto format of %s to markdown format" % (ctx.label.name)), ) _common_renderer_attrs = { "out": attr.output( doc = "The (markdown) file to which documentation will be output.", mandatory = True, ), "renderer": attr.label( doc = "The location of the renderer tool.", allow_files = True, cfg = "exec", executable = True, mandatory = True, ), "aspect_template": attr.label( doc = "The input file template for generating documentation of aspects.", allow_single_file = [".vm"], mandatory = True, ), "header_template": attr.label( doc = "The input file template for the header of the output documentation.", allow_single_file = [".vm"], mandatory = True, ), "table_of_contents_template": attr.label( doc = "The input file template for the table of contents of the output documentation. " + "This is unset by default for backwards compatibility. Use " + "`Label(\"@stardoc//stardoc:templates/markdown_tables/table_of_contents.vm\")` " + "for the default template.", allow_single_file = [".vm"], mandatory = False, # Not mandatory for backwards compatibility. ), "func_template": attr.label( doc = "The input file template for generating documentation of functions, including legacy macros.", allow_single_file = [".vm"], mandatory = True, ), "macro_template": attr.label( doc = "The input file template for generating documentation of symbolic macros.", allow_single_file = [".vm"], mandatory = True, ), "provider_template": attr.label( doc = "The input file template for generating documentation of providers.", allow_single_file = [".vm"], mandatory = True, ), "rule_template": attr.label( doc = "The input file template for generating documentation of rules.", allow_single_file = [".vm"], mandatory = True, ), "repository_rule_template": attr.label( doc = "The input file template for generating documentation of repository rules.", allow_single_file = [".vm"], mandatory = True, ), "module_extension_template": attr.label( doc = "The input file template for generating documentation of module extensions.", allow_single_file = [".vm"], mandatory = True, ), "footer_template": attr.label( doc = "The input file template for generating the footer of the output documentation. Optional.", allow_single_file = [".vm"], ), "stamp": attr.int( doc = """ Whether to provide stamping information to templates, where it can be accessed via `$util.formatBuildTimestamp()` and`$stamping`. Example: ```vm Built on `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "yyyy-MM-dd HH:mm")` ``` Possible values: * `stamp = 1`: Always provide stamping information, even in [--nostamp](https://bazel.build/docs/user-manual#stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it. * `stamp = 0`: Do not provide stamping information. * `stamp = -1`: Provide stamping information only if the [--stamp](https://bazel.build/docs/user-manual#stamp) flag is set. Stamped targets are not rebuilt unless their dependencies change. """, default = -1, ), "_stamp_detector": attr.label( default = "//stardoc/private:stamp_detector", providers = [StampDetectorInfo], ), } def _stardoc_markdown_renderer_impl(ctx): out_file = ctx.outputs.out _renderer_action_run(ctx, out_file = out_file, proto_file = ctx.file.src) # Work around default outputs not getting captured by sh_binary: # https://github.com/bazelbuild/bazel/issues/15043. # See discussion in https://github.com/bazelbuild/stardoc/pull/139. outputs = [out_file] return [DefaultInfo(files = depset(outputs), runfiles = ctx.runfiles(files = outputs))] _stardoc_markdown_renderer_attrs = { "src": attr.label( doc = "The .binaryproto file from which to generate documentation.", allow_single_file = [".binaryproto"], mandatory = True, ), } | _common_renderer_attrs stardoc_markdown_renderer = rule( _stardoc_markdown_renderer_impl, doc = """ Generates markdown documentation for starlark rule definitions from the corresponding binary proto. """, attrs = _stardoc_markdown_renderer_attrs, ) stardoc-0.8.1/stardoc/proto/000077500000000000000000000000001513642521100157615ustar00rootroot00000000000000stardoc-0.8.1/stardoc/proto/BUILD000066400000000000000000000012561513642521100165470ustar00rootroot00000000000000load("@com_google_protobuf//bazel:java_proto_library.bzl", "java_proto_library") load("@com_google_protobuf//bazel:proto_library.bzl", "proto_library") licenses(["notice"]) package( default_applicable_licenses = ["//:license"], default_visibility = ["//visibility:public"], ) exports_files(["stardoc_output.proto"]) # Sources needed for release tarball. filegroup( name = "distro_srcs", srcs = [ "BUILD", ] + glob(["*.proto"]), visibility = ["//:__pkg__"], ) proto_library( name = "stardoc_output_proto", srcs = ["stardoc_output.proto"], ) java_proto_library( name = "stardoc_output_java_proto", deps = [":stardoc_output_proto"], ) stardoc-0.8.1/stardoc/proto/stardoc_output.proto000066400000000000000000000356641513642521100221430ustar00rootroot00000000000000// Copyright 2019 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Vendored from src/main/protobuf/stardoc_output.proto // in the Bazel source tree at commit 58cd0a15421529a957bfb0f7fca1b188930dc5b5 // // Protos for Stardoc data. // // Stardoc collects information about Starlark functions, providers, and rules. syntax = "proto3"; package stardoc_output; // option java_api_version = 2; option java_package = "com.google.devtools.build.lib.starlarkdocextract"; option java_outer_classname = "StardocOutputProtos"; // The root output proto of Stardoc. An invocation of Stardoc on a single file // will output exactly one instance of this proto, representing all // documentation for the input Starlark file. message ModuleInfo { repeated RuleInfo rule_info = 1; repeated ProviderInfo provider_info = 2; repeated StarlarkFunctionInfo func_info = 3; repeated AspectInfo aspect_info = 4; // The docstring present at the top of the input Starlark file. string module_docstring = 5; // The display form of the label of the module file (as seen from the // starlark_doc_extract or Stardoc target's repo). Unset when there is no // module file (e.g. when the module is a REPL, or in Bazel's internal tests). string file = 6; repeated ModuleExtensionInfo module_extension_info = 7; repeated RepositoryRuleInfo repository_rule_info = 8; repeated MacroInfo macro_info = 9; repeated StarlarkOtherSymbolInfo starlark_other_symbol_info = 10; } // Representation of a Starlark rule attribute type. These generally // have a one-to-one correspondence with functions defined at // https://bazel.build/rules/lib/toplevel/attr. enum AttributeType { UNKNOWN = 0; // A special case of STRING; all rules have exactly one implicit // attribute "name" of type NAME. NAME = 1; INT = 2; LABEL = 3; STRING = 4; STRING_LIST = 5; INT_LIST = 6; LABEL_LIST = 7; BOOLEAN = 8; LABEL_STRING_DICT = 9; STRING_DICT = 10; STRING_LIST_DICT = 11; OUTPUT = 12; OUTPUT_LIST = 13; LABEL_DICT_UNARY = 14; LABEL_LIST_DICT = 15; } // Representation of a Starlark rule definition. message RuleInfo { // In Stardoc and starlark_doc_extract output, this is the name under which // the rule is made accessible to a user of this module, including any structs // it is nested in, for example "foo.foo_library". // // In query output, this is the name under which the rule was defined (which // might be a private symbol prefixed with "_"). string rule_name = 1; // The documentation string of the rule. string doc_string = 2; // The attributes of the rule. repeated AttributeInfo attribute = 3; // Note: legacy Stardoc (0.5.x and earlier) does not set any fields below. // The module where and the name under which the rule was originally declared. OriginKey origin_key = 4; // The list of providers that the rule's implementation must return. Unset if // the rule lists no advertised providers. ProviderNameGroup advertised_providers = 5; // True if this is a test rule. bool test = 6; // True if this is an executable rule. // // Note: if test is true, executable is also true (test rules are implicitly // executable). bool executable = 7; } // Representation of a Starlark symbolic macro definition. // Note: symbolic macros (and thus, their documentation format) are an // experimental feature gated by the --experimental_enable_first_class_macros // flag. message MacroInfo { // The name under which the macro is made accessible to a user of this module, // including any structs it is nested in, for example "foo.foo_library". string macro_name = 1; // The documentation string of the macro. string doc_string = 2; // The attributes of the macro. repeated AttributeInfo attribute = 3; // The module where and the name under which the macro was originally // declared. OriginKey origin_key = 4; // True if this macro is a rule finalizer. bool finalizer = 5; } // Representation of a Starlark rule, repository rule, or module extension tag // attribute definition, comprised of an attribute name, and a schema defined by // a call to one of the 'attr' module methods enumerated at // https://bazel.build/rules/lib/toplevel/attr. message AttributeInfo { // The name of the attribute. string name = 1; // The documentation string of the attribute, supplied via the 'doc' // parameter to the schema-creation call. string doc_string = 2; // The type of the attribute, defined generally by which function is invoked // in the attr module. AttributeType type = 3; // If true, all targets of the rule must specify a value for this attribute. bool mandatory = 4; // The target(s) in this attribute must define all the providers of at least // one of the ProviderNameGroups in this list. If the Attribute Type is not a // label, a label list, or a label-keyed string dictionary, the field will be // left empty. For attributes of a repository rule or a module extension tag, // this attribute is meaningless and may be ignored. // TODO(b/290788853): ensure this field is always empty for attributes of a // repository rule or a module extension tag. repeated ProviderNameGroup provider_name_group = 5; // The string representation of the default value of this attribute. string default_value = 6; // If true, the attribute is non-configurable. bool nonconfigurable = 7; // If true, the attribute is defined in Bazel's native code, not in Starlark. bool natively_defined = 8; // If non-empty, the string representations of the allowed values for this // attribute. repeated string values = 9; } // Representation of a set of providers. message ProviderNameGroup { // The names of the providers. // // This field is only intended for rendering human-readable output. // Please use origin_key (a list of the same length and in the same order as // this field) for cross-references and tooling. // // Note: legacy Stardoc (0.5.x and earlier) is unable to extract the name in // some circumstances (for example, if the provider is nested in a struct), // and in that case, the provider name will be "Unknown Provider". repeated string provider_name = 1; // A list of unambiguous references to providers, of the same length and in // the same order as the provider_name list. // // For provider symbols, this means modules where and the names under which // the providers were originally declared. // // For legacy struct providers, origin_key.file is unset. // // Note: legacy Stardoc (0.5.x and earlier) does not set this field. repeated OriginKey origin_key = 2; } // Representation of Starlark function definition. message StarlarkFunctionInfo { // The name under which the function is made accessible to a user of this // module, including any structs it is nested in, for example // "foo.frobnicate". string function_name = 1; // The parameters for the function, in the following order: // - positional parameters // - keyword-only parameters // - residual varargs parameter (`*args`) // - residual keyword arguments parameter (`**kwargs`) // This order differs from the order in which parameters are listed in the // function's declaration (where positional parameters and keyword-only // parameters are separated either by `*` or `*args`). The declaration order // can be recovered by looking for the transition from ordinary/positional to // keyword-only. repeated FunctionParamInfo parameter = 2; // The documented description of the function (if specified in the function's // docstring). string doc_string = 3; // The return value for the function. FunctionReturnInfo return = 4; // The deprecation for the function. FunctionDeprecationInfo deprecated = 5; // The module where and the name under which the function was originally // declared. // // Note: legacy Stardoc (0.5.x and earlier) does not set this field. OriginKey origin_key = 6; } // Representation of the syntactic role of a given function parameter. enum FunctionParamRole { PARAM_ROLE_UNSPECIFIED = 0; // An ordinary parameter which may be used as a positional or by keyword. PARAM_ROLE_ORDINARY = 1; // A positional-only parameter; such parameters cannot be defined in pure // Starlark code, but exist in some natively-defined functions. PARAM_ROLE_POSITIONAL_ONLY = 2; // A keyword-only parameter, i.e. a non-vararg/kwarg parameter that follows // `*` or `*args` in the function's declaration. PARAM_ROLE_KEYWORD_ONLY = 3; // Residual varargs, typically `*args` in the function's declaration. PARAM_ROLE_VARARGS = 4; // Residual keyword arguments, typically `**kwargs` in the function's // declaration. PARAM_ROLE_KWARGS = 5; } // Representation of a Starlark function parameter definition. message FunctionParamInfo { // The name of the parameter. This does *not* include the `*` or `**` prefix // for varargs or residual keyword argument parameters. string name = 1; // The documented description of the parameter (if specified in the function's // docstring). string doc_string = 2; // If not an empty string, the default value of the parameter displayed // as a string. string default_value = 3; // If true, the default value is unset and a value is needed for this // parameter. This might be false even if defaultValue is empty in the case of // special parameter such as *args and **kwargs" bool mandatory = 4; // The parameter's syntactic role. FunctionParamRole role = 5; } message FunctionReturnInfo { // The documented return value of the function (if specified in the function's // docstring). string doc_string = 1; } message FunctionDeprecationInfo { // The documented deprecation of the function (if specified in the function's // docstring). string doc_string = 1; } // Representation of a Starlark provider field definition, comprised of // the field name and provider description. message ProviderFieldInfo { // The name of the field. string name = 1; // The description of the provider. string doc_string = 2; } // Representation of a Starlark provider definition. message ProviderInfo { // The name under which the provider is made accessible to a user of this // module, including any structs it is nested in, for example "foo.FooInfo". string provider_name = 1; // The description of the provider. string doc_string = 2; // The fields of the provider. repeated ProviderFieldInfo field_info = 3; // Note: legacy Stardoc (0.5.x and earlier) does not set any fields below. // The module where and the name under which the provider was originally // declared. OriginKey origin_key = 4; // The provider's init callback. StarlarkFunctionInfo init = 5; } // Representation of a Starlark aspect definition. message AspectInfo { // The name under which the aspect is made accessible to a user of this // module, including any structs it is nested in, for example // "foo.foo_aspect". string aspect_name = 1; // The documentation string of the aspect. string doc_string = 2; // The rule attributes along which the aspect propagates. repeated string aspect_attribute = 3; // The attributes of the aspect. repeated AttributeInfo attribute = 4; // The module where and the name under which the aspect was originally // declared. // // Note: legacy Stardoc (0.5.x and earlier) does not set this field. OriginKey origin_key = 5; } // Representation of a Bazel module extension, i.e. the object returned by // calling `module_extension(...)`. // // Note: legacy Stardoc (0.5.x and earlier) does not emit this message. message ModuleExtensionInfo { // The name under which the extension is made accessible to a user of this // Starlark module. string extension_name = 1; // The documentation string of the extension. string doc_string = 2; // The tag classes of the extension. repeated ModuleExtensionTagClassInfo tag_class = 3; // The Starlark module where the Bazel module extension was originally // declared; origin_key.name is currently never set. // TODO(arostovtsev): attempt to retrieve the name under which the module // extension was originally declared if it was declared as a global. OriginKey origin_key = 4; } // Representation of a Bazel module extension tag class. message ModuleExtensionTagClassInfo { // The name of the tag for this tag class. string tag_name = 1; // The documentation string of the tag class. string doc_string = 2; // The tag class's attributes. repeated AttributeInfo attribute = 3; } // Representation of a Bazel repository rule, i.e. the object returned by // calling `repository_rule(...)`. // // Note: legacy Stardoc (0.5.x and earlier) does not emit this message, instead // using RuleInfo. message RepositoryRuleInfo { // The name under which the repository rule is made accessible to a user of // this Starlark module. string rule_name = 1; // The documentation string of the repository rule. string doc_string = 2; // The attributes of the repository rule. repeated AttributeInfo attribute = 3; // Environment variables that this repository rule depends on. repeated string environ = 4; // The Starlark module where and the name under which the repository rule was // originally declared. OriginKey origin_key = 5; } // Representation of a Starlark symbol whose value is of type which lacks // built-in docstring and needs to be documented using `#:`-prefixed doc // comments; for example, a bool, dict, float, int, list, range, set, string, // struct, or tuple. message StarlarkOtherSymbolInfo { // The name of the symbol. string name = 1; // The content of the symbol's doc comments. string doc = 2; // The symbol's value's data type. string type_name = 3; } // Representation of the origin of a rule, provider, aspect, or function. // Intended to be used for building unambiguous cross-references: for example, // between an element of a ProviderNameGroup required by a rule attribute and // its corresponding ProviderInfo. message OriginKey { // The name under which the entity was originally exported. Unset when the // entity was not exported in its module. string name = 1; // The display form of the label of the module file in which the entity was // originally declared (as seen from the starlark_doc_extract or Stardoc // target's repo), or "" for Bazel's built-in entities implemented in // Java. Unset when there is no module file (such as for legacy struct // providers, when the module is a REPL, or in Bazel's internal tests). string file = 2; } stardoc-0.8.1/stardoc/stardoc.bzl000066400000000000000000000155321513642521100167740ustar00rootroot00000000000000# Copyright 2018 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Starlark rule for stardoc: a documentation generator tool written in Java.""" load("@bazel_skylib//rules:copy_file.bzl", "copy_file") load("//stardoc/private:stardoc.bzl", "stardoc_markdown_renderer") def stardoc( *, name, input, out, deps = [], format = "markdown", symbol_names = [], renderer = Label("//stardoc:renderer"), aspect_template = Label("//stardoc:templates/markdown_tables/aspect.vm"), func_template = Label("//stardoc:templates/markdown_tables/func.vm"), macro_template = Label("//stardoc:templates/markdown_tables/macro.vm"), header_template = Label("//stardoc:templates/markdown_tables/header.vm"), table_of_contents_template = None, provider_template = Label("//stardoc:templates/markdown_tables/provider.vm"), rule_template = Label("//stardoc:templates/markdown_tables/rule.vm"), repository_rule_template = Label("//stardoc:templates/markdown_tables/repository_rule.vm"), module_extension_template = Label("//stardoc:templates/markdown_tables/module_extension.vm"), footer_template = None, render_main_repo_name = True, stamp = -1, **kwargs): """Generates documentation for exported starlark rule definitions in a target starlark file. Args: name: The name of the stardoc target. input: The starlark file to generate documentation for (mandatory). out: The file to which documentation will be output (mandatory). deps: A list of bzl_library dependencies which the input depends on. format: The format of the output file. Valid values: 'markdown' or 'proto'. symbol_names: A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated. renderer: The location of the renderer tool. aspect_template: The input file template for generating documentation of aspects header_template: The input file template for the header of the output documentation. table_of_contents_template: The input file template for the table of contents of the output documentation. This is unset by default for backwards compatibility. Use `Label("@stardoc//stardoc:templates/markdown_tables/table_of_contents.vm")` for the default template. func_template: The input file template for generating documentation of functions, including legacy macros. macro_template: The input file template for generating documentation of symbolic macros. provider_template: The input file template for generating documentation of providers. rule_template: The input file template for generating documentation of rules. repository_rule_template: The input file template for generating documentation of repository rules. module_extension_template: The input file template for generating documentation of module extensions. footer_template: The input file template for generating the footer of the output documentation. Optional. render_main_repo_name: Render labels in the main repository with a repo component (either the module name or workspace name). stamp: Whether to provide stamping information to templates, where it can be accessed via `$util.formatBuildTimestamp()` and`$stamping`. Example: ```vm Built on `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "yyyy-MM-dd HH:mm")` ``` Possible values:
  • `stamp = 1`: Always provide stamping information, even in [--nostamp](https://bazel.build/docs/user-manual#stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.
  • `stamp = 0`: Do not provide stamping information.
  • `stamp = -1`: Provide stamping information only if the [--stamp](https://bazel.build/docs/user-manual#stamp) flag is set.
Stamped targets are not rebuilt unless their dependencies change. **kwargs: Further arguments to pass to stardoc. """ if format not in ["markdown", "proto"]: fail("`format` must be \"markdown\" or \"proto\"") auxiliary_target_kwargs = { "tags": ["manual"], "visibility": ["//visibility:private"], } if "testonly" in kwargs: auxiliary_target_kwargs["testonly"] = kwargs["testonly"] if "tags" in kwargs: user_tags = kwargs["tags"] # Merge tags from kwargs without duplicating "manual" auxiliary_target_kwargs["tags"] += [tag for tag in user_tags if tag not in auxiliary_target_kwargs["tags"]] if format == "proto" and Label(name + ".binaryproto") == Label(out): extractor_is_main_target = True extractor_name = name else: extractor_is_main_target = False extractor_name = name + ".extract" proto_name = extractor_name + ".binaryproto" native.starlark_doc_extract( name = extractor_name, src = input, deps = deps, render_main_repo_name = render_main_repo_name, symbol_names = symbol_names, **(kwargs if extractor_is_main_target else auxiliary_target_kwargs) ) if format == "markdown": stardoc_markdown_renderer( name = name, src = proto_name, out = out, renderer = renderer, aspect_template = aspect_template, func_template = func_template, header_template = header_template, table_of_contents_template = table_of_contents_template, provider_template = provider_template, rule_template = rule_template, repository_rule_template = repository_rule_template, module_extension_template = module_extension_template, macro_template = macro_template, footer_template = footer_template, stamp = stamp, **kwargs ) elif format == "proto" and not extractor_is_main_target: copy_file( name = name, src = proto_name, out = out, **kwargs ) stardoc-0.8.1/stardoc/templates/000077500000000000000000000000001513642521100166145ustar00rootroot00000000000000stardoc-0.8.1/stardoc/templates/html_tables/000077500000000000000000000000001513642521100211125ustar00rootroot00000000000000stardoc-0.8.1/stardoc/templates/html_tables/aspect.vm000066400000000000000000000021511513642521100227340ustar00rootroot00000000000000 #[[##]]# ${aspectName}
${util.loadStatement($aspectName)}

${util.aspectSummary($aspectName, $aspectInfo)}
$aspectInfo.getDocString() #[[###]]# Aspect Attributes #if (!$aspectInfo.getAspectAttributeList().isEmpty()) #foreach ($aspectAttribute in $aspectInfo.getAspectAttributeList()) #end
${aspectAttribute} String; required.
#end #[[###]]# Attributes #if (!$aspectInfo.getAttributeList().isEmpty()) #foreach ($attribute in $aspectInfo.getAttributeList()) #end
${attribute.name} ${util.attributeTypeString($attribute)}; ${util.mandatoryString($attribute)} #if (!$attribute.docString.isEmpty())

${attribute.docString.trim()}

#end
#end stardoc-0.8.1/stardoc/templates/html_tables/func.vm000066400000000000000000000020231513642521100224060ustar00rootroot00000000000000 #[[##]]# ${funcInfo.functionName}
${util.loadStatement($funcInfo.functionName)}

${util.funcSummary($funcInfo)}
${util.htmlEscape($funcInfo.docString)} #if (!$funcInfo.getParameterList().isEmpty()) #[[###]]# Parameters #foreach ($param in $funcInfo.getParameterList()) #end
${param.name} ${util.mandatoryString($param)}. #if(!$param.getDefaultValue().isEmpty()) default is $param.getDefaultValue() #end #if (!$param.docString.isEmpty())

${param.docString.trim()}

#end
#end #if (!$funcInfo.getReturn().docString.isEmpty()) #[[###]]# Returns ${util.htmlEscape($funcInfo.getReturn().docString)} #end #if (!$funcInfo.getDeprecated().docString.isEmpty()) #[[###]]# Deprecated ${util.htmlEscape($funcInfo.getDeprecated().docString)} #end stardoc-0.8.1/stardoc/templates/html_tables/header.vm000066400000000000000000000001171513642521100227050ustar00rootroot00000000000000 ${moduleDocstring} stardoc-0.8.1/stardoc/templates/html_tables/macro.vm000066400000000000000000000015141513642521100225600ustar00rootroot00000000000000 #[[##]]# ${macroName}
${util.loadStatement($macroName)}

${util.macroSummary($macroName, $macroInfo)}
#if ($macroInfo.finalizer) This macro is a rule finalizer. #end ${util.htmlEscape($macroInfo.docString)} #[[###]]# Attributes #if (!$macroInfo.getAttributeList().isEmpty()) #foreach ($attribute in $macroInfo.getAttributeList()) #end
${attribute.name} ${util.attributeTypeString($attribute)}; ${util.mandatoryString($attribute)} #if (!$attribute.docString.isEmpty())

${attribute.docString.trim()}

#end
#end stardoc-0.8.1/stardoc/templates/html_tables/module_extension.vm000066400000000000000000000020171513642521100250370ustar00rootroot00000000000000 #[[##]]# ${extensionName}
${util.moduleExtensionSummary($extensionName, $extensionInfo)}
#if (!$extensionInfo.docString.isEmpty()) ${extensionInfo.docString} #end #if (!$extensionInfo.getTagClassList().isEmpty()) **TAG CLASSES** #foreach ($tagClass in $extensionInfo.getTagClassList()) #[[###]]# ${tagClass.tagName} #if (!$tagClass.docString.isEmpty()) ${tagClass.docString} #end **Attributes** #if (!$tagClass.getAttributeList().isEmpty()) #foreach ($attribute in $tagClass.getAttributeList()) #end
${attribute.name} ${util.attributeTypeString($attribute)}; ${util.mandatoryString($attribute)} #if (!$attribute.docString.isEmpty())

${attribute.docString.trim()}

#end
#end #end #end stardoc-0.8.1/stardoc/templates/html_tables/provider.vm000066400000000000000000000041631513642521100233140ustar00rootroot00000000000000 #if ($providerInfo.hasInit() && $initParamNamesEqualFieldNames && !$initParamsHaveDistinctDocs && !$initParamsWithInferredDocs.isEmpty()) #set ($mergeParamsAndFields = true) #else #set ($mergeParamsAndFields = false) #end #[[##]]# ${providerName}
${util.loadStatement($providerName)}

#if ($providerInfo.hasInit() && !$mergeParamsAndFields)
${util.providerSummaryWithInitAnchor($providerName, $providerInfo)}
#else
${util.providerSummary($providerName, $providerInfo)}
#end
#if (!$providerInfo.docString.isEmpty()) ${providerInfo.docString} #end #if ($providerInfo.hasInit() && !$providerInfo.init.deprecated.docString.isEmpty()) #[[###]]# Deprecated ${providerInfo.init.deprecated.docString} #end #if ($providerInfo.hasInit() && !$providerInfo.init.parameterList.isEmpty() && !$mergeParamsAndFields) #[[###]]# Constructor parameters #foreach ($param in $initParamsWithInferredDocs) #end
${param.name} ${util.mandatoryString($param)}. #if(!$param.getDefaultValue().isEmpty()) default is $param.getDefaultValue() #end #if (!$param.docString.isEmpty())

${param.docString.trim()}

#end
#end #if (!$providerInfo.fieldInfoList.isEmpty()) #[[###]]# Fields #if ($mergeParamsAndFields) #foreach ($param in $initParamsWithInferredDocs) #end #else #foreach ($field in $providerInfo.fieldInfoList) #end #end
${param.name} ${util.mandatoryString($param)}. #if(!$param.getDefaultValue().isEmpty()) default is $param.getDefaultValue() #end #if (!$param.docString.isEmpty())

${param.docString.trim()}

#end
${field.name}

${field.docString}

#end stardoc-0.8.1/stardoc/templates/html_tables/repository_rule.vm000066400000000000000000000017061513642521100247300ustar00rootroot00000000000000 #[[##]]# ${ruleName}
${util.loadStatement($ruleName)}

${util.repositoryRuleSummary($ruleName, $ruleInfo)}
#if (!$ruleInfo.docString.isEmpty()) ${ruleInfo.docString} #end **ATTRIBUTES** #if (!$ruleInfo.getAttributeList().isEmpty()) #foreach ($attribute in $ruleInfo.getAttributeList()) #end
${attribute.name} ${util.attributeTypeString($attribute)}; ${util.mandatoryString($attribute)} #if (!$attribute.docString.isEmpty())

${attribute.docString.trim()}

#end
#end #if (!$ruleInfo.getEnvironList().isEmpty()) **ENVIRONMENT VARIABLES** This repository rule depends on the following environment variables: #foreach ($var in $ruleInfo.getEnvironList()) * ${util.markdownCodeSpan($var)} #end #end stardoc-0.8.1/stardoc/templates/html_tables/rule.vm000066400000000000000000000015421513642521100224270ustar00rootroot00000000000000 #[[##]]# ${ruleName}
${util.loadStatement($ruleName)}

${util.ruleSummary($ruleName, $ruleInfo)}
${util.htmlEscape($ruleInfo.docString)} #[[###]]# Attributes #if (!$ruleInfo.getAttributeList().isEmpty()) #foreach ($attribute in $ruleInfo.getAttributeList()) #end
${attribute.name} ${util.attributeTypeString($attribute)}; ${util.mandatoryString($attribute)} #if (!$attribute.docString.isEmpty())

${attribute.docString.trim()}

#end #if (!$attribute.getProviderNameGroupList().isEmpty())

The dependencies of this attribute must provide: ${util.attributeProviders($attribute)}

#end
#end stardoc-0.8.1/stardoc/templates/markdown_tables/000077500000000000000000000000001513642521100217705ustar00rootroot00000000000000stardoc-0.8.1/stardoc/templates/markdown_tables/aspect.vm000066400000000000000000000020071513642521100236120ustar00rootroot00000000000000 #[[##]]# ${aspectName}
${util.loadStatement($aspectName)}

${util.aspectSummary($aspectName, $aspectInfo)}
$aspectInfo.getDocString() **ASPECT ATTRIBUTES** #if (!$aspectInfo.getAspectAttributeList().isEmpty()) | Name | Type | | :------------- | :------------- | #foreach ($aspectAttribute in $aspectInfo.getAspectAttributeList()) | $aspectAttribute| String | #end #end **ATTRIBUTES** #if (!$aspectInfo.getAttributeList().isEmpty()) | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | #foreach ($attribute in $aspectInfo.getAttributeList()) | $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.markdownCodeSpan($attribute.defaultValue)} #end | #end #end stardoc-0.8.1/stardoc/templates/markdown_tables/func.vm000066400000000000000000000016151513642521100232720ustar00rootroot00000000000000 #[[##]]# ${funcInfo.functionName}
${util.loadStatement($funcInfo.functionName)}

${util.funcSummary($funcInfo)}
${funcInfo.docString} #if (!$funcInfo.getParameterList().isEmpty()) **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | #foreach ($param in $funcInfo.getParameterList()) | $param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else

-

#end | #if(!$param.getDefaultValue().isEmpty()) ${util.markdownCodeSpan($param.defaultValue)} #else none #end| #end #end #if (!$funcInfo.getReturn().docString.isEmpty()) **RETURNS** ${funcInfo.getReturn().docString} #end #if (!$funcInfo.getDeprecated().docString.isEmpty()) **DEPRECATED** ${funcInfo.getDeprecated().docString} #end stardoc-0.8.1/stardoc/templates/markdown_tables/header.vm000066400000000000000000000001171513642521100235630ustar00rootroot00000000000000 ${moduleDocstring} stardoc-0.8.1/stardoc/templates/markdown_tables/macro.vm000066400000000000000000000016121513642521100234350ustar00rootroot00000000000000 #[[##]]# ${macroName}
${util.loadStatement($macroName)}

${util.macroSummary($macroName, $macroInfo)}
#if ($macroInfo.finalizer) This macro is a rule finalizer. #end ${macroInfo.docString} **ATTRIBUTES** #if (!$macroInfo.getAttributeList().isEmpty()) | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | #foreach ($attribute in $macroInfo.getAttributeList()) | $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.markdownCodeSpan($attribute.defaultValue)} #end | #end #end stardoc-0.8.1/stardoc/templates/markdown_tables/module_extension.vm000066400000000000000000000020611513642521100257140ustar00rootroot00000000000000 #[[##]]# ${extensionName}
${util.moduleExtensionSummary($extensionName, $extensionInfo)}
#if (!$extensionInfo.docString.isEmpty()) ${extensionInfo.docString} #end #if (!$extensionInfo.getTagClassList().isEmpty()) **TAG CLASSES** #foreach ($tagClass in $extensionInfo.getTagClassList()) #[[###]]# ${tagClass.tagName} #if (!$tagClass.docString.isEmpty()) ${tagClass.docString} #end **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | #foreach ($attribute in $tagClass.getAttributeList()) | $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.markdownCodeSpan($attribute.defaultValue)} #end | #end #end #end stardoc-0.8.1/stardoc/templates/markdown_tables/provider.vm000066400000000000000000000043221513642521100241670ustar00rootroot00000000000000 #if ($providerInfo.hasInit() && $initParamNamesEqualFieldNames && !$initParamsHaveDistinctDocs && !$initParamsWithInferredDocs.isEmpty()) #set ($mergeParamsAndFields = true) #else #set ($mergeParamsAndFields = false) #end #[[##]]# ${providerName}
${util.loadStatement($providerName)}

#if ($providerInfo.hasInit() && !$mergeParamsAndFields)
${util.providerSummaryWithInitAnchor($providerName, $providerInfo)}
#else
${util.providerSummary($providerName, $providerInfo)}
#end
#if (!$providerInfo.docString.isEmpty()) ${providerInfo.docString} #end #if ($providerInfo.hasInit() && !$providerInfo.init.deprecated.docString.isEmpty()) **DEPRECATED** ${providerInfo.init.deprecated.docString} #end #if ($providerInfo.hasInit() && !$providerInfo.init.parameterList.isEmpty() && !$mergeParamsAndFields) **CONSTRUCTOR PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | #foreach ($param in $initParamsWithInferredDocs) | $param.name | ## #if (!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} ## #else

-

## #end | ## #if (!$param.getDefaultValue().isEmpty()) ${util.markdownCodeSpan($param.defaultValue)} ## #else none ## #end | #end #end #if (!$providerInfo.fieldInfoList.isEmpty()) **FIELDS** #if ($mergeParamsAndFields) | Name | Description #if ($initParamsHaveDefaultValues)| Default Value #end| | :------------- | :------------- #if ($initParamsHaveDefaultValues)| :------------- #end| #foreach ($param in $initParamsWithInferredDocs) | $param.name | ## #if (!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} ## #else

-

## #end #if($initParamsHaveDefaultValues) | ## #if (!$param.getDefaultValue().isEmpty()) ${util.markdownCodeSpan($param.defaultValue)} ## #else none ## #end #end | #end #else | Name | Description | | :------------- | :------------- | #foreach ($field in $providerInfo.fieldInfoList) | $field.name | #if(!$field.docString.isEmpty()) ${util.markdownCellFormat($field.docString)} #else - #end | #end #end #end stardoc-0.8.1/stardoc/templates/markdown_tables/repository_rule.vm000066400000000000000000000020341513642521100256010ustar00rootroot00000000000000 #[[##]]# ${ruleName}
${util.loadStatement($ruleName)}

${util.repositoryRuleSummary($ruleName, $ruleInfo)}
#if (!$ruleInfo.docString.isEmpty()) ${ruleInfo.docString} #end **ATTRIBUTES** #if (!$ruleInfo.getAttributeList().isEmpty()) | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | #foreach ($attribute in $ruleInfo.getAttributeList()) | $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.markdownCodeSpan($attribute.defaultValue)} #end | #end #end #if (!$ruleInfo.getEnvironList().isEmpty()) **ENVIRONMENT VARIABLES** This repository rule depends on the following environment variables: #foreach ($var in $ruleInfo.getEnvironList()) * ${util.markdownCodeSpan($var)} #end #end stardoc-0.8.1/stardoc/templates/markdown_tables/rule.vm000066400000000000000000000014011513642521100232770ustar00rootroot00000000000000 #[[##]]# ${ruleName}
${util.loadStatement($ruleName)}

${util.ruleSummary($ruleName, $ruleInfo)}
${ruleInfo.docString} **ATTRIBUTES** #if (!$ruleInfo.getAttributeList().isEmpty()) | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | #foreach ($attribute in $ruleInfo.getAttributeList()) | $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.markdownCodeSpan($attribute.defaultValue)} #end | #end #end stardoc-0.8.1/stardoc/templates/markdown_tables/table_of_contents.vm000066400000000000000000000022011513642521100260170ustar00rootroot00000000000000 #if (!$ruleInfos.isEmpty()) #[[##]]# Rules #foreach ($rule in $ruleInfos) - [$rule.ruleName](#$rule.ruleName) #end #end #if (!$providerInfos.isEmpty()) #[[##]]# Providers #foreach ($providerInfo in $providerInfos) - [$providerInfo.providerName](#$providerInfo.providerName) #end #end #if (!$macroInfos.isEmpty()) #[[##]]# Macros #foreach ($macroInfo in $macroInfos) - [$macroInfo.macroName](#$macroInfo.macroName) #end #end #if (!$functionInfos.isEmpty()) #[[##]]# Functions #foreach ($functionInfo in $functionInfos) - [$functionInfo.functionName](#$functionInfo.functionName) #end #end #if (!$aspectInfos.isEmpty()) #[[##]]# Aspects #foreach ($aspectInfo in $aspectInfos) - [$aspectInfo.aspectName](#$aspectInfo.aspectName) #end #end #if (!$repositoryRuleInfos.isEmpty()) #[[##]]# Repository Rules #foreach ($repositoryRuleInfo in $repositoryRuleInfos) - [$repositoryRuleInfo.ruleName](#$repositoryRuleInfo.ruleName) #end #end #if (!$moduleExtensionInfos.isEmpty()) #[[##]]# Module Extensions #foreach ($moduleExtensionInfo in $moduleExtensionInfos) - [$moduleExtensionInfo.extensionName](#$moduleExtensionInfo.extensionName) #end #end stardoc-0.8.1/test/000077500000000000000000000000001513642521100141365ustar00rootroot00000000000000stardoc-0.8.1/test/BUILD000066400000000000000000000324341513642521100147260ustar00rootroot00000000000000load("@bazel_skylib//:bzl_library.bzl", "bzl_library") load("@bazel_skylib//rules:diff_test.bzl", "diff_test") load("@rules_shell//shell:sh_test.bzl", "sh_test") load(":stardoc_test.bzl", "self_gen_test", "stardoc_test") package( default_applicable_licenses = ["//:license"], default_testonly = True, ) licenses(["notice"]) # Apache 2.0 self_gen_test( name = "stardoc_self_gen_test", golden_file = "//stardoc:stardoc_doc.md", stardoc_doc = "//:stardoc_rule_doc", ) exports_files(["testdata/fakedeps/dep.bzl"]) stardoc_test( name = "input_template_test", aspect_template = "testdata/input_template_test/aspect.vm", func_template = "testdata/input_template_test/func.vm", golden_file = "testdata/input_template_test/golden.md", header_template = "testdata/input_template_test/header.vm", input_file = "testdata/input_template_test/input.bzl", provider_template = "testdata/input_template_test/provider.vm", rule_template = "testdata/input_template_test/rule.vm", ) stardoc_test( name = "angle_bracket_test", golden_file = "testdata/angle_bracket_test/golden.md", input_file = "testdata/angle_bracket_test/input.bzl", ) stardoc_test( name = "proto_format_test", format = "proto", golden_file = "testdata/proto_format_test/golden.binaryproto", input_file = "testdata/proto_format_test/input.bzl", # Golden output was generated with Bazel 7.4.1 and may differ in other versions tags = [ "bazel_7", "manual", ], ) stardoc_test( name = "simple_test", golden_file = "testdata/simple_test/golden.md", input_file = "testdata/simple_test/input.bzl", symbol_names = ["my_rule"], ) stardoc_test( name = "repo_rules_test", golden_file = "testdata/repo_rules_test/golden.md", input_file = "testdata/repo_rules_test/input.bzl", ) stardoc_test( name = "repo_rules_bazel_8_test", golden_file = "testdata/repo_rules_test/bazel_8_golden.md", input_file = "testdata/repo_rules_test/input.bzl", tags = [ "bazel_8", "manual", ], ) stardoc_test( name = "module_extension_test", golden_file = "testdata/module_extension_test/golden.md", input_file = "testdata/module_extension_test/input.bzl", ) stardoc_test( name = "unknown_name_test", golden_file = "testdata/unknown_name_test/golden.md", input_file = "testdata/unknown_name_test/input.bzl", ) stardoc_test( name = "multiple_rules_test", golden_file = "testdata/multiple_rules_test/golden.md", input_file = "testdata/multiple_rules_test/input.bzl", ) stardoc_test( name = "multiple_files_test", golden_file = "testdata/multiple_files_test/golden.md", input_file = "testdata/multiple_files_test/input.bzl", deps = [ "testdata/multiple_files_test/dep.bzl", "testdata/multiple_files_test/inner_dep.bzl", ], ) stardoc_test( name = "multiple_files_noenable_bzlmod_test", golden_file = "testdata/multiple_files_test/noenable_bzlmod_golden.md", input_file = "testdata/multiple_files_test/input.bzl", tags = [ "manual", "noenable_bzlmod", ], deps = [ "testdata/multiple_files_test/dep.bzl", "testdata/multiple_files_test/inner_dep.bzl", ], ) stardoc_test( name = "same_level_file_test", golden_file = "//test/testdata/same_level_file_test:golden.md", input_file = "//test/testdata/same_level_file_test:input.bzl", symbol_names = ["my_rule"], deps = [ "//test/testdata/same_level_file_test:dep.bzl", ], ) stardoc_test( name = "same_level_file_noenable_bzlmod_test", golden_file = "//test/testdata/same_level_file_test:noenable_bzlmod_golden.md", input_file = "//test/testdata/same_level_file_test:input.bzl", symbol_names = ["my_rule"], tags = [ "manual", "noenable_bzlmod", ], deps = [ "//test/testdata/same_level_file_test:dep.bzl", ], ) stardoc_test( name = "scl_test", golden_file = "testdata/scl_test/golden.md", input_file = "testdata/scl_test/input.scl", ) stardoc_test( name = "misc_apis_test", golden_file = "testdata/misc_apis_test/golden.md", input_file = "testdata/misc_apis_test/input.bzl", ) stardoc_test( name = "attribute_types_test", golden_file = "testdata/attribute_types_test/golden.md", input_file = "testdata/attribute_types_test/input.bzl", symbol_names = ["my_rule"], ) stardoc_test( name = "filter_rules_test", golden_file = "testdata/filter_rules_test/golden.md", input_file = "testdata/filter_rules_test/input.bzl", symbol_names = [ "my_rule", "allowlisted_dep_rule", ], deps = [ "testdata/filter_rules_test/dep.bzl", ], ) stardoc_test( name = "provider_basic_test", golden_file = "testdata/provider_basic_test/golden.md", input_file = "testdata/provider_basic_test/input.bzl", ) stardoc_test( name = "function_basic_test", golden_file = "testdata/function_basic_test/golden.md", input_file = "testdata/function_basic_test/input.bzl", ) stardoc_test( name = "function_wrap_multiple_lines_test", golden_file = "testdata/function_wrap_multiple_lines_test/golden.md", input_file = "testdata/function_wrap_multiple_lines_test/input.bzl", ) stardoc_test( name = "namespace_test", golden_file = "testdata/namespace_test/golden.md", input_file = "testdata/namespace_test/input.bzl", ) stardoc_test( name = "namespace_test_with_allowlist", golden_file = "testdata/namespace_test/golden.md", input_file = "testdata/namespace_test/input.bzl", symbol_names = [ "my_namespace", ], ) stardoc_test( name = "multi_level_namespace_test", golden_file = "testdata/multi_level_namespace_test/golden.md", input_file = "testdata/multi_level_namespace_test/input.bzl", ) stardoc_test( name = "multi_level_namespace_test_with_allowlist", golden_file = "testdata/multi_level_namespace_test_with_allowlist/golden.md", input_file = "testdata/multi_level_namespace_test_with_allowlist/input.bzl", symbol_names = [ "my_namespace", "other_namespace.foo.nothing", ], ) stardoc_test( name = "macro_kwargs_legacy_test", golden_file = "testdata/macro_kwargs_test/legacy_golden.md", input_file = "testdata/macro_kwargs_test/input.bzl", # Golden output was generated with Bazel 7.4.1 and may differ in other versions tags = [ "bazel_7", "manual", ], ) stardoc_test( name = "macro_kwargs_test", golden_file = "testdata/macro_kwargs_test/golden.md", input_file = "testdata/macro_kwargs_test/input.bzl", ) stardoc_test( name = "pure_markdown_template_test", golden_file = "testdata/pure_markdown_template_test/golden.md", input_file = "testdata/pure_markdown_template_test/input.bzl", ) stardoc_test( name = "struct_default_value_test", golden_file = "testdata/struct_default_value_test/golden.md", input_file = "testdata/struct_default_value_test/input.bzl", ) stardoc_test( name = "aspect_test", golden_file = "testdata/aspect_test/golden.md", input_file = "testdata/aspect_test/input.bzl", ) stardoc_test( name = "providers_for_attributes_test", golden_file = "testdata/providers_for_attributes_test/golden.md", input_file = "testdata/providers_for_attributes_test/input.bzl", deps = [ "testdata/providers_for_attributes_test/dep.bzl", ], ) stardoc_test( name = "html_tables_template_test", golden_file = "testdata/html_tables_template_test/golden.md", input_file = "testdata/html_tables_template_test/input.bzl", test = "html_tables", ) stardoc_test( name = "attribute_defaults_test", golden_file = "testdata/attribute_defaults_test/golden.md", input_file = "testdata/attribute_defaults_test/input.bzl", ) stardoc_test( name = "config_apis_test", golden_file = "testdata/config_apis_test/golden.md", input_file = "testdata/config_apis_test/input.bzl", ) stardoc_test( name = "footer_test", footer_template = "testdata/footer_test/footer_template.vm", golden_file = "testdata/footer_test/golden.md", input_file = "testdata/footer_test/input.bzl", ) bzl_library( name = "table_of_contents_test_deps", srcs = [ "testdata/aspect_test/input.bzl", "testdata/function_basic_test/input.bzl", "testdata/module_extension_test/input.bzl", "testdata/provider_basic_test/input.bzl", "testdata/repo_rules_test/input.bzl", "testdata/simple_test/input.bzl", "testdata/symbolic_macro_test/input.bzl", ], ) stardoc_test( name = "table_of_contents_test", golden_file = "testdata/table_of_contents_test/golden.md", input_file = "testdata/table_of_contents_test/input.bzl", table_of_contents_template = "//stardoc:templates/markdown_tables/table_of_contents.vm", deps = [":table_of_contents_test_deps"], ) stardoc_test( name = "table_of_contents_bazel_8_test", golden_file = "testdata/table_of_contents_test/bazel_8_golden.md", input_file = "testdata/table_of_contents_test/input.bzl", table_of_contents_template = "//stardoc:templates/markdown_tables/table_of_contents.vm", tags = [ "bazel_8", "manual", ], deps = [":table_of_contents_test_deps"], ) stardoc_test( name = "table_of_contents_noenable_bzlmod_test", golden_file = "testdata/table_of_contents_test/noenable_bzlmod_golden.md", input_file = "testdata/table_of_contents_test/input.bzl", table_of_contents_template = "//stardoc:templates/markdown_tables/table_of_contents.vm", tags = [ "manual", "noenable_bzlmod", ], deps = [":table_of_contents_test_deps"], ) stardoc_test( name = "stamping_test", golden_file = "testdata/stamping_test/golden.md", header_template = "testdata/stamping_test/stamping_header.vm", input_file = "testdata/stamping_test/input.bzl", stamp = 1, ) stardoc_test( name = "stamping_with_stamping_off_test", golden_file = "testdata/stamping_test/golden_stamping_off.md", header_template = "testdata/stamping_test/stamping_header_stamping_off.vm", input_file = "testdata/stamping_test/input.bzl", stamp = 0, ) stardoc_test( name = "symbolic_macro_test", golden_file = "testdata/symbolic_macro_test/golden.md", input_file = "testdata/symbolic_macro_test/input.bzl", ) stardoc_test( name = "symbolic_macro_finalizer_test", golden_file = "testdata/symbolic_macro_finalizer_test/golden.md", input_file = "testdata/symbolic_macro_finalizer_test/input.bzl", ) stardoc_test( name = "symbolic_macro_inherit_attrs_test", golden_file = "testdata/symbolic_macro_inherit_attrs_test/golden.md", input_file = "testdata/symbolic_macro_inherit_attrs_test/input.bzl", # Inherited default rule attributes vary depending on Bazel version tags = [ "bazel_9", "manual", ], ) stardoc_test( name = "symbolic_macro_inherit_attrs_bazel_8_test", golden_file = "testdata/symbolic_macro_inherit_attrs_test/bazel_8_golden.md", input_file = "testdata/symbolic_macro_inherit_attrs_test/input.bzl", # Inherited default rule attributes vary depending on Bazel version tags = [ "bazel_8", "manual", ], ) sh_test( name = "local_repository_test", srcs = ["diff_test_runner.sh"], args = [ "$(location @local_repository_test//:output.md)", "$(location @local_repository_test//:golden.md)", ], data = [ "@local_repository_test//:golden.md", "@local_repository_test//:output.md", ], tags = [ "manual", "noenable_bzlmod", ], ) # Consistency tests for WORKSPACE-related .bzl files vs. MODULE.bazel genrule( name = "stardoc_maven_artifacts_in_deps_bzl", srcs = ["//:deps.bzl"], outs = ["stardoc_maven_artifacts_in_deps_bzl.txt"], # Remove all lines except those from 'STARDOC_MAVEN_ARTIFACTS = [' to next ']' cmd = "sed -e '/STARDOC_MAVEN_ARTIFACTS = \\[/,/\\]/!d' $< >$@", ) genrule( name = "stardoc_maven_artifacts_in_module_bazel", srcs = ["//:MODULE.bazel"], outs = ["stardoc_maven_artifacts_in_module_bazel.txt"], # Remove all lines except those from 'STARDOC_MAVEN_ARTIFACTS = [' to next ']' cmd = "sed -e '/STARDOC_MAVEN_ARTIFACTS = \\[/,/\\]/!d' $< >$@", ) diff_test( name = "stardoc_maven_artifacts_consistency_test", failure_message = "STARDOC_MAVEN_ARTIFACTS in deps.bzl and MODULE.bazel are inconsistent", file1 = "stardoc_maven_artifacts_in_deps_bzl", file2 = "stardoc_maven_artifacts_in_module_bazel", ) genrule( name = "stardoc_version_in_version_bzl", srcs = ["//:version.bzl"], outs = ["stardoc_version_in_version_bzl.txt"], # Find first line starting containing 'version = ' and extract the string value cmd = "grep -m 1 'version = ' $< | sed -e 's/.*version = \\(\".*\"\\).*/\\1/' >$@", ) genrule( name = "stardoc_version_in_module_bazel", srcs = ["//:MODULE.bazel"], outs = ["stardoc_version_in_module_bazel.txt"], # Find first line starting containing 'version = ' and extract the string value cmd = "grep -m 1 'version = ' $< | sed -e 's/.*version = \\(\".*\"\\).*/\\1/' >$@", ) diff_test( name = "stardoc_version_consistency_test", failure_message = "version in version.bzl and MODULE.bazel is inconsistent", file1 = "stardoc_version_in_version_bzl", file2 = "stardoc_version_in_module_bazel", ) stardoc-0.8.1/test/bzlmod/000077500000000000000000000000001513642521100154255ustar00rootroot00000000000000stardoc-0.8.1/test/bzlmod/.bazelrc000066400000000000000000000003711513642521100170510ustar00rootroot00000000000000common --enable_bzlmod build --java_language_version=11 build --tool_java_language_version=11 # Incompatible flags which we always want in development build --incompatible_disable_starlark_host_transitions build --incompatible_disallow_empty_glob stardoc-0.8.1/test/bzlmod/BUILD000066400000000000000000000007311513642521100162100ustar00rootroot00000000000000load("@my_skylib//rules:diff_test.bzl", "diff_test") load("@stardoc//stardoc:stardoc.bzl", "stardoc") load(":def.bzl", "write_host_constraints") write_host_constraints( name = "host_constraints", ) stardoc( name = "docs", out = "docs.md", input = "def.bzl", deps = [ "@my_skylib//rules:write_file", "@platforms//host:constraints_lib", ], ) diff_test( name = "docs_test", file1 = "docs.md", file2 = "docs.md.golden", ) stardoc-0.8.1/test/bzlmod/MODULE.bazel000066400000000000000000000004201513642521100174250ustar00rootroot00000000000000module(name = "test_module") bazel_dep(name = "stardoc", version = "") local_path_override( module_name = "stardoc", path = "../..", ) bazel_dep(name = "bazel_skylib", version = "1.6.1", repo_name = "my_skylib") bazel_dep(name = "platforms", version = "0.0.10") stardoc-0.8.1/test/bzlmod/WORKSPACE000066400000000000000000000000001513642521100166740ustar00rootroot00000000000000stardoc-0.8.1/test/bzlmod/WORKSPACE.bzlmod000066400000000000000000000000001513642521100201620ustar00rootroot00000000000000stardoc-0.8.1/test/bzlmod/def.bzl000066400000000000000000000020621513642521100166740ustar00rootroot00000000000000# Copyright 2023 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """A simple macro used to test stardoc.""" load("@my_skylib//rules:write_file.bzl", "write_file") load("@platforms//host:constraints.bzl", "HOST_CONSTRAINTS") def write_host_constraints(name): """Emits the constraints of the host platform to a file. Args: name: The name of the target. The output file will be named `.txt`. """ write_file( name = name, content = HOST_CONSTRAINTS, out = name + ".txt", ) stardoc-0.8.1/test/bzlmod/docs.md.golden000066400000000000000000000011331513642521100201440ustar00rootroot00000000000000 A simple macro used to test stardoc. ## write_host_constraints
load("@test_module//:def.bzl", "write_host_constraints")

write_host_constraints(name)
Emits the constraints of the host platform to a file. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name of the target. The output file will be named `.txt`. | none | stardoc-0.8.1/test/diff_test_runner.sh000077500000000000000000000017531513642521100200430ustar00rootroot00000000000000#!/bin/bash # # Copyright 2018 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # A shell test that the contents of an input file match a golden file. # # Usage: diff_test_runner.sh ACTUAL_FILE GOLDEN_FILE set -u actual_file=$1 shift 1 golden_file=$1 shift 1 DIFF="$(diff ${actual_file} ${golden_file})" if [ "$DIFF" != "" ] then echo "FAIL: Actual did not match golden." echo "${DIFF}" exit 1 else echo "SUCCESS: Result matches golden file" fi stardoc-0.8.1/test/stardoc_test.bzl000066400000000000000000000116421513642521100173510ustar00rootroot00000000000000# Copyright 2019 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Convenience macro for stardoc e2e tests.""" load("@bazel_skylib//:bzl_library.bzl", "bzl_library") load("@rules_shell//shell:sh_binary.bzl", "sh_binary") load("@rules_shell//shell:sh_test.bzl", "sh_test") load("//stardoc:html_tables_stardoc.bzl", "html_tables_stardoc") load("//stardoc:stardoc.bzl", "stardoc") def stardoc_test( name, input_file, golden_file, deps = [], test = "default", **kwargs): """Convenience macro for stardoc e2e test suites. Each invocation creates multiple targets: 1. A `stardoc` target which will generate a new golden file given an input file, named "{name}_stardoc". 2. An `sh_test` target which verifies that the output of the `stardoc` target above matches a golden file. 3. A shell script which can be executed via `bazel run` to update the golden file from the `stardoc` target's output, named "{name}_regenerate" 4. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib". Args: name: A unique name to qualify the created targets. input_file: The label string of the Starlark input file for which documentation is generated in this test. golden_file: The label string of the golden file containing the documentation when stardoc is run on the input file. deps: A list of label strings of starlark file dependencies of the input_file. test: The type of test (default or html_tables). **kwargs: A dictionary of input template names mapped to template file path for which documentation is generated. """ bzl_library( name = "%s_lib" % name, srcs = [input_file], deps = deps, ) _create_test_targets( test_name = name, stardoc_name = "%s_stardoc" % name, regenerate_name = "%s_regenerate" % name, lib_name = "%s_lib" % name, input_file = input_file, golden_file = golden_file, test = test, **kwargs ) def _create_test_targets( test_name, stardoc_name, regenerate_name, lib_name, input_file, golden_file, test, **kwargs): actual_generated_doc = "%s.md" % stardoc_name tags = kwargs.get("tags", []) sh_test( name = test_name, srcs = ["diff_test_runner.sh"], args = [ "$(location %s)" % actual_generated_doc, "$(location %s)" % golden_file, ], data = [ actual_generated_doc, golden_file, ], tags = tags, ) regenerate_sh = "%s.sh" % regenerate_name native.genrule( name = "%s_sh" % regenerate_name, cmd = """cat > $(location %s) < Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186) See https://github.com/bazelbuild/skydoc/issues/186, https://github.com/bazelbuild/stardoc/issues/132, and https://github.com/bazelbuild/stardoc/issues/137. HTML formatting can be used in docstrings, just as in regular Markdown. Literal angle brackets can be obtained by escaping them with a backslash, where the backslash itself must be escaped for use in a Starlark docstring (`\\<` becomes \<), or by using HTML entities (`<` becomes <). Angle brackets are also preserved in inline code blocks (`#include `). ## my_anglebrac
load("@stardoc//test:testdata/angle_bracket_test/input.bzl", "my_anglebrac")

my_anglebrac(name, also_useless, useless)
Rule with \ **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | also_useless | Args with some formatted tags: `` and
<tag2>x</tag2>
| String | optional | `"1<<5"` | | useless | Args with some tags: \, \ | String | optional | `"Find \\"` | ## bracketuse
load("@stardoc//test:testdata/angle_bracket_test/input.bzl", "bracketuse")

bracketuse(foo, bar, baz)
Information with \ **FIELDS** | Name | Description | | :------------- | :------------- | | foo | A string representing \ | | bar | A string representing bar | | baz | A string representing baz | ## bracket_function
load("@stardoc//test:testdata/angle_bracket_test/input.bzl", "bracket_function")

bracket_function(param, md_string)
Dummy docstring with \. This rule runs checks on ``. Sometimes, we have such things on their own, but they may also appear in code blocks, like ```starlark foo = "" ``` **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | param | an arg with **formatted** docstring, `` by default. | `""` | | md_string | A markdown string. | ``"foo `1<<10` bar"`` | **RETURNS** some \ brackets **DEPRECATED** deprecated for \ as well as ``. ## bracket_aspect
load("@stardoc//test:testdata/angle_bracket_test/input.bzl", "bracket_aspect")

bracket_aspect(brackets)
Aspect. Sometimes, we want a code block like ```starlark foo = "" ``` which includes angle brackets. **ASPECT ATTRIBUTES** | Name | Type | | :------------- | :------------- | | deps| String | **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | brackets | Attribute with \ | String | optional | `""` | stardoc-0.8.1/test/testdata/angle_bracket_test/input.bzl000066400000000000000000000046301513642521100234420ustar00rootroot00000000000000"""Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186) See https://github.com/bazelbuild/skydoc/issues/186, https://github.com/bazelbuild/stardoc/issues/132, and https://github.com/bazelbuild/stardoc/issues/137. HTML formatting can be used in docstrings, just as in regular Markdown. Literal angle brackets can be obtained by escaping them with a backslash, where the backslash itself must be escaped for use in a Starlark docstring (`\\\\<` becomes \\<), or by using HTML entities (`<` becomes <). Angle brackets are also preserved in inline code blocks (`#include `). """ def bracket_function(param = "", md_string = "foo `1<<10` bar"): """Dummy docstring with \\. This rule runs checks on ``. Sometimes, we have such things on their own, but they may also appear in code blocks, like ```starlark foo = "" ``` Args: param: an arg with **formatted** docstring, `` by default. md_string: A markdown string. Returns: some \\ brackets Deprecated: deprecated for \\ as well as ``. """ return param or md_string # buildifier: disable=unsorted-dict-items bracketuse = provider( doc = "Information with \\", fields = { "foo": "A string representing \\", "bar": "A string representing bar", "baz": "A string representing baz", }, ) def _rule_impl(ctx): _ignore = [ctx] # @unused return [] my_anglebrac = rule( implementation = _rule_impl, doc = "Rule with \\", attrs = { "useless": attr.string( doc = "Args with some tags: \\, \\", default = "Find \\", ), "also_useless": attr.string( doc = """Args with some formatted tags: `` and ```xml x ``` """, default = "1<<5", ), }, ) def _bracket_aspect_impl(ctx): _ignore = [ctx] # @unused return [] bracket_aspect = aspect( implementation = _bracket_aspect_impl, doc = """Aspect. Sometimes, we want a code block like ```starlark foo = "" ``` which includes angle brackets. """, attr_aspects = ["deps"], attrs = { "brackets": attr.string( doc = "Attribute with \\", default = "", ), }, ) stardoc-0.8.1/test/testdata/aspect_test/000077500000000000000000000000001513642521100202655ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/aspect_test/golden.md000066400000000000000000000041321513642521100220570ustar00rootroot00000000000000 The input file for the aspect test ## my_aspect_impl
load("@stardoc//test:testdata/aspect_test/input.bzl", "my_aspect_impl")

my_aspect_impl(ctx)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | ctx |

-

| none | ## my_aspect
load("@stardoc//test:testdata/aspect_test/input.bzl", "my_aspect")

my_aspect(first, second)
This is my aspect. It does stuff. **ASPECT ATTRIBUTES** | Name | Type | | :------------- | :------------- | | deps| String | | attr_aspect| String | **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | first | - | Boolean | required | | | second | - | String | required | | ## namespace.namespaced_aspect
load("@stardoc//test:testdata/aspect_test/input.bzl", "namespace")

namespace.namespaced_aspect(third)
This is another aspect. **ASPECT ATTRIBUTES** **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | third | - | Integer | required | | ## other_aspect
load("@stardoc//test:testdata/aspect_test/input.bzl", "other_aspect")

other_aspect(third)
This is another aspect. **ASPECT ATTRIBUTES** **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | third | - | Integer | required | | stardoc-0.8.1/test/testdata/aspect_test/input.bzl000066400000000000000000000013271513642521100221400ustar00rootroot00000000000000"""The input file for the aspect test""" def my_aspect_impl(ctx): _ignore = [ctx] # @unused return [] my_aspect = aspect( implementation = my_aspect_impl, doc = """ This is my aspect. It does stuff. """, attr_aspects = ["deps", "attr_aspect"], attrs = { "first": attr.bool(mandatory = True), "second": attr.string(mandatory = True), }, ) # buildifier: disable=unsorted-dict-items other_aspect = aspect( implementation = my_aspect_impl, doc = "This is another aspect.", attr_aspects = ["*"], attrs = { "_hidden": attr.string(), "third": attr.int(mandatory = True), }, ) namespace = struct( namespaced_aspect = other_aspect, ) stardoc-0.8.1/test/testdata/attribute_defaults_test/000077500000000000000000000000001513642521100227005ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/attribute_defaults_test/golden.md000066400000000000000000000110061513642521100244700ustar00rootroot00000000000000 A golden test to verify attribute default values. ## my_rule
load("@stardoc//test:testdata/attribute_defaults_test/input.bzl", "my_rule")

my_rule(name, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | a | Some bool | Boolean | optional | `False` | | b | Some int | Integer | optional | `2` | | c | Some int_list | List of integers | optional | `[0, 1]` | | d | Some label | Label | optional | `"@stardoc//foo:bar"` | | e | Some label_keyed_string_dict | Dictionary: Label -> String | optional | `{"@stardoc//foo:bar": "hello", "@stardoc//bar:baz": "goodbye"}` | | f | Some label_list | List of labels | optional | `["@stardoc//foo:bar", "@stardoc//bar:baz"]` | | g | Some string | String | optional | `""` | | h | Some string_dict | Dictionary: String -> String | optional | `{"animal": "bunny", "color": "orange"}` | | i | Some string_list | List of strings | optional | `["cat", "dog"]` | | j | Some string_list_dict | Dictionary: String -> List of strings | optional | `{"animal": ["cat", "bunny"], "color": ["blue", "orange"]}` | | k | Some bool | Boolean | required | | | l | Some int | Integer | required | | | m | Some int_list | List of integers | required | | | n | Some label | Label | required | | | o | Some label_keyed_string_dict | Dictionary: Label -> String | required | | | p | Some label_list | List of labels | required | | | q | Some string | String | required | | | r | Some string_dict | Dictionary: String -> String | required | | | s | Some string_list | List of strings | required | | | t | Some string_list_dict | Dictionary: String -> List of strings | required | | | u | - | String | optional | `""` | | v | - | Label | optional | `None` | | w | - | Integer | optional | `0` | ## my_aspect
load("@stardoc//test:testdata/attribute_defaults_test/input.bzl", "my_aspect")

my_aspect(y, z)
This is my aspect. It does stuff. **ASPECT ATTRIBUTES** | Name | Type | | :------------- | :------------- | | deps| String | | attr_aspect| String | **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | y | some string | String | optional | `"why"` | | z | - | String | required | | stardoc-0.8.1/test/testdata/attribute_defaults_test/input.bzl000066400000000000000000000047621513642521100245610ustar00rootroot00000000000000"""A golden test to verify attribute default values.""" def _my_rule_impl(ctx): _ignore = [ctx] # @unused return [] def _my_aspect_impl(target, ctx): _ignore = [target, ctx] # @unused return [] # buildifier: disable=unsorted-dict-items my_aspect = aspect( implementation = _my_aspect_impl, doc = "This is my aspect. It does stuff.", attr_aspects = ["deps", "attr_aspect"], attrs = { "_x": attr.label(mandatory = True, default = "//foo:bar"), "y": attr.string(default = "why", doc = "some string"), "z": attr.string(mandatory = True), }, ) # buildifier: disable=unsorted-dict-items my_rule = rule( implementation = _my_rule_impl, doc = "This is my rule. It does stuff.", attrs = { "a": attr.bool(default = False, doc = "Some bool"), "b": attr.int(default = 2, doc = "Some int"), "c": attr.int_list(default = [0, 1], doc = "Some int_list"), "d": attr.label(default = "//foo:bar", doc = "Some label"), "e": attr.label_keyed_string_dict( default = {"//foo:bar": "hello", "//bar:baz": "goodbye"}, doc = "Some label_keyed_string_dict", ), "f": attr.label_list(default = ["//foo:bar", "//bar:baz"], doc = "Some label_list"), "g": attr.string(default = "", doc = "Some string"), "h": attr.string_dict( default = {"animal": "bunny", "color": "orange"}, doc = "Some string_dict", ), "i": attr.string_list(default = ["cat", "dog"], doc = "Some string_list"), "j": attr.string_list_dict( default = {"animal": ["cat", "bunny"], "color": ["blue", "orange"]}, doc = "Some string_list_dict", ), "k": attr.bool(mandatory = True, doc = "Some bool"), "l": attr.int(mandatory = True, doc = "Some int"), "m": attr.int_list(mandatory = True, doc = "Some int_list"), "n": attr.label(mandatory = True, doc = "Some label"), "o": attr.label_keyed_string_dict(mandatory = True, doc = "Some label_keyed_string_dict"), "p": attr.label_list(mandatory = True, doc = "Some label_list"), "q": attr.string(mandatory = True, doc = "Some string"), "r": attr.string_dict(mandatory = True, doc = "Some string_dict"), "s": attr.string_list(mandatory = True, doc = "Some string_list"), "t": attr.string_list_dict(mandatory = True, doc = "Some string_list_dict"), "u": attr.string(), "v": attr.label(), "w": attr.int(), }, ) stardoc-0.8.1/test/testdata/attribute_types_test/000077500000000000000000000000001513642521100222355ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/attribute_types_test/golden.md000066400000000000000000000045671513642521100240430ustar00rootroot00000000000000 ## my_rule
load("@stardoc//test:testdata/attribute_types_test/input.bzl", "my_rule")

my_rule(name, a, b, c, d, e, f, g, h, i, j, k, l)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | a | Some bool | Boolean | required | | | b | Some int | Integer | required | | | c | Some int_list | List of integers | required | | | d | Some label | Label | required | | | e | Some label_keyed_string_dict | Dictionary: Label -> String | required | | | f | Some label_list | List of labels | required | | | g | Some output | Label; nonconfigurable | optional | `None` | | h | Some output_list | List of labels; nonconfigurable | optional | `[]` | | i | Some string | String | required | | | j | Some string_dict | Dictionary: String -> String | required | | | k | Some string_list | List of strings | required | | | l | Some string_list_dict | Dictionary: String -> List of strings | optional | `{}` | stardoc-0.8.1/test/testdata/attribute_types_test/input.bzl000066400000000000000000000022021513642521100241010ustar00rootroot00000000000000# buildifier: disable=module-docstring # buildifier: disable=function-docstring def my_rule_impl(ctx): _ignore = [ctx] # @unused return [] my_rule = rule( implementation = my_rule_impl, doc = """ This is my rule. It does stuff. """, attrs = { "a": attr.bool(mandatory = True, doc = "Some bool"), "b": attr.int(mandatory = True, doc = "Some int"), "c": attr.int_list(mandatory = True, doc = "Some int_list"), "d": attr.label(mandatory = True, doc = "Some label"), "e": attr.label_keyed_string_dict(mandatory = True, doc = "Some label_keyed_string_dict"), "f": attr.label_list(mandatory = True, doc = "Some label_list"), "g": attr.output(mandatory = False, doc = "Some output"), "h": attr.output_list(mandatory = False, doc = "Some output_list"), "i": attr.string(mandatory = True, doc = "Some string"), "j": attr.string_dict(mandatory = True, doc = "Some string_dict"), "k": attr.string_list(mandatory = True, doc = "Some string_list"), "l": attr.string_list_dict(mandatory = False, doc = "Some string_list_dict"), }, ) stardoc-0.8.1/test/testdata/config_apis_test/000077500000000000000000000000001513642521100212675ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/config_apis_test/golden.md000066400000000000000000000032451513642521100230650ustar00rootroot00000000000000 ## int_setting
load("@stardoc//test:testdata/config_apis_test/input.bzl", "int_setting")

int_setting(name)
An integer flag. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | ## string_flag
load("@stardoc//test:testdata/config_apis_test/input.bzl", "string_flag")

string_flag(name)
A string flag. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | ## exercise_the_api
load("@stardoc//test:testdata/config_apis_test/input.bzl", "exercise_the_api")

exercise_the_api()
## transition_func
load("@stardoc//test:testdata/config_apis_test/input.bzl", "transition_func")

transition_func(settings)
A no-op transition function. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | settings |

-

| none | stardoc-0.8.1/test/testdata/config_apis_test/input.bzl000066400000000000000000000013551513642521100231430ustar00rootroot00000000000000# buildifier: disable=module-docstring # buildifier: disable=function-docstring def exercise_the_api(): _unused = configuration_field(fragment = "cpp", name = "custom_malloc") # @unused exercise_the_api() def transition_func(settings): """A no-op transition function.""" return settings my_transition = transition(implementation = transition_func, inputs = [], outputs = []) def _build_setting_impl(ctx): _ignore = [ctx] # @unused return [] string_flag = rule( doc = "A string flag.", implementation = _build_setting_impl, build_setting = config.string(flag = True), ) int_setting = rule( doc = "An integer flag.", implementation = _build_setting_impl, build_setting = config.int(flag = False), ) stardoc-0.8.1/test/testdata/fakedeps/000077500000000000000000000000001513642521100175315ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/fakedeps/dep.bzl000066400000000000000000000001621513642521100210110ustar00rootroot00000000000000"""A fake bzl to test cross-repository dependencies.""" def give_me_five(): """Returns five.""" return 5 stardoc-0.8.1/test/testdata/filter_rules_test/000077500000000000000000000000001513642521100215055ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/filter_rules_test/dep.bzl000066400000000000000000000006701513642521100227710ustar00rootroot00000000000000# buildifier: disable=module-docstring def my_rule_impl(ctx): _ignore = [ctx] # @unused return [] my_rule = rule( implementation = my_rule_impl, doc = "This is the dep rule. It does stuff.", attrs = { "first": attr.label( mandatory = True, doc = "dep's my_rule doc string", allow_single_file = True, ), "second": attr.string_dict(mandatory = True), }, ) stardoc-0.8.1/test/testdata/filter_rules_test/golden.md000066400000000000000000000036051513642521100233030ustar00rootroot00000000000000 ## allowlisted_dep_rule
load("@stardoc//test:testdata/filter_rules_test/input.bzl", "allowlisted_dep_rule")

allowlisted_dep_rule(name, first, second)
This is the dep rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | dep's my_rule doc string | Label | required | | | second | - | Dictionary: String -> String | required | | ## my_rule
load("@stardoc//test:testdata/filter_rules_test/input.bzl", "my_rule")

my_rule(name, first, second)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first my_rule doc string | Label | required | | | second | - | Dictionary: String -> String | required | | stardoc-0.8.1/test/testdata/filter_rules_test/input.bzl000066400000000000000000000015041513642521100233550ustar00rootroot00000000000000# buildifier: disable=module-docstring load( ":testdata/filter_rules_test/dep.bzl", "my_rule_impl", dep_rule = "my_rule", ) my_rule = rule( implementation = my_rule_impl, doc = "This is my rule. It does stuff.", attrs = { "first": attr.label( mandatory = True, doc = "first my_rule doc string", allow_single_file = True, ), "second": attr.string_dict(mandatory = True), }, ) other_rule = rule( implementation = my_rule_impl, doc = "This is another rule.", attrs = { "test": attr.string_dict(mandatory = True), }, ) allowlisted_dep_rule = dep_rule yet_another_rule = rule( implementation = my_rule_impl, doc = "This is yet another rule", attrs = { "test": attr.string_dict(mandatory = True), }, ) stardoc-0.8.1/test/testdata/footer_test/000077500000000000000000000000001513642521100203045ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/footer_test/footer_template.vm000066400000000000000000000000441513642521100240370ustar00rootroot00000000000000This is the footer of the document. stardoc-0.8.1/test/testdata/footer_test/golden.md000066400000000000000000000001431513642521100220740ustar00rootroot00000000000000 This is the footer of the document. stardoc-0.8.1/test/testdata/footer_test/input.bzl000066400000000000000000000000431513642521100221510ustar00rootroot00000000000000# only need to generate the footer stardoc-0.8.1/test/testdata/function_basic_test/000077500000000000000000000000001513642521100217745ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/function_basic_test/golden.md000066400000000000000000000073601513642521100235740ustar00rootroot00000000000000 A test that verifies basic user function documentation. ## check_sources
load("@stardoc//test:testdata/function_basic_test/input.bzl", "check_sources")

check_sources(name, required_param, bool_param, srcs, string_param, int_param, dict_param,
              struct_param)
Runs some checks on the given source files. This rule runs checks on a given set of source files. Use `bazel build` to run the check. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | A unique name for this rule. | none | | required_param | Use your imagination. | none | | bool_param |

-

| `True` | | srcs | Source files to run the checks against. | `[]` | | string_param |

-

| `""` | | int_param | Your favorite number. | `2` | | dict_param |

-

| `{}` | | struct_param |

-

| `struct(foo = "bar")` | ## deprecated_do_not_use
load("@stardoc//test:testdata/function_basic_test/input.bzl", "deprecated_do_not_use")

deprecated_do_not_use()
This function is deprecated. **DEPRECATED** Use literally anything but this function. ## param_doc_multiline
load("@stardoc//test:testdata/function_basic_test/input.bzl", "param_doc_multiline")

param_doc_multiline(complex)
Has a complex parameter. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | complex | A parameter with some non-obvious behavior.

For example, it does things that require **multiple paragraphs** to explain.

Note: we should preserve the nested indent in the following code:

{
    "key": "value"
}
| none | ## returns_a_thing
load("@stardoc//test:testdata/function_basic_test/input.bzl", "returns_a_thing")

returns_a_thing(name)
Returns a suffixed name. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | A unique name for this rule. | none | **RETURNS** A suffixed version of the name. ## undocumented_function
load("@stardoc//test:testdata/function_basic_test/input.bzl", "undocumented_function")

undocumented_function(a, b, c)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | a |

-

| none | | b |

-

| none | | c |

-

| none | stardoc-0.8.1/test/testdata/function_basic_test/input.bzl000066400000000000000000000036441513642521100236530ustar00rootroot00000000000000"""A test that verifies basic user function documentation.""" def check_sources( name, required_param, bool_param = True, srcs = [], string_param = "", int_param = 2, dict_param = {}, struct_param = struct(foo = "bar")): # buildifier: disable=function-docstring-args """Runs some checks on the given source files. This rule runs checks on a given set of source files. Use `bazel build` to run the check. Args: name: A unique name for this rule. required_param: Use your imagination. srcs: Source files to run the checks against. doesnt_exist: A param that doesn't exist (lets hope we still get *some* documentation) int_param: Your favorite number. """ _ignore = [ name, required_param, bool_param, srcs, string_param, int_param, dict_param, struct_param, ] # @unused x = ("Hah. All that documentation but nothing really to see here") # @unused def returns_a_thing(name): """Returns a suffixed name. Args: name: A unique name for this rule. Returns: A suffixed version of the name. """ _ignore = name # @unused pass def deprecated_do_not_use(): """This function is deprecated. Deprecated: Use literally anything but this function. """ pass # buildifier: disable=unused-variable def undocumented_function(a, b, c): pass # buildifier: disable=unused-variable def param_doc_multiline(complex): """Has a complex parameter. Args: complex: A parameter with some non-obvious behavior. For example, it does things that require **multiple paragraphs** to explain. Note: we should preserve the nested indent in the following code: ```json { "key": "value" } ``` """ pass stardoc-0.8.1/test/testdata/function_wrap_multiple_lines_test/000077500000000000000000000000001513642521100247715ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/function_wrap_multiple_lines_test/golden.md000066400000000000000000000142561513642521100265730ustar00rootroot00000000000000 Rules for ANTLR 3. ## antlr
load("@stardoc//test:testdata/function_wrap_multiple_lines_test/input.bzl", "antlr")

antlr(name, deps, srcs, Xconversiontimeout, Xdbgconversion, Xdbgst, Xdfa, Xdfaverbose, Xgrtree, Xm,
      Xmaxdfaedges, Xmaxinlinedfastates, Xminswitchalts, Xmultithreaded, Xnfastates, Xnocollapse,
      Xnomergestopstates, Xnoprune, XsaveLexer, Xwatchconversion, debug, depend, dfa, dump, imports,
      language, message_format, nfa, package, profile, report, trace)
Runs [ANTLR 3](https://www.antlr3.org//) on a set of grammars. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | deps | The dependencies to use. Defaults to the most recent ANTLR 3 release, but if you need to use a different version, you can specify the dependencies here. | List of labels | optional | `["@@[unknown repo 'antlr3_runtimes' requested from @@]//:tool"]` | | srcs | The grammar files to process. | List of labels | required | | | Xconversiontimeout | Set NFA conversion timeout for each decision. | Integer | optional | `0` | | Xdbgconversion | Dump lots of info during NFA conversion. | Boolean | optional | `False` | | Xdbgst | Put tags at start/stop of all templates in output. | Boolean | optional | `False` | | Xdfa | Print DFA as text. | Boolean | optional | `False` | | Xdfaverbose | Generate DFA states in DOT with NFA configs. | Boolean | optional | `False` | | Xgrtree | Print the grammar AST. | Boolean | optional | `False` | | Xm | Max number of rule invocations during conversion. | Integer | optional | `0` | | Xmaxdfaedges | Max "comfortable" number of edges for single DFA state. | Integer | optional | `0` | | Xmaxinlinedfastates | Max DFA states before table used rather than inlining. | Integer | optional | `0` | | Xminswitchalts | Don't generate switch() statements for dfas smaller than given number. | Integer | optional | `0` | | Xmultithreaded | Run the analysis in 2 threads. | Boolean | optional | `False` | | Xnfastates | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` | | Xnocollapse | Collapse incident edges into DFA states. | Boolean | optional | `False` | | Xnomergestopstates | Max DFA states before table used rather than inlining. | Boolean | optional | `False` | | Xnoprune | Do not test EBNF block exit branches. | Boolean | optional | `False` | | XsaveLexer | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` | | Xwatchconversion | Don't delete temporary lexers generated from combined grammars. | Boolean | optional | `False` | | debug | Generate a parser that emits debugging events. | Boolean | optional | `False` | | depend | Generate file dependencies; don't actually run antlr. | Boolean | optional | `False` | | dfa | Generate a DFA for each decision point. | Boolean | optional | `False` | | dump | Print out the grammar without actions. | Boolean | optional | `False` | | imports | The grammar and .tokens files to import. Must be all in the same directory. | List of labels | optional | `[]` | | language | The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive). | String | optional | `""` | | message_format | Specify output style for messages. | String | optional | `""` | | nfa | Generate an NFA for each rule. | Boolean | optional | `False` | | package | The package/namespace for the generated code. | String | optional | `""` | | profile | Generate a parser that computes profiling information. | Boolean | optional | `False` | | report | Print out a report about the grammar(s) processed. | Boolean | optional | `False` | | trace | Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods. | Boolean | optional | `False` | stardoc-0.8.1/test/testdata/function_wrap_multiple_lines_test/input.bzl000066400000000000000000000073721513642521100266520ustar00rootroot00000000000000"""Rules for ANTLR 3.""" # buildifier: disable=unused-variable def _generate(ctx): return None antlr = rule( implementation = _generate, doc = "Runs [ANTLR 3](https://www.antlr3.org//) on a set of grammars.", attrs = { "debug": attr.bool(default = False, doc = "Generate a parser that emits debugging events."), "depend": attr.bool(default = False, doc = "Generate file dependencies; don't actually run antlr."), "deps": attr.label_list( default = [Label("@antlr3_runtimes//:tool")], doc = """ The dependencies to use. Defaults to the most recent ANTLR 3 release, but if you need to use a different version, you can specify the dependencies here. """, ), "dfa": attr.bool(default = False, doc = "Generate a DFA for each decision point."), "dump": attr.bool(default = False, doc = "Print out the grammar without actions."), "imports": attr.label_list(allow_files = True, doc = "The grammar and .tokens files to import. Must be all in the same directory."), "language": attr.string(doc = "The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive)."), "message_format": attr.string(doc = "Specify output style for messages."), "nfa": attr.bool(default = False, doc = "Generate an NFA for each rule."), "package": attr.string(doc = "The package/namespace for the generated code."), "profile": attr.bool(default = False, doc = "Generate a parser that computes profiling information."), "report": attr.bool(default = False, doc = "Print out a report about the grammar(s) processed."), "srcs": attr.label_list(allow_files = True, mandatory = True, doc = "The grammar files to process."), "trace": attr.bool(default = False, doc = "Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods."), "Xconversiontimeout": attr.int(doc = "Set NFA conversion timeout for each decision."), "Xdbgconversion": attr.bool(default = False, doc = "Dump lots of info during NFA conversion."), "Xdbgst": attr.bool(default = False, doc = "Put tags at start/stop of all templates in output."), "Xdfa": attr.bool(default = False, doc = "Print DFA as text."), "Xdfaverbose": attr.bool(default = False, doc = "Generate DFA states in DOT with NFA configs."), "Xgrtree": attr.bool(default = False, doc = "Print the grammar AST."), "Xm": attr.int(doc = "Max number of rule invocations during conversion."), "Xmaxdfaedges": attr.int(doc = "Max "comfortable" number of edges for single DFA state."), "Xmaxinlinedfastates": attr.int(doc = "Max DFA states before table used rather than inlining."), "Xminswitchalts": attr.int(doc = "Don't generate switch() statements for dfas smaller than given number."), "Xmultithreaded": attr.bool(default = False, doc = "Run the analysis in 2 threads."), "Xnfastates": attr.bool(default = False, doc = "For nondeterminisms, list NFA states for each path."), "Xnocollapse": attr.bool(default = False, doc = "Collapse incident edges into DFA states."), "Xnoprune": attr.bool(default = False, doc = "Do not test EBNF block exit branches."), "Xnomergestopstates": attr.bool(default = False, doc = "Max DFA states before table used rather than inlining."), "XsaveLexer": attr.bool(default = False, doc = "For nondeterminisms, list NFA states for each path."), "Xwatchconversion": attr.bool(default = False, doc = "Don't delete temporary lexers generated from combined grammars."), "_tool": attr.label( executable = True, cfg = "exec", ), }, ) stardoc-0.8.1/test/testdata/html_tables_template_test/000077500000000000000000000000001513642521100231775ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/html_tables_template_test/golden.md000066400000000000000000000071411513642521100247740ustar00rootroot00000000000000 Input file for markdown template test ## example_rule
load("@stardoc//test:testdata/html_tables_template_test/input.bzl", "example_rule")

example_rule(name, first, second)
Small example of rule using a markdown template. ### Attributes
name Name; required

A unique name for this target.

first String; optional

This is the first attribute

second String; optional
## ExampleProviderInfo
load("@stardoc//test:testdata/html_tables_template_test/input.bzl", "ExampleProviderInfo")

ExampleProviderInfo(foo, bar, baz)
Small example of provider using a markdown template. ### Fields
foo

A string representing foo

bar

A string representing bar

baz

A string representing baz

## example_function
load("@stardoc//test:testdata/html_tables_template_test/input.bzl", "example_function")

example_function(foo, bar)
Small example of function using a markdown template. ### Parameters
foo required.

This parameter does foo related things.

bar optional. default is "bar"

This parameter does bar related things.

## example_aspect
load("@stardoc//test:testdata/html_tables_template_test/input.bzl", "example_aspect")

example_aspect(first, second)
Small example of aspect using a markdown template. ### Aspect Attributes
deps String; required.
attr_aspect String; required.
### Attributes
first Integer; required
second String; optional

This is the second attribute.

stardoc-0.8.1/test/testdata/html_tables_template_test/input.bzl000066400000000000000000000024341513642521100250520ustar00rootroot00000000000000"""Input file for markdown template test""" def example_function(foo, bar = "bar"): """Small example of function using a markdown template. Args: foo: This parameter does foo related things. bar: This parameter does bar related things. """ _ignore = [foo, bar] # @unused pass # buildifier: disable=unsorted-dict-items ExampleProviderInfo = provider( doc = "Small example of provider using a markdown template.", fields = { "foo": "A string representing foo", "bar": "A string representing bar", "baz": "A string representing baz", }, ) def _rule_impl(ctx): _ignore = [ctx] # @unused return [] example_rule = rule( implementation = _rule_impl, doc = "Small example of rule using a markdown template.", attrs = { "first": attr.string(doc = "This is the first attribute"), "second": attr.string(default = "2"), }, ) def _aspect_impl(ctx): _ignore = [ctx] # @unused return [] example_aspect = aspect( implementation = _aspect_impl, doc = "Small example of aspect using a markdown template.", attr_aspects = ["deps", "attr_aspect"], attrs = { "first": attr.int(mandatory = True), "second": attr.string(doc = "This is the second attribute."), }, ) stardoc-0.8.1/test/testdata/input_template_test/000077500000000000000000000000001513642521100220405ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/input_template_test/aspect.vm000066400000000000000000000012461513642521100236660ustar00rootroot00000000000000 #[[##]]# ${aspectName}
${util.aspectSummary($aspectName, $aspectInfo)}
$aspectInfo.getDocString() #[[###]]# Aspect Attributes #if (!$aspectInfo.getAspectAttributeList().isEmpty()) #foreach ($aspectAttribute in $aspectInfo.getAspectAttributeList()) $aspectAttribute String; required. #end #end #[[###]]# Attributes #foreach ($attribute in $aspectInfo.getAttributeList()) ${attribute.name} ${util.attributeTypeString($attribute)}; ${util.mandatoryString($attribute)} #if (!$attribute.docString.isEmpty())

${attribute.docString.trim()}

#end #end stardoc-0.8.1/test/testdata/input_template_test/func.vm000066400000000000000000000011501513642521100233340ustar00rootroot00000000000000 #[[##]]# ${funcInfo.functionName}
${util.funcSummary($funcInfo)}
${funcInfo.docString} input_template_test BOLD PARAMETERS #if (!$funcInfo.getParameterList().isEmpty()) #[[###]]# Parameters #foreach ($param in $funcInfo.getParameterList()) ${param.name} ${util.mandatoryString($param)}.#if(!$param.getDefaultValue().isEmpty()) default is $param.getDefaultValue() #end #if (!$param.docString.isEmpty())

${param.docString.trim()}

#end #end #end stardoc-0.8.1/test/testdata/input_template_test/golden.md000066400000000000000000000041731513642521100236370ustar00rootroot00000000000000 Module Docstring: "Input file for input template test" ## my_example
my_example(name, useless)
Small example of rule using chosen template. input_template_test BOLD ATTRIBUTES ### Attributes name Name; required

A unique name for this target.

useless String; optional

This argument will be ignored.

## example
example(foo, bar, baz)
Stores information about an example in chosen template. input_template_test BOLD FIELDS ### Fields foo

A string representing foo

bar

A string representing bar

baz

A string representing baz

## my_aspect_impl
my_aspect_impl(ctx)
input_template_test BOLD PARAMETERS ### Parameters ctx required. ## template_function
template_function(foo)
Runs some checks on the given function parameter. This rule runs checks on a given function parameter in chosen template. Use `bazel build` to run the check. input_template_test BOLD PARAMETERS ### Parameters foo required.

A unique name for this function.

## my_aspect
my_aspect(first)
This is my aspect. It does stuff. ### Aspect Attributes deps String; required. attr_aspect String; required. ### Attributes first String; required stardoc-0.8.1/test/testdata/input_template_test/header.vm000066400000000000000000000001351513642521100236330ustar00rootroot00000000000000 Module Docstring: "${moduleDocstring}" stardoc-0.8.1/test/testdata/input_template_test/input.bzl000066400000000000000000000023461513642521100237150ustar00rootroot00000000000000"""Input file for input template test""" def template_function(foo): """Runs some checks on the given function parameter. This rule runs checks on a given function parameter in chosen template. Use `bazel build` to run the check. Args: foo: A unique name for this function. """ _ignore = [foo] # @unused pass # buildifier: disable=unsorted-dict-items example = provider( doc = "Stores information about an example in chosen template.", fields = { "foo": "A string representing foo", "bar": "A string representing bar", "baz": "A string representing baz", }, ) def _rule_impl(ctx): _ignore = [ctx] # @unused return [] my_example = rule( implementation = _rule_impl, doc = "Small example of rule using chosen template.", attrs = { "useless": attr.string( doc = "This argument will be ignored.", default = "word", ), }, ) def my_aspect_impl(ctx): _ignore = [ctx] # @unused return [] my_aspect = aspect( implementation = my_aspect_impl, doc = "This is my aspect. It does stuff.", attr_aspects = ["deps", "attr_aspect"], attrs = { "first": attr.string(mandatory = True), }, ) stardoc-0.8.1/test/testdata/input_template_test/provider.vm000066400000000000000000000006061513642521100242400ustar00rootroot00000000000000 #[[##]]# ${providerName}
${util.providerSummary($providerName, $providerInfo)}
${providerInfo.docString} input_template_test BOLD FIELDS #if (!$providerInfo.fieldInfoList.isEmpty()) #[[###]]# Fields #foreach ($field in $providerInfo.fieldInfoList) ${field.name}

${field.docString}

#end #end stardoc-0.8.1/test/testdata/input_template_test/rule.vm000066400000000000000000000010401513642521100233460ustar00rootroot00000000000000 #[[##]]# ${ruleName}
${util.ruleSummary($ruleName, $ruleInfo)}
${ruleInfo.docString} input_template_test BOLD ATTRIBUTES #[[###]]# Attributes #if (!$ruleInfo.getAttributeList().isEmpty()) #foreach ($attribute in $ruleInfo.getAttributeList()) ${attribute.name} ${util.attributeTypeString($attribute)}; ${util.mandatoryString($attribute)} #if (!$attribute.docString.isEmpty())

${attribute.docString.trim()}

#end #end #end stardoc-0.8.1/test/testdata/local_repository_test/000077500000000000000000000000001513642521100223775ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/local_repository_test/BUILD000066400000000000000000000007511513642521100231640ustar00rootroot00000000000000load("@bazel_skylib//:bzl_library.bzl", "bzl_library") load("@stardoc//stardoc:stardoc.bzl", "stardoc") package( default_visibility = ["//visibility:public"], ) licenses(["notice"]) # Apache 2.0 exports_files([ "input.bzl", "golden.md", ]) stardoc( name = "input_doc", out = "output.md", input = ":input.bzl", deps = [":lib"], ) bzl_library( name = "lib", srcs = [ "input.bzl", "@stardoc//test:testdata/fakedeps/dep.bzl", ], ) stardoc-0.8.1/test/testdata/local_repository_test/WORKSPACE000066400000000000000000000000511513642521100236540ustar00rootroot00000000000000workspace(name = "local_workspace_test") stardoc-0.8.1/test/testdata/local_repository_test/golden.md000077500000000000000000000010771513642521100242010ustar00rootroot00000000000000 A test that verifies documenting functions in an input file under a local_repository. ## min
load("@local_repository_test//:input.bzl", "min")

min(integers)
Returns the minimum of given elements. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | integers | A list of integers. Must not be empty. | none | **RETURNS** The minimum integer in the given list. stardoc-0.8.1/test/testdata/local_repository_test/input.bzl000066400000000000000000000006431513642521100242520ustar00rootroot00000000000000"""A test that verifies documenting functions in an input file under a local_repository.""" load("@stardoc//test:testdata/fakedeps/dep.bzl", "give_me_five") def min(integers): """Returns the minimum of given elements. Args: integers: A list of integers. Must not be empty. Returns: The minimum integer in the given list. """ _ignore = [integers] # @unused return give_me_five() stardoc-0.8.1/test/testdata/macro_kwargs_test/000077500000000000000000000000001513642521100214655ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/macro_kwargs_test/golden.md000066400000000000000000000452711513642521100232700ustar00rootroot00000000000000 Tests for functions which use *args or **kwargs ## macro_with_args
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args")

macro_with_args(name, *args)
My args macro is OK. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name of the test rule. | none | | args | Other arguments to include | none | **RETURNS** An empty list. ## macro_with_args_and_kwonly
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_and_kwonly")

macro_with_args_and_kwonly(*args, name)
*args and a keyword-only param **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | args | Positional arguments | none | ## macro_with_args_and_kwonlys
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_and_kwonlys")

macro_with_args_and_kwonlys(*args, name, number)
*args and several keyword-only params **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | args | Positional arguments | none | ## macro_with_args_kwonly_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_kwonly_and_kwargs")

macro_with_args_kwonly_and_kwargs(*args, name, **kwargs)
*args, a keyword-only param, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | args | Positional arguments | none | | kwargs | Other named arguments | none | ## macro_with_args_kwonlys_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_kwonlys_and_kwargs")

macro_with_args_kwonlys_and_kwargs(*args, name, number, **kwargs)
*args, several keyword-only params, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | args | Positional arguments | none | | kwargs | Other named arguments | none | ## macro_with_both
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_both")

macro_with_both(name, number, *args, **kwargs)
Oh wow this macro has both. Not much else to say. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name of the test rule. | none | | number | Some number used for important things | `3` | | args | Other arguments to include | none | | kwargs | Other attributes to include | none | **RETURNS** An empty list. ## macro_with_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwargs")

macro_with_kwargs(name, config, deps, **kwargs)
My kwargs macro is the best. This is a long multi-line doc string. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer elementum, diam vitae tincidunt pulvinar, nunc tortor volutpat dui, vitae facilisis odio ligula a tortor. Donec ullamcorper odio eget ipsum tincidunt, vel mollis eros pellentesque. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name of the test rule. | none | | config | Config to use for my macro | none | | deps | List of my macro's dependencies | `[]` | | kwargs | Other attributes to include | none | **RETURNS** An empty list. ## macro_with_kwonly
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonly")

macro_with_kwonly(*, name)
One keyword-only param **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | ## macro_with_kwonly_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonly_and_kwargs")

macro_with_kwonly_and_kwargs(*, name, **kwargs)
One keyword-only param and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | kwargs | Other named arguments | none | ## macro_with_kwonlys
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonlys")

macro_with_kwonlys(*, name, number)
Several keyword-only params **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | ## macro_with_kwonlys_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonlys_and_kwargs")

macro_with_kwonlys_and_kwargs(*, name, number, **kwargs)
Several keyword-only params and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | kwargs | Other named arguments | none | ## macro_with_only_args
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_args")

macro_with_only_args(*args)
Macro only taking *args **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | args | Positional arguments | none | ## macro_with_only_args_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_args_and_kwargs")

macro_with_only_args_and_kwargs(*args, **kwargs)
Macro only taking *args and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | args | Positional arguments | none | | kwargs | Named arguments | none | ## macro_with_only_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_kwargs")

macro_with_only_kwargs(**kwargs)
Macro only taking **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | kwargs | Named arguments | none | ## macro_with_ordinary_param_and_kwonlys
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_and_kwonlys")

macro_with_ordinary_param_and_kwonlys(name, *, number, config)
One ordinary param and several keyword-only params **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | none | | config | Configuration | none | ## macro_with_ordinary_param_args_and_kwonlys
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_args_and_kwonlys")

macro_with_ordinary_param_args_and_kwonlys(name, *args, number, config)
One ordinary param, *args, and several keyword-only params **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | none | | config | Configuration | none | | args | Positional arguments | none | ## macro_with_ordinary_param_args_kwonlys_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_args_kwonlys_and_kwargs")

macro_with_ordinary_param_args_kwonlys_and_kwargs(name, *args, number, config, **kwargs)
One ordinary param, *args, several keyword-only params, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | none | | config | Configuration | none | | args | Other positional arguments | none | | kwargs | Other named arguments | none | ## macro_with_ordinary_param_kwonlys_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_kwonlys_and_kwargs")

macro_with_ordinary_param_kwonlys_and_kwargs(name, *, number, config, **kwargs)
One ordinary param, several keyword-only params, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | none | | config | Configuration | none | | kwargs | Other named arguments | none | ## macro_with_ordinary_params_and_kwonly
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_and_kwonly")

macro_with_ordinary_params_and_kwonly(name, number, *, config)
Several ordinary params and a keyword-only param **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | config | Configuration | none | ## macro_with_ordinary_params_args_and_kwonly
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_args_and_kwonly")

macro_with_ordinary_params_args_and_kwonly(name, number, *args, config)
Several ordinary params, *args, and a keyword-only param **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | config | Configuration | none | | args | Positional arguments | none | ## macro_with_ordinary_params_args_kwonly_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_args_kwonly_and_kwargs")

macro_with_ordinary_params_args_kwonly_and_kwargs(name, number, *args, config, **kwargs)
Several ordinary params, *args, one keyword-only param, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | config | Configuration | none | | args | Other positional arguments | none | | kwargs | Other named arguments | none | ## macro_with_ordinary_params_kwonly_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_kwonly_and_kwargs")

macro_with_ordinary_params_kwonly_and_kwargs(name, number, *, config, **kwargs)
Several ordinary params, a keyword-only param, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | config | Configuration | none | | kwargs | Other named arguments | none | stardoc-0.8.1/test/testdata/macro_kwargs_test/input.bzl000066400000000000000000000145071513642521100233440ustar00rootroot00000000000000"""Tests for functions which use *args or **kwargs""" def macro_with_kwargs(name, config, deps = [], **kwargs): """My kwargs macro is the best. This is a long multi-line doc string. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer elementum, diam vitae tincidunt pulvinar, nunc tortor volutpat dui, vitae facilisis odio ligula a tortor. Donec ullamcorper odio eget ipsum tincidunt, vel mollis eros pellentesque. Args: name: The name of the test rule. config: Config to use for my macro deps: List of my macro's dependencies **kwargs: Other attributes to include Returns: An empty list. """ _ignore = [name, config, deps, kwargs] # @unused return [] def macro_with_args(name, *args): """My args macro is OK. Args: name: The name of the test rule. *args: Other arguments to include Returns: An empty list. """ _ignore = [name, args] # @unused return [] def macro_with_both(name, number = 3, *args, **kwargs): """Oh wow this macro has both. Not much else to say. Args: name: The name of the test rule. number: Some number used for important things *args: Other arguments to include **kwargs: Other attributes to include Returns: An empty list. """ _ignore = [name, number, args, kwargs] # @unused return [] # buildifier: disable=unused-variable def macro_with_only_args(*args): """Macro only taking *args Args: *args: Positional arguments """ pass # buildifier: disable=unused-variable def macro_with_only_kwargs(**kwargs): """Macro only taking **kwargs Args: **kwargs: Named arguments """ pass # buildifier: disable=unused-variable def macro_with_only_args_and_kwargs(*args, **kwargs): """Macro only taking *args and **kwargs Args: *args: Positional arguments **kwargs: Named arguments """ pass # buildifier: disable=unused-variable def macro_with_kwonly(*, name): """One keyword-only param Args: name: The name """ pass # buildifier: disable=unused-variable def macro_with_kwonlys(*, name, number = 3): """Several keyword-only params Args: name: The name number: The number """ pass # buildifier: disable=unused-variable def macro_with_kwonly_and_kwargs(*, name, **kwargs): """One keyword-only param and **kwargs Args: name: The name **kwargs: Other named arguments """ pass # buildifier: disable=unused-variable def macro_with_kwonlys_and_kwargs(*, name, number = 3, **kwargs): """Several keyword-only params and **kwargs Args: name: The name number: The number **kwargs: Other named arguments """ pass # buildifier: disable=unused-variable def macro_with_ordinary_params_and_kwonly(name, number = 3, *, config): """Several ordinary params and a keyword-only param Args: name: The name number: The number config: Configuration """ pass # buildifier: disable=unused-variable def macro_with_ordinary_param_and_kwonlys(name, *, number, config): """One ordinary param and several keyword-only params Args: name: The name number: The number config: Configuration """ pass # buildifier: disable=unused-variable def macro_with_ordinary_param_kwonlys_and_kwargs(name, *, number, config, **kwargs): """One ordinary param, several keyword-only params, and **kwargs Args: name: The name number: The number config: Configuration **kwargs: Other named arguments """ pass # buildifier: disable=unused-variable def macro_with_ordinary_params_kwonly_and_kwargs(name, number = 3, *, config, **kwargs): """Several ordinary params, a keyword-only param, and **kwargs Args: name: The name number: The number config: Configuration **kwargs: Other named arguments """ pass # buildifier: disable=unused-variable def macro_with_args_and_kwonly(*args, name): """*args and a keyword-only param Args: *args: Positional arguments name: The name """ pass # buildifier: disable=unused-variable def macro_with_args_and_kwonlys(*args, name, number = 3): """*args and several keyword-only params Args: *args: Positional arguments name: The name number: The number """ pass # buildifier: disable=unused-variable def macro_with_args_kwonly_and_kwargs(*args, name, **kwargs): """*args, a keyword-only param, and **kwargs Args: *args: Positional arguments name: The name **kwargs: Other named arguments """ pass # buildifier: disable=unused-variable def macro_with_args_kwonlys_and_kwargs(*args, name, number = 3, **kwargs): """*args, several keyword-only params, and **kwargs Args: *args: Positional arguments name: The name number: The number **kwargs: Other named arguments """ pass # buildifier: disable=unused-variable def macro_with_ordinary_params_args_and_kwonly(name, number = 3, *args, config): """Several ordinary params, *args, and a keyword-only param Args: name: The name number: The number *args: Positional arguments config: Configuration """ pass # buildifier: disable=unused-variable def macro_with_ordinary_param_args_and_kwonlys(name, *args, number, config): """One ordinary param, *args, and several keyword-only params Args: name: The name *args: Positional arguments number: The number config: Configuration """ pass # buildifier: disable=unused-variable def macro_with_ordinary_param_args_kwonlys_and_kwargs(name, *args, number, config, **kwargs): """One ordinary param, *args, several keyword-only params, and **kwargs Args: name: The name *args: Other positional arguments number: The number config: Configuration **kwargs: Other named arguments """ pass # buildifier: disable=unused-variable def macro_with_ordinary_params_args_kwonly_and_kwargs(name, number = 3, *args, config, **kwargs): """Several ordinary params, *args, one keyword-only param, and **kwargs Args: name: The name number: The number *args: Other positional arguments config: Configuration **kwargs: Other named arguments """ pass stardoc-0.8.1/test/testdata/macro_kwargs_test/legacy_golden.md000066400000000000000000000451751513642521100246170ustar00rootroot00000000000000 Tests for functions which use *args or **kwargs ## macro_with_args
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args")

macro_with_args(name, args)
My args macro is OK. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name of the test rule. | none | | args | Other arguments to include | none | **RETURNS** An empty list. ## macro_with_args_and_kwonly
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_and_kwonly")

macro_with_args_and_kwonly(name, args)
*args and a keyword-only param **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | args | Positional arguments | none | ## macro_with_args_and_kwonlys
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_and_kwonlys")

macro_with_args_and_kwonlys(name, number, args)
*args and several keyword-only params **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | args | Positional arguments | none | ## macro_with_args_kwonly_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_kwonly_and_kwargs")

macro_with_args_kwonly_and_kwargs(name, args, kwargs)
*args, a keyword-only param, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | args | Positional arguments | none | | kwargs | Other named arguments | none | ## macro_with_args_kwonlys_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_kwonlys_and_kwargs")

macro_with_args_kwonlys_and_kwargs(name, number, args, kwargs)
*args, several keyword-only params, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | args | Positional arguments | none | | kwargs | Other named arguments | none | ## macro_with_both
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_both")

macro_with_both(name, number, args, kwargs)
Oh wow this macro has both. Not much else to say. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name of the test rule. | none | | number | Some number used for important things | `3` | | args | Other arguments to include | none | | kwargs | Other attributes to include | none | **RETURNS** An empty list. ## macro_with_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwargs")

macro_with_kwargs(name, config, deps, kwargs)
My kwargs macro is the best. This is a long multi-line doc string. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer elementum, diam vitae tincidunt pulvinar, nunc tortor volutpat dui, vitae facilisis odio ligula a tortor. Donec ullamcorper odio eget ipsum tincidunt, vel mollis eros pellentesque. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name of the test rule. | none | | config | Config to use for my macro | none | | deps | List of my macro's dependencies | `[]` | | kwargs | Other attributes to include | none | **RETURNS** An empty list. ## macro_with_kwonly
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonly")

macro_with_kwonly(name)
One keyword-only param **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | ## macro_with_kwonly_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonly_and_kwargs")

macro_with_kwonly_and_kwargs(name, kwargs)
One keyword-only param and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | kwargs | Other named arguments | none | ## macro_with_kwonlys
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonlys")

macro_with_kwonlys(name, number)
Several keyword-only params **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | ## macro_with_kwonlys_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonlys_and_kwargs")

macro_with_kwonlys_and_kwargs(name, number, kwargs)
Several keyword-only params and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | kwargs | Other named arguments | none | ## macro_with_only_args
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_args")

macro_with_only_args(args)
Macro only taking *args **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | args | Positional arguments | none | ## macro_with_only_args_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_args_and_kwargs")

macro_with_only_args_and_kwargs(args, kwargs)
Macro only taking *args and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | args | Positional arguments | none | | kwargs | Named arguments | none | ## macro_with_only_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_kwargs")

macro_with_only_kwargs(kwargs)
Macro only taking **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | kwargs | Named arguments | none | ## macro_with_ordinary_param_and_kwonlys
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_and_kwonlys")

macro_with_ordinary_param_and_kwonlys(name, number, config)
One ordinary param and several keyword-only params **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | none | | config | Configuration | none | ## macro_with_ordinary_param_args_and_kwonlys
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_args_and_kwonlys")

macro_with_ordinary_param_args_and_kwonlys(name, number, config, args)
One ordinary param, *args, and several keyword-only params **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | none | | config | Configuration | none | | args | Positional arguments | none | ## macro_with_ordinary_param_args_kwonlys_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_args_kwonlys_and_kwargs")

macro_with_ordinary_param_args_kwonlys_and_kwargs(name, number, config, args, kwargs)
One ordinary param, *args, several keyword-only params, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | none | | config | Configuration | none | | args | Other positional arguments | none | | kwargs | Other named arguments | none | ## macro_with_ordinary_param_kwonlys_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_kwonlys_and_kwargs")

macro_with_ordinary_param_kwonlys_and_kwargs(name, number, config, kwargs)
One ordinary param, several keyword-only params, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | none | | config | Configuration | none | | kwargs | Other named arguments | none | ## macro_with_ordinary_params_and_kwonly
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_and_kwonly")

macro_with_ordinary_params_and_kwonly(name, number, config)
Several ordinary params and a keyword-only param **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | config | Configuration | none | ## macro_with_ordinary_params_args_and_kwonly
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_args_and_kwonly")

macro_with_ordinary_params_args_and_kwonly(name, number, config, args)
Several ordinary params, *args, and a keyword-only param **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | config | Configuration | none | | args | Positional arguments | none | ## macro_with_ordinary_params_args_kwonly_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_args_kwonly_and_kwargs")

macro_with_ordinary_params_args_kwonly_and_kwargs(name, number, config, args, kwargs)
Several ordinary params, *args, one keyword-only param, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | config | Configuration | none | | args | Other positional arguments | none | | kwargs | Other named arguments | none | ## macro_with_ordinary_params_kwonly_and_kwargs
load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_kwonly_and_kwargs")

macro_with_ordinary_params_kwonly_and_kwargs(name, number, config, kwargs)
Several ordinary params, a keyword-only param, and **kwargs **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | The name | none | | number | The number | `3` | | config | Configuration | none | | kwargs | Other named arguments | none | stardoc-0.8.1/test/testdata/misc_apis_test/000077500000000000000000000000001513642521100207555ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/misc_apis_test/golden.md000066400000000000000000000046561513642521100225620ustar00rootroot00000000000000 ## my_rule
load("@stardoc//test:testdata/misc_apis_test/input.bzl", "my_rule")

my_rule(name, deps, src, out, extra_arguments, tool)
This rule exercises some of the build API. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | deps | A list of dependencies. | List of labels | optional | `[]` | | src | The source file. | Label | optional | `None` | | out | The output file. | Label; nonconfigurable | required | | | extra_arguments | - | List of strings | optional | `[]` | | tool | The location of the tool to use. | Label | optional | `"@stardoc//foo/bar/baz:target"` | ## MyInfo
load("@stardoc//test:testdata/misc_apis_test/input.bzl", "MyInfo")

MyInfo(foo, bar)
**FIELDS** | Name | Description | | :------------- | :------------- | | foo | Something foo-related. | | bar | Something bar-related. | ## exercise_the_api
load("@stardoc//test:testdata/misc_apis_test/input.bzl", "exercise_the_api")

exercise_the_api()
## my_rule_impl
load("@stardoc//test:testdata/misc_apis_test/input.bzl", "my_rule_impl")

my_rule_impl(ctx)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | ctx |

-

| none | stardoc-0.8.1/test/testdata/misc_apis_test/input.bzl000066400000000000000000000032561513642521100226330ustar00rootroot00000000000000# This is here to test that built-in names can be shadowed by global names. # (Regression test for http://b/35984389). # buildifier: disable=module-docstring config = "value for global config variable" def my_rule_impl(ctx): _ignore = [ctx] # @unused return [] def exercise_the_api(): var1 = config_common.FeatureFlagInfo # @unused var2 = platform_common.TemplateVariableInfo # @unused var3 = repository_rule( implementation = my_rule_impl, doc = "This repository rule has documentation.", ) # @unused var4 = testing.ExecutionInfo({}) # @unused exercise_the_api() # buildifier: disable=provider-params # buildifier: disable=unsorted-dict-items MyInfo = provider( fields = { "foo": "Something foo-related.", "bar": "Something bar-related.", }, ) my_info = MyInfo(foo = "x", bar = "y") # buildifier: disable=unsorted-dict-items my_rule = rule( implementation = my_rule_impl, doc = "This rule exercises some of the build API.", attrs = { "src": attr.label( doc = "The source file.", allow_files = [".bzl"], ), "deps": attr.label_list( doc = """ A list of dependencies. """, providers = [MyInfo], allow_files = False, ), "tool": attr.label( doc = "The location of the tool to use.", allow_files = True, default = Label("//foo/bar/baz:target"), cfg = "exec", executable = True, ), "out": attr.output( doc = "The output file.", mandatory = True, ), "extra_arguments": attr.string_list(default = []), }, ) stardoc-0.8.1/test/testdata/module_extension_test/000077500000000000000000000000001513642521100223675ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/module_extension_test/golden.md000066400000000000000000000023011513642521100241550ustar00rootroot00000000000000 Minimal example of a .bzl file defining a module extension. ## my_ext
my_ext = use_extension("@stardoc//test:testdata/module_extension_test/input.bzl", "my_ext")
my_ext.install(artifacts)
my_ext.artifact(artifact, group)
Minimal example of a module extension. **TAG CLASSES** ### install Install tag **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | artifacts | Install artifacts | List of strings | optional | `[]` | ### artifact Artifact tag **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | artifact | Artifact | String | required | | | group | Group name | String | optional | `"my_group"` | stardoc-0.8.1/test/testdata/module_extension_test/input.bzl000066400000000000000000000014321513642521100242370ustar00rootroot00000000000000"""Minimal example of a .bzl file defining a module extension.""" # buildifier: disable=unused-variable def _impl(module_ctx): """No-op""" pass _artifact = tag_class( doc = "Artifact tag", attrs = { "group": attr.string( doc = "Group name", default = "my_group", ), "artifact": attr.string( doc = "Artifact", mandatory = True, ), }, ) _install = tag_class( doc = "Install tag", attrs = { "artifacts": attr.string_list( doc = "Install artifacts", ), }, ) my_ext = module_extension( implementation = _impl, doc = "Minimal example of a module extension.", tag_classes = { "install": _install, "artifact": _artifact, }, ) stardoc-0.8.1/test/testdata/multi_level_namespace_test/000077500000000000000000000000001513642521100233435ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/multi_level_namespace_test/golden.md000066400000000000000000000043341513642521100251410ustar00rootroot00000000000000 A test that verifies documenting a multi-leveled namespace of functions. ## my_namespace.foo.bar.baz
load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace")

my_namespace.foo.bar.baz()
This function does nothing. ## my_namespace.math.min
load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace")

my_namespace.math.min(integers)
Returns the minimum of given elements. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | integers | A list of integers. Must not be empty. | none | **RETURNS** The minimum integer in the given list. ## my_namespace.min
load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace")

my_namespace.min(integers)
Returns the minimum of given elements. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | integers | A list of integers. Must not be empty. | none | **RETURNS** The minimum integer in the given list. ## my_namespace.one.three.does_nothing
load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace")

my_namespace.one.three.does_nothing()
This function does nothing. ## my_namespace.one.two.min
load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace")

my_namespace.one.two.min(integers)
Returns the minimum of given elements. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | integers | A list of integers. Must not be empty. | none | **RETURNS** The minimum integer in the given list. stardoc-0.8.1/test/testdata/multi_level_namespace_test/input.bzl000066400000000000000000000013711513642521100252150ustar00rootroot00000000000000"""A test that verifies documenting a multi-leveled namespace of functions.""" def _min(integers): """Returns the minimum of given elements. Args: integers: A list of integers. Must not be empty. Returns: The minimum integer in the given list. """ _ignore = [integers] # @unused return 42 def _does_nothing(): """This function does nothing.""" pass my_namespace = struct( dropped_field = "Note this field should not be documented", min = _min, math = struct(min = _min), foo = struct( bar = struct(baz = _does_nothing), num = 12, string = "Hello!", ), one = struct( two = struct(min = _min), three = struct(does_nothing = _does_nothing), ), ) stardoc-0.8.1/test/testdata/multi_level_namespace_test_with_allowlist/000077500000000000000000000000001513642521100264705ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/multi_level_namespace_test_with_allowlist/golden.md000066400000000000000000000030001513642521100302530ustar00rootroot00000000000000 A test that verifies documenting a multi-leveled namespace of functions with allowlist symbols. The allowlist symbols should cause everything in my_namespace to to be documented, but only a specific symbol in other_namespace to be documented. ## my_namespace.math.min
load("@stardoc//test:testdata/multi_level_namespace_test_with_allowlist/input.bzl", "my_namespace")

my_namespace.math.min(integers)
Returns the minimum of given elements. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | integers |

-

| none | ## my_namespace.min
load("@stardoc//test:testdata/multi_level_namespace_test_with_allowlist/input.bzl", "my_namespace")

my_namespace.min(integers)
Returns the minimum of given elements. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | integers |

-

| none | ## other_namespace.foo.nothing
load("@stardoc//test:testdata/multi_level_namespace_test_with_allowlist/input.bzl", "other_namespace")

other_namespace.foo.nothing()
This function does nothing. stardoc-0.8.1/test/testdata/multi_level_namespace_test_with_allowlist/input.bzl000066400000000000000000000012271513642521100303420ustar00rootroot00000000000000"""A test that verifies documenting a multi-leveled namespace of functions with allowlist symbols. The allowlist symbols should cause everything in my_namespace to to be documented, but only a specific symbol in other_namespace to be documented.""" def _min(integers): """Returns the minimum of given elements.""" _ignore = [integers] # @unused return 42 def _does_nothing(): """This function does nothing.""" pass my_namespace = struct( dropped_field = "Note this field should not be documented", min = _min, math = struct(min = _min), ) other_namespace = struct( foo = struct(nothing = _does_nothing), min = _min, ) stardoc-0.8.1/test/testdata/multiple_files_test/000077500000000000000000000000001513642521100220235ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/multiple_files_test/dep.bzl000066400000000000000000000007201513642521100233030ustar00rootroot00000000000000"""A dependency file for multiple_files_test.""" load(":testdata/multiple_files_test/inner_dep.bzl", "inner_rule_impl", "prep_work") def some_cool_function(name, srcs = [], beef = ""): """A pretty cool function. You should call it. Args: name: Some sort of name. srcs: What sources you want cool stuff to happen to. beef: Your opinion on beef. """ x = (name, srcs, beef) # @unused prep_work() my_rule_impl = inner_rule_impl stardoc-0.8.1/test/testdata/multiple_files_test/golden.md000066400000000000000000000060531513642521100236210ustar00rootroot00000000000000 A direct dependency file of the input file. ## my_rule
load("@stardoc//test:testdata/multiple_files_test/input.bzl", "my_rule")

my_rule(name, first, second)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first my_rule doc string | Label | required | | | second | - | Dictionary: String -> String | required | | ## other_rule
load("@stardoc//test:testdata/multiple_files_test/input.bzl", "other_rule")

other_rule(name, fourth, third)
This is another rule. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | fourth | - | Dictionary: String -> String | required | | | third | third other_rule doc string | Label | required | | ## yet_another_rule
load("@stardoc//test:testdata/multiple_files_test/input.bzl", "yet_another_rule")

yet_another_rule(name, fifth)
This is yet another rule **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | fifth | - | Label | required | | ## top_fun
load("@stardoc//test:testdata/multiple_files_test/input.bzl", "top_fun")

top_fun(a, b, c)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | a |

-

| none | | b |

-

| none | | c |

-

| none | stardoc-0.8.1/test/testdata/multiple_files_test/inner_dep.bzl000066400000000000000000000002771513642521100245050ustar00rootroot00000000000000"""A deep dependency file.""" def prep_work(): """Does some prep work. Nothing to see here.""" return 1 def inner_rule_impl(ctx): _ignore = [ctx] # @unused return struct() stardoc-0.8.1/test/testdata/multiple_files_test/input.bzl000066400000000000000000000021041513642521100236700ustar00rootroot00000000000000"""A direct dependency file of the input file.""" load(":testdata/multiple_files_test/dep.bzl", "my_rule_impl", "some_cool_function") my_rule = rule( implementation = my_rule_impl, doc = "This is my rule. It does stuff.", attrs = { "first": attr.label( mandatory = True, doc = "first my_rule doc string", allow_single_file = True, ), "second": attr.string_dict(mandatory = True), }, ) def top_fun(a, b, c): some_cool_function(a, b, c) return 6 # buildifier: disable=unsorted-dict-items other_rule = rule( implementation = my_rule_impl, doc = "This is another rule.", attrs = { "third": attr.label( mandatory = True, doc = "third other_rule doc string", allow_single_file = True, ), "fourth": attr.string_dict(mandatory = True), }, ) yet_another_rule = rule( implementation = my_rule_impl, doc = "This is yet another rule", attrs = { "fifth": attr.label(mandatory = True, allow_single_file = True), }, ) stardoc-0.8.1/test/testdata/multiple_files_test/noenable_bzlmod_golden.md000066400000000000000000000061171513642521100270340ustar00rootroot00000000000000 A direct dependency file of the input file. ## my_rule
load("@io_bazel_stardoc//test:testdata/multiple_files_test/input.bzl", "my_rule")

my_rule(name, first, second)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first my_rule doc string | Label | required | | | second | - | Dictionary: String -> String | required | | ## other_rule
load("@io_bazel_stardoc//test:testdata/multiple_files_test/input.bzl", "other_rule")

other_rule(name, fourth, third)
This is another rule. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | fourth | - | Dictionary: String -> String | required | | | third | third other_rule doc string | Label | required | | ## yet_another_rule
load("@io_bazel_stardoc//test:testdata/multiple_files_test/input.bzl", "yet_another_rule")

yet_another_rule(name, fifth)
This is yet another rule **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | fifth | - | Label | required | | ## top_fun
load("@io_bazel_stardoc//test:testdata/multiple_files_test/input.bzl", "top_fun")

top_fun(a, b, c)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | a |

-

| none | | b |

-

| none | | c |

-

| none | stardoc-0.8.1/test/testdata/multiple_rules_test/000077500000000000000000000000001513642521100220535ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/multiple_rules_test/golden.md000066400000000000000000000054671513642521100236610ustar00rootroot00000000000000 ## my_rule
load("@stardoc//test:testdata/multiple_rules_test/input.bzl", "my_rule")

my_rule(name, first, second)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | - | Label | required | | | second | - | Dictionary: String -> String | required | | ## other_rule
load("@stardoc//test:testdata/multiple_rules_test/input.bzl", "other_rule")

other_rule(name, fourth, third)
This is another rule. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | fourth | - | Dictionary: String -> String | required | | | third | - | Label | required | | ## yet_another_rule
load("@stardoc//test:testdata/multiple_rules_test/input.bzl", "yet_another_rule")

yet_another_rule(name, fifth)
This is yet another rule **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | fifth | - | Label | required | | ## my_rule_impl
load("@stardoc//test:testdata/multiple_rules_test/input.bzl", "my_rule_impl")

my_rule_impl(ctx)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | ctx |

-

| none | stardoc-0.8.1/test/testdata/multiple_rules_test/input.bzl000066400000000000000000000016551513642521100237320ustar00rootroot00000000000000# buildifier: disable=module-docstring def my_rule_impl(ctx): _ignore = [ctx] # @unused return [] my_rule = rule( implementation = my_rule_impl, doc = "This is my rule. It does stuff.", attrs = { "first": attr.label(mandatory = True, allow_single_file = True), "second": attr.string_dict(mandatory = True), }, ) # buildifier: disable=unsorted-dict-items other_rule = rule( implementation = my_rule_impl, doc = "This is another rule.", attrs = { "third": attr.label(mandatory = True, allow_single_file = True), "_hidden": attr.string(), "fourth": attr.string_dict(mandatory = True), }, ) # buildifier: disable=unsorted-dict-items yet_another_rule = rule( implementation = my_rule_impl, doc = "This is yet another rule", attrs = { "_hidden": attr.string(), "fifth": attr.label(mandatory = True, allow_single_file = True), }, ) stardoc-0.8.1/test/testdata/namespace_test/000077500000000000000000000000001513642521100207425ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/namespace_test/golden.md000066400000000000000000000037211513642521100225370ustar00rootroot00000000000000 A test that verifies documenting a namespace of functions. ## my_namespace.assert_non_empty
load("@stardoc//test:testdata/namespace_test/input.bzl", "my_namespace")

my_namespace.assert_non_empty(some_list, other_list)
Asserts the two given lists are not empty. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | some_list | The first list | none | | other_list | The second list | none | ## my_namespace.join_strings
load("@stardoc//test:testdata/namespace_test/input.bzl", "my_namespace")

my_namespace.join_strings(strings, delimiter)
Joins the given strings with a delimiter. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | strings | A list of strings to join. | none | | delimiter | The delimiter to use | `", "` | **RETURNS** The joined string. ## my_namespace.min
load("@stardoc//test:testdata/namespace_test/input.bzl", "my_namespace")

my_namespace.min(integers)
Returns the minimum of given elements. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | integers | A list of integers. Must not be empty. | none | **RETURNS** The minimum integer in the given list. stardoc-0.8.1/test/testdata/namespace_test/input.bzl000066400000000000000000000020321513642521100226070ustar00rootroot00000000000000"""A test that verifies documenting a namespace of functions.""" def _min(integers): """Returns the minimum of given elements. Args: integers: A list of integers. Must not be empty. Returns: The minimum integer in the given list. """ _ignore = [integers] # @unused return 42 def _assert_non_empty(some_list, other_list): """Asserts the two given lists are not empty. Args: some_list: The first list other_list: The second list """ _ignore = [some_list, other_list] # @unused fail("Not implemented") def _join_strings(strings, delimiter = ", "): """Joins the given strings with a delimiter. Args: strings: A list of strings to join. delimiter: The delimiter to use Returns: The joined string. """ _ignore = [strings, delimiter] # @unused return "" my_namespace = struct( dropped_field = "Note this field should not be documented", assert_non_empty = _assert_non_empty, min = _min, join_strings = _join_strings, ) stardoc-0.8.1/test/testdata/proto_format_test/000077500000000000000000000000001513642521100215215ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/proto_format_test/golden.binaryproto000066400000000000000000000014161513642521100252650ustar00rootroot00000000000000  my_exampleSmall example of rule.* nameA unique name for this target. 7 uselessThis argument will be ignored.2 "ignoreme""A my_example3@stardoc//test:testdata/proto_format_test/input.bzl example$Stores information about an example. fooA string representing foo barA string representing bar bazA string representing baz"> example3@stardoc//test:testdata/proto_format_test/input.bzl check_function% fooA unique name for this rule. Runs some checks on the given function parameter. This rule runs checks on a given function parameter. Use `bazel build` to run the check. 2E check_function3@stardoc//test:testdata/proto_format_test/input.bzl* Input file for proto format test23@stardoc//test:testdata/proto_format_test/input.bzlstardoc-0.8.1/test/testdata/proto_format_test/input.bzl000066400000000000000000000016001513642521100233660ustar00rootroot00000000000000"""Input file for proto format test""" def check_function(foo): """Runs some checks on the given function parameter. This rule runs checks on a given function parameter. Use `bazel build` to run the check. Args: foo: A unique name for this rule. """ _ignore = foo # @unused pass # buildifier: disable=unsorted-dict-items example = provider( doc = "Stores information about an example.", fields = { "foo": "A string representing foo", "bar": "A string representing bar", "baz": "A string representing baz", }, ) def _rule_impl(ctx): _ignore = [ctx] # @unused return [] my_example = rule( implementation = _rule_impl, doc = "Small example of rule.", attrs = { "useless": attr.string( doc = "This argument will be ignored.", default = "ignoreme", ), }, ) stardoc-0.8.1/test/testdata/provider_basic_test/000077500000000000000000000000001513642521100220015ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/provider_basic_test/golden.md000066400000000000000000000137371513642521100236060ustar00rootroot00000000000000 ## MyCustomInitInfo
load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyCustomInitInfo")

MyCustomInitInfo(foo, bar)
A provider with a custom constructor. Since the custom constructor parameters match the provider's fields, we don't need to render a separate table of constructor parameters. **FIELDS** | Name | Description | | :------------- | :------------- | | foo | Foo data | | bar | Bar data. | ## MyCustomInitWithDefaultParamValueInfo
load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyCustomInitWithDefaultParamValueInfo")

MyCustomInitWithDefaultParamValueInfo(foo, bar)
A provider with a custom constructor with a parameter with a default value. Since the custom constructor parameters match the provider's fields, we don't need to render a separate table of constructor parameters - but we do need to render the default value. **FIELDS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | foo | Foo data | none | | bar | Bar data. | `42` | ## MyCustomInitWithDocumentedParamInfo
load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyCustomInitWithDocumentedParamInfo")

MyCustomInitWithDocumentedParamInfo(foo, bar)
A provider with a custom constructor with documented constructor parameters. Docs for constructor parameters differ from docs for fields, so we need to render constructor parameters as a separate table. **CONSTRUCTOR PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | foo | Foo data; must be non-negative | none | | bar | Bar data. Note that we didn't document `bar` parameter for the init callback - we want this docstring to be propagated to the constructor param table. | `42` | **FIELDS** | Name | Description | | :------------- | :------------- | | foo | Foo data | | bar | Bar data. Note that we didn't document `bar` parameter for the init callback - we want this docstring to be propagated to the constructor param table. | ## MyCustomInitWithMismatchingConstructorParamsAndFieldsInfo
load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyCustomInitWithMismatchingConstructorParamsAndFieldsInfo")

MyCustomInitWithMismatchingConstructorParamsAndFieldsInfo(foo, bar)
A provider with a custom constructor whose set of constructor parameters does not equal the provider's set of fields. We have no choice - we need to render constructor parameters as a separate table. **CONSTRUCTOR PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | foo | Foo data | none | | bar | Bar data. | none | **FIELDS** | Name | Description | | :------------- | :------------- | | foo | Foo data | | bar | Bar data. | | validated | True, hopefully | ## MyDeprecatedInfo
load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyDeprecatedInfo")

MyDeprecatedInfo()
You can read this info. But should you really construct it? **DEPRECATED** Do not construct! **FIELDS** | Name | Description | | :------------- | :------------- | | foo | Foo | ## MyFooInfo
load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyFooInfo")

MyFooInfo(bar, baz)
Stores information about a foo. **FIELDS** | Name | Description | | :------------- | :------------- | | bar | - | | baz | - | ## MyPoorlyDocumentedInfo
load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyPoorlyDocumentedInfo")

MyPoorlyDocumentedInfo()
## MyVeryDocumentedInfo
load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyVeryDocumentedInfo")

MyVeryDocumentedInfo(favorite_food, favorite_color)
A provider with some really neat documentation. Look on my works, ye mighty, and despair! **FIELDS** | Name | Description | | :------------- | :------------- | | favorite_food | A string representing my favorite food

Expected to be delicious. | | favorite_color | A string representing my favorite color | stardoc-0.8.1/test/testdata/provider_basic_test/input.bzl000066400000000000000000000106251513642521100236550ustar00rootroot00000000000000# buildifier: disable=module-docstring # buildifier: disable=provider-params MyPoorlyDocumentedInfo = provider() MyFooInfo = provider( doc = "Stores information about a foo.", fields = ["bar", "baz"], ) # buildifier: disable=unsorted-dict-items MyVeryDocumentedInfo = provider( doc = """ A provider with some really neat documentation. Look on my works, ye mighty, and despair! """, fields = { "favorite_food": """ A string representing my favorite food Expected to be delicious. """, "favorite_color": "A string representing my favorite color", }, ) def _init_my_custom_init_info(foo, bar): """ Validate stuff. Technical details; the user probably doesn't want to see this part. """ if foo < 0: fail("foo must be non-negative") return {"foo": foo, "bar": bar, "validated": True} MyCustomInitInfo, _new_my_custom_init_info = provider( doc = """ A provider with a custom constructor. Since the custom constructor parameters match the provider's fields, we don't need to render a separate table of constructor parameters. """, init = _init_my_custom_init_info, fields = { "foo": "Foo data", "bar": "Bar data.", }, ) def _init_my_custom_init_with_default_param_value_info(foo, bar = 42): """ Validate stuff. Technical details; the user probably doesn't want to see this part. """ if foo < 0: fail("foo must be non-negative") return {"foo": foo, "bar": bar, "validated": True} MyCustomInitWithDefaultParamValueInfo, _new_my_custom_init_with_default_param_value_info = provider( doc = """ A provider with a custom constructor with a parameter with a default value. Since the custom constructor parameters match the provider's fields, we don't need to render a separate table of constructor parameters - but we do need to render the default value. """, init = _init_my_custom_init_with_default_param_value_info, fields = { "foo": "Foo data", "bar": "Bar data.", }, ) def _init_my_custom_init_with_mismatching_constructor_params_and_fields_info(foo, bar): """ Validate stuff. Technical details; the user probably doesn't want to see this part. """ if foo < 0: fail("foo must be non-negative") return {"foo": foo, "bar": bar, "validated": True} MyCustomInitWithMismatchingConstructorParamsAndFieldsInfo, _new_my_custom_init_with_mismatching_constructor_params_and_fields_info = provider( doc = """ A provider with a custom constructor whose set of constructor parameters does not equal the provider's set of fields. We have no choice - we need to render constructor parameters as a separate table. """, init = _init_my_custom_init_with_mismatching_constructor_params_and_fields_info, fields = { "foo": "Foo data", "bar": "Bar data.", "validated": "True, hopefully", }, ) # buildifier: disable=function-docstring-args def _init_my_custom_init_with_documented_param_info(foo, bar = 42): """ Validate stuff. Technical details; the user probably doesn't want to see this part. Args: foo: Foo data; must be non-negative """ if foo < 0: fail("foo must be non-negative") return {"foo": foo, "bar": bar} MyCustomInitWithDocumentedParamInfo, _new_my_custom_init_with_documented_param_info = provider( doc = """ A provider with a custom constructor with documented constructor parameters. Docs for constructor parameters differ from docs for fields, so we need to render constructor parameters as a separate table. """, init = _init_my_custom_init_with_documented_param_info, fields = { "foo": "Foo data", "bar": "Bar data. Note that we didn't document `bar` parameter for the init callback - we want this docstring to be propagated to the constructor param table.", }, ) def _init_my_deprecated_info(): """ MyDeprecatedInfo constructor. Deprecated: Do not construct! """ return {} MyDeprecatedInfo, _new_my_deprecated_info = provider( doc = """ You can read this info. But should you really construct it? """, init = _init_my_deprecated_info, fields = { "foo": "Foo", }, ) named_providers_are_hashable = { MyFooInfo: "MyFooInfo is hashable", MyVeryDocumentedInfo: "So is MyVeryDocumentedInfo", } stardoc-0.8.1/test/testdata/providers_for_attributes_test/000077500000000000000000000000001513642521100241375ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/providers_for_attributes_test/dep.bzl000066400000000000000000000002511513642521100254160ustar00rootroot00000000000000"A file to test providers not defined in the same file." # buildifier: disable=provider-params DepProviderInfo = provider( doc = "This provider does something.", ) stardoc-0.8.1/test/testdata/providers_for_attributes_test/golden.md000066400000000000000000000044611513642521100257360ustar00rootroot00000000000000 The input file for the providers for attributes test ## my_rule
load("@stardoc//test:testdata/providers_for_attributes_test/input.bzl", "my_rule")

my_rule(name, first, fourth, second, third)
This rule does things. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | this is the first attribute. | Dictionary: Label -> String | optional | `{}` | | fourth | - | Label | optional | `None` | | second | - | List of labels | optional | `[]` | | third | - | Label | optional | `None` | ## MyProviderInfo
load("@stardoc//test:testdata/providers_for_attributes_test/input.bzl", "MyProviderInfo")

MyProviderInfo(foo, bar)
**FIELDS** | Name | Description | | :------------- | :------------- | | foo | Something foo-related. | | bar | Something bar-related. | ## OtherProviderInfo
load("@stardoc//test:testdata/providers_for_attributes_test/input.bzl", "OtherProviderInfo")

OtherProviderInfo()
## my_rule_impl
load("@stardoc//test:testdata/providers_for_attributes_test/input.bzl", "my_rule_impl")

my_rule_impl(ctx)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | ctx |

-

| none | stardoc-0.8.1/test/testdata/providers_for_attributes_test/input.bzl000066400000000000000000000022001513642521100260010ustar00rootroot00000000000000"""The input file for the providers for attributes test""" load(":testdata/providers_for_attributes_test/dep.bzl", "DepProviderInfo") def my_rule_impl(ctx): _ignore = [ctx] # @unused return [] # buildifier: disable=provider-params # buildifier: disable=unsorted-dict-items MyProviderInfo = provider( fields = { "foo": "Something foo-related.", "bar": "Something bar-related.", }, ) # buildifier: disable=provider-params OtherProviderInfo = provider() other_provider_info = OtherProviderInfo(fields = ["foo"]) # buildifier: disable=unsorted-dict-items my_rule = rule( implementation = my_rule_impl, doc = "This rule does things.", attrs = { "first": attr.label_keyed_string_dict( providers = [MyProviderInfo, DefaultInfo], doc = "this is the first attribute.", ), "second": attr.label_list( providers = [[DefaultInfo], [OtherProviderInfo, DepProviderInfo]], ), "third": attr.label( providers = [OtherProviderInfo], ), "fourth": attr.label( providers = [DefaultInfo], ), }, ) stardoc-0.8.1/test/testdata/pure_markdown_template_test/000077500000000000000000000000001513642521100235565ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/pure_markdown_template_test/golden.md000066400000000000000000000062301513642521100253510ustar00rootroot00000000000000 Input file for markdown template test ## example_rule
load("@stardoc//test:testdata/pure_markdown_template_test/input.bzl", "example_rule")

example_rule(name, first, second)
Small example of rule using a markdown template. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | This is the first attribute | String | optional | `""` | | second | - | Integer | optional | `2` | ## ExampleProviderInfo
load("@stardoc//test:testdata/pure_markdown_template_test/input.bzl", "ExampleProviderInfo")

ExampleProviderInfo(foo, bar, baz)
Small example of provider using a markdown template. **FIELDS** | Name | Description | | :------------- | :------------- | | foo | A string representing foo | | bar | A string representing bar | | baz | A string representing baz | ## example_function
load("@stardoc//test:testdata/pure_markdown_template_test/input.bzl", "example_function")

example_function(foo, bar)
Small example of function using a markdown template. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | foo | This parameter does foo related things. | none | | bar | This parameter does bar related things.

For example, it does things that require **multiple paragraphs** to explain.

Note: we should preserve the nested indent in the following code:

{
    "key": "value"
}
| `"bar"` | ## example_aspect
load("@stardoc//test:testdata/pure_markdown_template_test/input.bzl", "example_aspect")

example_aspect(first, second)
Small example of aspect using a markdown template. **ASPECT ATTRIBUTES** | Name | Type | | :------------- | :------------- | | deps| String | | attr_aspect| String | **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | first | - | String | required | | | second | This is the second attribute. | String | optional | `""` | stardoc-0.8.1/test/testdata/pure_markdown_template_test/input.bzl000066400000000000000000000030111513642521100254210ustar00rootroot00000000000000"""Input file for markdown template test""" # buildifier: disable=unused-variable def example_function(foo, bar = "bar"): """Small example of function using a markdown template. Args: foo: This parameter does foo related things. bar: This parameter does bar related things. For example, it does things that require **multiple paragraphs** to explain. Note: we should preserve the nested indent in the following code: ```json { "key": "value" } ``` """ pass ExampleProviderInfo = provider( doc = "Small example of provider using a markdown template.", fields = { "foo": "A string representing foo", "bar": "A string representing bar", "baz": "A string representing baz", }, ) # buildifier: disable=unused-variable def _rule_impl(ctx): return [] example_rule = rule( implementation = _rule_impl, doc = "Small example of rule using a markdown template.", attrs = { "first": attr.string(doc = "This is the first attribute"), "second": attr.int(default = 2), }, ) # buildifier: disable=unused-variable def _aspect_impl(ctx): return [] example_aspect = aspect( implementation = _aspect_impl, doc = "Small example of aspect using a markdown template.", attr_aspects = ["deps", "attr_aspect"], attrs = { "first": attr.string(mandatory = True), "second": attr.string(doc = "This is the second attribute."), }, ) stardoc-0.8.1/test/testdata/repo_rules_test/000077500000000000000000000000001513642521100211655ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/repo_rules_test/bazel_8_golden.md000066400000000000000000000032501513642521100243630ustar00rootroot00000000000000 ## my_repo
load("@stardoc//test:testdata/repo_rules_test/input.bzl", "my_repo")

my_repo(name, repo_mapping, useless)
Minimal example of a repository rule. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this repository. | Name | required | | | repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).

This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | Dictionary: String -> String | optional | | | useless | This argument will be ignored.

You don't have to specify it, but you may. | String | optional | `"ignoreme"` | **ENVIRONMENT VARIABLES** This repository rule depends on the following environment variables: * `FOO_CC` * `BAR_PATH` stardoc-0.8.1/test/testdata/repo_rules_test/golden.md000066400000000000000000000016071513642521100227630ustar00rootroot00000000000000 ## my_repo
load("@stardoc//test:testdata/repo_rules_test/input.bzl", "my_repo")

my_repo(name, useless)
Minimal example of a repository rule. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this repository. | Name | required | | | useless | This argument will be ignored.

You don't have to specify it, but you may. | String | optional | `"ignoreme"` | **ENVIRONMENT VARIABLES** This repository rule depends on the following environment variables: * `FOO_CC` * `BAR_PATH` stardoc-0.8.1/test/testdata/repo_rules_test/input.bzl000066400000000000000000000007271513642521100230430ustar00rootroot00000000000000# buildifier: disable=module-docstring def _repo_rule_impl(ctx): ctx.file("BUILD", "") my_repo = repository_rule( implementation = _repo_rule_impl, doc = "Minimal example of a repository rule.", attrs = { "useless": attr.string( doc = """This argument will be ignored. You don't have to specify it, but you may. """, default = "ignoreme", ), }, environ = ["FOO_CC", "BAR_PATH"], ) stardoc-0.8.1/test/testdata/same_level_file_test/000077500000000000000000000000001513642521100221215ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/same_level_file_test/BUILD000066400000000000000000000003701513642521100227030ustar00rootroot00000000000000filegroup( name = "srcs", testonly = 0, srcs = glob(["**"]), visibility = ["//src:__subpackages__"], ) exports_files( [ "dep.bzl", "golden.md", "noenable_bzlmod_golden.md", "input.bzl", ], ) stardoc-0.8.1/test/testdata/same_level_file_test/dep.bzl000066400000000000000000000002321513642521100233770ustar00rootroot00000000000000# buildifier: disable=module-docstring # buildifier: disable=function-docstring def my_rule_impl(ctx): _ignore = [ctx] # @unused return struct() stardoc-0.8.1/test/testdata/same_level_file_test/golden.md000066400000000000000000000016411513642521100237150ustar00rootroot00000000000000 ## my_rule
load("@stardoc//test/testdata/same_level_file_test:input.bzl", "my_rule")

my_rule(name, first, second)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first my_rule doc string | Label | required | | | second | - | Dictionary: String -> String | required | | stardoc-0.8.1/test/testdata/same_level_file_test/input.bzl000066400000000000000000000006201513642521100237670ustar00rootroot00000000000000# buildifier: disable=module-docstring load(":dep.bzl", "my_rule_impl") my_rule = rule( implementation = my_rule_impl, doc = "This is my rule. It does stuff.", attrs = { "first": attr.label( mandatory = True, doc = "first my_rule doc string", allow_single_file = True, ), "second": attr.string_dict(mandatory = True), }, ) stardoc-0.8.1/test/testdata/same_level_file_test/noenable_bzlmod_golden.md000066400000000000000000000016521513642521100271310ustar00rootroot00000000000000 ## my_rule
load("@io_bazel_stardoc//test/testdata/same_level_file_test:input.bzl", "my_rule")

my_rule(name, first, second)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first my_rule doc string | Label | required | | | second | - | Dictionary: String -> String | required | | stardoc-0.8.1/test/testdata/scl_test/000077500000000000000000000000001513642521100175675ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/scl_test/golden.md000066400000000000000000000015231513642521100213620ustar00rootroot00000000000000 A test that verifies support for .scl files. ## my_function
load("@stardoc//test:testdata/scl_test/input.scl", "my_function")

my_function(x, y, z, **kwargs)
Dummy function Adds three values. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | x |

-

| none | | y |

-

| none | | z |

-

| `"foo"` | | kwargs |

-

| none | **RETURNS** x + y + z stardoc-0.8.1/test/testdata/scl_test/input.scl000066400000000000000000000003201513642521100214240ustar00rootroot00000000000000"""A test that verifies support for .scl files.""" def my_function(x, y, z = "foo", **kwargs): """ Dummy function Adds three values. Returns: x + y + z """ return x + y + z stardoc-0.8.1/test/testdata/simple_test/000077500000000000000000000000001513642521100202775ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/simple_test/golden.md000066400000000000000000000024261513642521100220750ustar00rootroot00000000000000 ## my_rule
load("@stardoc//test:testdata/simple_test/input.bzl", "my_rule")

my_rule(name, first, fourth, second, third)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first doc string | Label | required | | | fourth | fourth doc string | Boolean | optional | `False` | | second | - | Dictionary: String -> String | required | | | third | - | Label; nonconfigurable | required | | stardoc-0.8.1/test/testdata/simple_test/input.bzl000066400000000000000000000012031513642521100221430ustar00rootroot00000000000000# buildifier: disable=module-docstring def my_rule_impl(ctx): _ignore = [ctx] # @unused return [] # buildifier: disable=unsorted-dict-items my_rule = rule( implementation = my_rule_impl, doc = "This is my rule. It does stuff.", attrs = { "first": attr.label( mandatory = True, doc = "first doc string", allow_single_file = True, ), "second": attr.string_dict(mandatory = True), "third": attr.output(mandatory = True), "fourth": attr.bool(default = False, doc = "fourth doc string", mandatory = False), "_hidden": attr.string(), }, ) stardoc-0.8.1/test/testdata/stamping_test/000077500000000000000000000000001513642521100206305ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/stamping_test/golden.md000066400000000000000000000001451513642521100224220ustar00rootroot00000000000000This Stardoc was built in the `AD` era. Host is a non-empty string. This key does not exist: ``. stardoc-0.8.1/test/testdata/stamping_test/golden_stamping_off.md000066400000000000000000000001111513642521100251470ustar00rootroot00000000000000This Stardoc was built on ``. This Stardoc was built on ``. Host: ``. stardoc-0.8.1/test/testdata/stamping_test/input.bzl000066400000000000000000000000431513642521100224750ustar00rootroot00000000000000# nothing needed, only uses header stardoc-0.8.1/test/testdata/stamping_test/stamping_header.vm000066400000000000000000000013331513642521100243260ustar00rootroot00000000000000## "G" in the format below is for "Era". So long as we don't go back in time ~2000 years, this should always be "AD", ## and we don't have to fiddle with handling varying timestamps in the test. This Stardoc was built in the `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "G")` era. ## Should test a stable value, but stable contains quasi sensitive info, so don't print that in the test output #if ($stamping.stable.BUILD_HOST) Host is a non-empty string. #else Host is empty or null. #end ## Sometimes Stardoc is built without --workspace_status_command (e.g. in build tests), luckily "$!foo" will tell ## Velocity to ignore null values: This key does not exist: `$!stamping.stable.STABLE_GIT_COMMIT`. stardoc-0.8.1/test/testdata/stamping_test/stamping_header_stamping_off.vm000066400000000000000000000004351513642521100270640ustar00rootroot00000000000000This Stardoc was built on `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "yyyy MMM dd, HH:mm")`. This Stardoc was built on `$util.formatBuildTimestamp("$!stamping.volatile.BUILD_TIMESTAMP", "UTC", "yyyy MMM dd, HH:mm")`. Host: `$!stamping.stable.BUILD_HOST`. stardoc-0.8.1/test/testdata/struct_default_value_test/000077500000000000000000000000001513642521100232325ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/struct_default_value_test/golden.md000066400000000000000000000031211513642521100250210ustar00rootroot00000000000000 The input file for struct default values test ## check_struct_default_values
load("@stardoc//test:testdata/struct_default_value_test/input.bzl", "check_struct_default_values")

check_struct_default_values(struct_no_args, struct_arg, struct_args, struct_int_args,
                            struct_struct_args)
Checks the default values of structs. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | struct_no_args | struct with no arguments | `struct()` | | struct_arg | struct with one argument | `struct(foo = "bar")` | | struct_args | struct with multiple arguments | `struct(bar = "foo", foo = "bar")` | | struct_int_args | struct with int arguments | `struct(one = 1, three = 3, two = 2)` | | struct_struct_args | struct with struct arguments | `struct(multiple = struct(one = 1, three = 3, two = 2), none = struct(), one = struct(foo = "bar"))` | stardoc-0.8.1/test/testdata/struct_default_value_test/input.bzl000066400000000000000000000014701513642521100251040ustar00rootroot00000000000000"""The input file for struct default values test""" # buildifier: disable=unused-variable def check_struct_default_values( struct_no_args = struct(), struct_arg = struct(foo = "bar"), struct_args = struct(foo = "bar", bar = "foo"), struct_int_args = struct(one = 1, two = 2, three = 3), struct_struct_args = struct( none = struct(), one = struct(foo = "bar"), multiple = struct(one = 1, two = 2, three = 3), )): """Checks the default values of structs. Args: struct_no_args: struct with no arguments struct_arg: struct with one argument struct_args: struct with multiple arguments struct_int_args: struct with int arguments struct_struct_args: struct with struct arguments """ pass stardoc-0.8.1/test/testdata/symbolic_macro_finalizer_test/000077500000000000000000000000001513642521100240535ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/symbolic_macro_finalizer_test/golden.md000066400000000000000000000033711513642521100256510ustar00rootroot00000000000000 Finalizer tests ## my_finalizer
load("@stardoc//test:testdata/symbolic_macro_finalizer_test/input.bzl", "my_finalizer")

my_finalizer(*, name, ignore_targets, visibility)
This macro is a rule finalizer. Finalizes a package. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | ignore_targets | Targets to ignore | List of labels; nonconfigurable | optional | `[]` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | stardoc-0.8.1/test/testdata/symbolic_macro_finalizer_test/input.bzl000066400000000000000000000005621513642521100257260ustar00rootroot00000000000000"""Finalizer tests""" # buildifier: disable=unused-variable def _impl(name, visibility, **kwargs): pass my_finalizer = macro( doc = """Finalizes a package.""", attrs = { "ignore_targets": attr.label_list( doc = "Targets to ignore", configurable = False, ), }, finalizer = True, implementation = _impl, ) stardoc-0.8.1/test/testdata/symbolic_macro_inherit_attrs_test/000077500000000000000000000000001513642521100247475ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/symbolic_macro_inherit_attrs_test/bazel_8_golden.md000066400000000000000000000677511513642521100301650ustar00rootroot00000000000000 Symbolic macro attribute inheritance tests ## inherit_from_common
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_common")

inherit_from_common(*, name, srcs, compatible_with, deprecation, exec_compatible_with,
                    exec_properties, features, package_metadata, restricted_to, tags,
                    target_compatible_with, testonly, toolchains, visibility)
InheritFromCommon: Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | srcs | Source files | List of labels | optional | `[]` | | compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | deprecation | Inherited rule attribute | String; nonconfigurable | optional | `None` | | exec_compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | exec_properties | Inherited rule attribute | Dictionary: String -> String | optional | `None` | | features | Inherited rule attribute | List of strings | optional | `None` | | package_metadata | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | restricted_to | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | tags | Inherited rule attribute | List of strings; nonconfigurable | optional | `None` | | target_compatible_with | Inherited rule attribute | List of labels | optional | `None` | | testonly | Inherited rule attribute | Boolean; nonconfigurable | optional | `None` | | toolchains | Inherited rule attribute | List of labels | optional | `None` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_macro
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_macro")

inherit_from_macro(*, name, deps, srcs, args, visibility)
InheritFromMacro: Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | deps | Dependencies | List of labels | optional | `None` | | srcs | Source files | List of labels | optional | `[]` | | args | Arguments | List of strings | required | | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_macro_no_doc
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_macro_no_doc")

inherit_from_macro_no_doc(*, name, deps, srcs, args, visibility)
**ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | deps | Dependencies | List of labels | optional | `None` | | srcs | Source files | List of labels | optional | `[]` | | args | Arguments | List of strings | required | | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_rule
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_rule")

inherit_from_rule(*, name, deps, srcs, args, compatible_with, deprecation, exec_compatible_with,
                  exec_properties, features, package_metadata, restricted_to, tags,
                  target_compatible_with, testonly, toolchains, visibility)
InheritFromRule: Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | deps | Dependencies | List of labels | optional | `None` | | srcs | Source files | List of labels | optional | `[]` | | args | Arguments | List of strings | required | | | compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | deprecation | Inherited rule attribute | String; nonconfigurable | optional | `None` | | exec_compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | exec_properties | Inherited rule attribute | Dictionary: String -> String | optional | `None` | | features | Inherited rule attribute | List of strings | optional | `None` | | package_metadata | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | restricted_to | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | tags | Inherited rule attribute | List of strings; nonconfigurable | optional | `None` | | target_compatible_with | Inherited rule attribute | List of labels | optional | `None` | | testonly | Inherited rule attribute | Boolean; nonconfigurable | optional | `None` | | toolchains | Inherited rule attribute | List of labels | optional | `None` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_rule_no_doc
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_rule_no_doc")

inherit_from_rule_no_doc(*, name, deps, srcs, args, compatible_with, deprecation,
                         exec_compatible_with, exec_properties, features, package_metadata,
                         restricted_to, tags, target_compatible_with, testonly, toolchains,
                         visibility)
**ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | deps | Dependencies | List of labels | optional | `None` | | srcs | Source files | List of labels | optional | `[]` | | args | Arguments | List of strings | required | | | compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | deprecation | Inherited rule attribute | String; nonconfigurable | optional | `None` | | exec_compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | exec_properties | Inherited rule attribute | Dictionary: String -> String | optional | `None` | | features | Inherited rule attribute | List of strings | optional | `None` | | package_metadata | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | restricted_to | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | tags | Inherited rule attribute | List of strings; nonconfigurable | optional | `None` | | target_compatible_with | Inherited rule attribute | List of labels | optional | `None` | | testonly | Inherited rule attribute | Boolean; nonconfigurable | optional | `None` | | toolchains | Inherited rule attribute | List of labels | optional | `None` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_rule_with_overrides
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_rule_with_overrides")

inherit_from_rule_with_overrides(*, name, srcs, args, compatible_with, deprecation,
                                 exec_compatible_with, exec_properties, features, package_metadata,
                                 restricted_to, tags, target_compatible_with, testonly, toolchains,
                                 visibility)
InheritFromRuleWithOverrides: Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | srcs | Source files | List of labels | optional | `[]` | | args | Override docs for Arguments | List of strings | required | | | compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | deprecation | Inherited rule attribute | String; nonconfigurable | optional | `None` | | exec_compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | exec_properties | Inherited rule attribute | Dictionary: String -> String | optional | `None` | | features | Inherited rule attribute | List of strings | optional | `None` | | package_metadata | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | restricted_to | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | tags | Inherited rule attribute | List of strings; nonconfigurable | optional | `None` | | target_compatible_with | Inherited rule attribute | List of labels | optional | `None` | | testonly | Inherited rule attribute | Boolean; nonconfigurable | optional | `None` | | toolchains | Inherited rule attribute | List of labels | optional | `None` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | stardoc-0.8.1/test/testdata/symbolic_macro_inherit_attrs_test/golden.md000066400000000000000000000763271513642521100265600ustar00rootroot00000000000000 Symbolic macro attribute inheritance tests ## inherit_from_common
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_common")

inherit_from_common(*, name, srcs, aspect_hints, compatible_with, deprecation, exec_compatible_with,
                    exec_group_compatible_with, exec_properties, features, package_metadata,
                    restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)
InheritFromCommon: Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | srcs | Source files | List of labels | optional | `[]` | | aspect_hints | Inherited rule attribute | List of labels | optional | `None` | | compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | deprecation | Inherited rule attribute | String; nonconfigurable | optional | `None` | | exec_compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | exec_group_compatible_with | Inherited rule attribute | Dictionary: String -> List of labels; nonconfigurable | optional | `None` | | exec_properties | Inherited rule attribute | Dictionary: String -> String | optional | `None` | | features | Inherited rule attribute | List of strings | optional | `None` | | package_metadata | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | restricted_to | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | tags | Inherited rule attribute | List of strings; nonconfigurable | optional | `None` | | target_compatible_with | Inherited rule attribute | List of labels | optional | `None` | | testonly | Inherited rule attribute | Boolean; nonconfigurable | optional | `None` | | toolchains | Inherited rule attribute | List of labels | optional | `None` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_macro
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_macro")

inherit_from_macro(*, name, deps, srcs, args, visibility)
InheritFromMacro: Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | deps | Dependencies | List of labels | optional | `None` | | srcs | Source files | List of labels | optional | `[]` | | args | Arguments | List of strings | required | | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_macro_no_doc
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_macro_no_doc")

inherit_from_macro_no_doc(*, name, deps, srcs, args, visibility)
**ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | deps | Dependencies | List of labels | optional | `None` | | srcs | Source files | List of labels | optional | `[]` | | args | Arguments | List of strings | required | | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_rule
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_rule")

inherit_from_rule(*, name, deps, srcs, args, aspect_hints, compatible_with, deprecation,
                  exec_compatible_with, exec_group_compatible_with, exec_properties, features,
                  package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains,
                  visibility)
InheritFromRule: Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | deps | Dependencies | List of labels | optional | `None` | | srcs | Source files | List of labels | optional | `[]` | | args | Arguments | List of strings | required | | | aspect_hints | Inherited rule attribute | List of labels | optional | `None` | | compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | deprecation | Inherited rule attribute | String; nonconfigurable | optional | `None` | | exec_compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | exec_group_compatible_with | Inherited rule attribute | Dictionary: String -> List of labels; nonconfigurable | optional | `None` | | exec_properties | Inherited rule attribute | Dictionary: String -> String | optional | `None` | | features | Inherited rule attribute | List of strings | optional | `None` | | package_metadata | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | restricted_to | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | tags | Inherited rule attribute | List of strings; nonconfigurable | optional | `None` | | target_compatible_with | Inherited rule attribute | List of labels | optional | `None` | | testonly | Inherited rule attribute | Boolean; nonconfigurable | optional | `None` | | toolchains | Inherited rule attribute | List of labels | optional | `None` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_rule_no_doc
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_rule_no_doc")

inherit_from_rule_no_doc(*, name, deps, srcs, args, aspect_hints, compatible_with, deprecation,
                         exec_compatible_with, exec_group_compatible_with, exec_properties, features,
                         package_metadata, restricted_to, tags, target_compatible_with, testonly,
                         toolchains, visibility)
**ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | deps | Dependencies | List of labels | optional | `None` | | srcs | Source files | List of labels | optional | `[]` | | args | Arguments | List of strings | required | | | aspect_hints | Inherited rule attribute | List of labels | optional | `None` | | compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | deprecation | Inherited rule attribute | String; nonconfigurable | optional | `None` | | exec_compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | exec_group_compatible_with | Inherited rule attribute | Dictionary: String -> List of labels; nonconfigurable | optional | `None` | | exec_properties | Inherited rule attribute | Dictionary: String -> String | optional | `None` | | features | Inherited rule attribute | List of strings | optional | `None` | | package_metadata | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | restricted_to | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | tags | Inherited rule attribute | List of strings; nonconfigurable | optional | `None` | | target_compatible_with | Inherited rule attribute | List of labels | optional | `None` | | testonly | Inherited rule attribute | Boolean; nonconfigurable | optional | `None` | | toolchains | Inherited rule attribute | List of labels | optional | `None` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## inherit_from_rule_with_overrides
load("@stardoc//test:testdata/symbolic_macro_inherit_attrs_test/input.bzl", "inherit_from_rule_with_overrides")

inherit_from_rule_with_overrides(*, name, srcs, args, aspect_hints, compatible_with, deprecation,
                                 exec_compatible_with, exec_group_compatible_with, exec_properties,
                                 features, package_metadata, restricted_to, tags,
                                 target_compatible_with, testonly, toolchains, visibility)
InheritFromRuleWithOverrides: Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | srcs | Source files | List of labels | optional | `[]` | | args | Override docs for Arguments | List of strings | required | | | aspect_hints | Inherited rule attribute | List of labels | optional | `None` | | compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | deprecation | Inherited rule attribute | String; nonconfigurable | optional | `None` | | exec_compatible_with | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | exec_group_compatible_with | Inherited rule attribute | Dictionary: String -> List of labels; nonconfigurable | optional | `None` | | exec_properties | Inherited rule attribute | Dictionary: String -> String | optional | `None` | | features | Inherited rule attribute | List of strings | optional | `None` | | package_metadata | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | restricted_to | Inherited rule attribute | List of labels; nonconfigurable | optional | `None` | | tags | Inherited rule attribute | List of strings; nonconfigurable | optional | `None` | | target_compatible_with | Inherited rule attribute | List of labels | optional | `None` | | testonly | Inherited rule attribute | Boolean; nonconfigurable | optional | `None` | | toolchains | Inherited rule attribute | List of labels | optional | `None` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | stardoc-0.8.1/test/testdata/symbolic_macro_inherit_attrs_test/input.bzl000066400000000000000000000052571513642521100266300ustar00rootroot00000000000000"""Symbolic macro attribute inheritance tests""" # buildifier: disable=unused-variable def _impl(name, visibility, **kwargs): pass _inherit_src_macro = macro( attrs = { "args": attr.string_list( doc = "Arguments", mandatory = True, ), "deps": attr.label_list( doc = "Dependencies", ), }, doc = """Src Macro docs""", implementation = _impl, ) # buildifier: disable=unused-variable def _rule_impl(ctx): pass _inherit_src_rule = rule( attrs = { "args": attr.string_list( doc = "Arguments", mandatory = True, ), "deps": attr.label_list( doc = "Dependencies", ), }, doc = """Src Rule docs""", implementation = _rule_impl, ) inherit_from_common = macro( doc = """InheritFromCommon: Initializes some targets.""", attrs = { "srcs": attr.label_list( doc = "Source files", allow_files = True, ), }, inherit_attrs = "common", implementation = _impl, ) inherit_from_macro = macro( doc = """InheritFromMacro: Initializes some targets.""", attrs = { "srcs": attr.label_list( doc = "Source files", allow_files = True, ), }, inherit_attrs = _inherit_src_macro, implementation = _impl, ) inherit_from_macro_no_doc = macro( # No `doc` value passed. attrs = { "srcs": attr.label_list( doc = "Source files", allow_files = True, ), }, inherit_attrs = _inherit_src_macro, implementation = _impl, ) inherit_from_rule = macro( doc = """InheritFromRule: Initializes some targets.""", attrs = { "srcs": attr.label_list( doc = "Source files", allow_files = True, ), }, inherit_attrs = _inherit_src_rule, implementation = _impl, ) inherit_from_rule_with_overrides = macro( doc = """InheritFromRuleWithOverrides: Initializes some targets.""", attrs = { "srcs": attr.label_list( doc = "Source files", allow_files = True, ), # Should get custom documentation "args": attr.string_list( doc = "Override docs for Arguments", mandatory = True, ), # Should cause it to be hidden. "deps": None, }, inherit_attrs = _inherit_src_rule, implementation = _impl, ) inherit_from_rule_no_doc = macro( # No `doc` value passed. attrs = { "srcs": attr.label_list( doc = "Source files", allow_files = True, ), }, inherit_attrs = _inherit_src_rule, implementation = _impl, ) stardoc-0.8.1/test/testdata/symbolic_macro_test/000077500000000000000000000000001513642521100220105ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/symbolic_macro_test/golden.md000066400000000000000000000034041513642521100236030ustar00rootroot00000000000000 Symbolic macro tests ## basic_macro
load("@stardoc//test:testdata/symbolic_macro_test/input.bzl", "basic_macro")

basic_macro(*, name, srcs, operation, visibility)
Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | srcs | Source files | List of labels | optional | `[]` | | operation | Operation to perform | String; nonconfigurable | optional | `"FROBNICATE"` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | stardoc-0.8.1/test/testdata/symbolic_macro_test/input.bzl000066400000000000000000000007611513642521100236640ustar00rootroot00000000000000"""Symbolic macro tests""" # buildifier: disable=unused-variable def _impl(name, visibility, **kwargs): pass basic_macro = macro( doc = """Initializes some targets.""", attrs = { "srcs": attr.label_list( doc = "Source files", allow_files = True, ), "operation": attr.string( doc = "Operation to perform", configurable = False, default = "FROBNICATE", ), }, implementation = _impl, ) stardoc-0.8.1/test/testdata/table_of_contents_test/000077500000000000000000000000001513642521100224765ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/table_of_contents_test/bazel_8_golden.md000066400000000000000000000245361513642521100257060ustar00rootroot00000000000000 Test rules / providers / etc for the table of contents generation test. ## Rules - [my_rule](#my_rule) ## Providers - [MyFooInfo](#MyFooInfo) - [MyVeryDocumentedInfo](#MyVeryDocumentedInfo) ## Macros - [basic_macro](#basic_macro) ## Functions - [check_sources](#check_sources) - [returns_a_thing](#returns_a_thing) ## Aspects - [my_aspect](#my_aspect) - [other_aspect](#other_aspect) ## Repository Rules - [my_repo](#my_repo) ## Module Extensions - [my_ext](#my_ext) ## my_rule
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_rule")

my_rule(name, first, fourth, second, third)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first doc string | Label | required | | | fourth | fourth doc string | Boolean | optional | `False` | | second | - | Dictionary: String -> String | required | | | third | - | Label; nonconfigurable | required | | ## MyFooInfo
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "MyFooInfo")

MyFooInfo(bar, baz)
Stores information about a foo. **FIELDS** | Name | Description | | :------------- | :------------- | | bar | - | | baz | - | ## MyVeryDocumentedInfo
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "MyVeryDocumentedInfo")

MyVeryDocumentedInfo(favorite_food, favorite_color)
A provider with some really neat documentation. Look on my works, ye mighty, and despair! **FIELDS** | Name | Description | | :------------- | :------------- | | favorite_food | A string representing my favorite food

Expected to be delicious. | | favorite_color | A string representing my favorite color | ## check_sources
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "check_sources")

check_sources(name, required_param, bool_param, srcs, string_param, int_param, dict_param,
              struct_param)
Runs some checks on the given source files. This rule runs checks on a given set of source files. Use `bazel build` to run the check. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | A unique name for this rule. | none | | required_param | Use your imagination. | none | | bool_param |

-

| `True` | | srcs | Source files to run the checks against. | `[]` | | string_param |

-

| `""` | | int_param | Your favorite number. | `2` | | dict_param |

-

| `{}` | | struct_param |

-

| `struct(foo = "bar")` | ## returns_a_thing
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "returns_a_thing")

returns_a_thing(name)
Returns a suffixed name. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | A unique name for this rule. | none | **RETURNS** A suffixed version of the name. ## basic_macro
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "basic_macro")

basic_macro(*, name, srcs, operation, visibility)
Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | srcs | Source files | List of labels | optional | `[]` | | operation | Operation to perform | String; nonconfigurable | optional | `"FROBNICATE"` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## my_aspect
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_aspect")

my_aspect(first, second)
This is my aspect. It does stuff. **ASPECT ATTRIBUTES** | Name | Type | | :------------- | :------------- | | deps| String | | attr_aspect| String | **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | first | - | Boolean | required | | | second | - | String | required | | ## other_aspect
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "other_aspect")

other_aspect(third)
This is another aspect. **ASPECT ATTRIBUTES** **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | third | - | Integer | required | | ## my_repo
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_repo")

my_repo(name, repo_mapping, useless)
Minimal example of a repository rule. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this repository. | Name | required | | | repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).

This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | Dictionary: String -> String | optional | | | useless | This argument will be ignored.

You don't have to specify it, but you may. | String | optional | `"ignoreme"` | **ENVIRONMENT VARIABLES** This repository rule depends on the following environment variables: * `FOO_CC` * `BAR_PATH` ## my_ext
my_ext = use_extension("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_ext")
my_ext.install(artifacts)
my_ext.artifact(artifact, group)
Minimal example of a module extension. **TAG CLASSES** ### install Install tag **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | artifacts | Install artifacts | List of strings | optional | `[]` | ### artifact Artifact tag **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | artifact | Artifact | String | required | | | group | Group name | String | optional | `"my_group"` | stardoc-0.8.1/test/testdata/table_of_contents_test/golden.md000066400000000000000000000230751513642521100242770ustar00rootroot00000000000000 Test rules / providers / etc for the table of contents generation test. ## Rules - [my_rule](#my_rule) ## Providers - [MyFooInfo](#MyFooInfo) - [MyVeryDocumentedInfo](#MyVeryDocumentedInfo) ## Macros - [basic_macro](#basic_macro) ## Functions - [check_sources](#check_sources) - [returns_a_thing](#returns_a_thing) ## Aspects - [my_aspect](#my_aspect) - [other_aspect](#other_aspect) ## Repository Rules - [my_repo](#my_repo) ## Module Extensions - [my_ext](#my_ext) ## my_rule
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_rule")

my_rule(name, first, fourth, second, third)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first doc string | Label | required | | | fourth | fourth doc string | Boolean | optional | `False` | | second | - | Dictionary: String -> String | required | | | third | - | Label; nonconfigurable | required | | ## MyFooInfo
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "MyFooInfo")

MyFooInfo(bar, baz)
Stores information about a foo. **FIELDS** | Name | Description | | :------------- | :------------- | | bar | - | | baz | - | ## MyVeryDocumentedInfo
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "MyVeryDocumentedInfo")

MyVeryDocumentedInfo(favorite_food, favorite_color)
A provider with some really neat documentation. Look on my works, ye mighty, and despair! **FIELDS** | Name | Description | | :------------- | :------------- | | favorite_food | A string representing my favorite food

Expected to be delicious. | | favorite_color | A string representing my favorite color | ## check_sources
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "check_sources")

check_sources(name, required_param, bool_param, srcs, string_param, int_param, dict_param,
              struct_param)
Runs some checks on the given source files. This rule runs checks on a given set of source files. Use `bazel build` to run the check. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | A unique name for this rule. | none | | required_param | Use your imagination. | none | | bool_param |

-

| `True` | | srcs | Source files to run the checks against. | `[]` | | string_param |

-

| `""` | | int_param | Your favorite number. | `2` | | dict_param |

-

| `{}` | | struct_param |

-

| `struct(foo = "bar")` | ## returns_a_thing
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "returns_a_thing")

returns_a_thing(name)
Returns a suffixed name. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | A unique name for this rule. | none | **RETURNS** A suffixed version of the name. ## basic_macro
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "basic_macro")

basic_macro(*, name, srcs, operation, visibility)
Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | srcs | Source files | List of labels | optional | `[]` | | operation | Operation to perform | String; nonconfigurable | optional | `"FROBNICATE"` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## my_aspect
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_aspect")

my_aspect(first, second)
This is my aspect. It does stuff. **ASPECT ATTRIBUTES** | Name | Type | | :------------- | :------------- | | deps| String | | attr_aspect| String | **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | first | - | Boolean | required | | | second | - | String | required | | ## other_aspect
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "other_aspect")

other_aspect(third)
This is another aspect. **ASPECT ATTRIBUTES** **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | third | - | Integer | required | | ## my_repo
load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_repo")

my_repo(name, useless)
Minimal example of a repository rule. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this repository. | Name | required | | | useless | This argument will be ignored.

You don't have to specify it, but you may. | String | optional | `"ignoreme"` | **ENVIRONMENT VARIABLES** This repository rule depends on the following environment variables: * `FOO_CC` * `BAR_PATH` ## my_ext
my_ext = use_extension("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_ext")
my_ext.install(artifacts)
my_ext.artifact(artifact, group)
Minimal example of a module extension. **TAG CLASSES** ### install Install tag **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | artifacts | Install artifacts | List of strings | optional | `[]` | ### artifact Artifact tag **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | artifact | Artifact | String | required | | | group | Group name | String | optional | `"my_group"` | stardoc-0.8.1/test/testdata/table_of_contents_test/input.bzl000066400000000000000000000017671513642521100243610ustar00rootroot00000000000000"""Test rules / providers / etc for the table of contents generation test.""" load("//test:testdata/aspect_test/input.bzl", _my_aspect = "my_aspect", _other_aspect = "other_aspect") load("//test:testdata/function_basic_test/input.bzl", _check_sources = "check_sources", _returns_a_thing = "returns_a_thing") load("//test:testdata/module_extension_test/input.bzl", _my_ext = "my_ext") load("//test:testdata/provider_basic_test/input.bzl", _MyFooInfo = "MyFooInfo", _MyVeryDocumentedInfo = "MyVeryDocumentedInfo") load("//test:testdata/repo_rules_test/input.bzl", _my_repo = "my_repo") load("//test:testdata/simple_test/input.bzl", _my_rule = "my_rule") load("//test:testdata/symbolic_macro_test/input.bzl", _basic_macro = "basic_macro") my_rule = _my_rule MyFooInfo = _MyFooInfo MyVeryDocumentedInfo = _MyVeryDocumentedInfo check_sources = _check_sources returns_a_thing = _returns_a_thing my_aspect = _my_aspect other_aspect = _other_aspect my_repo = _my_repo my_ext = _my_ext basic_macro = _basic_macro stardoc-0.8.1/test/testdata/table_of_contents_test/noenable_bzlmod_golden.md000066400000000000000000000246701513642521100275130ustar00rootroot00000000000000 Test rules / providers / etc for the table of contents generation test. ## Rules - [my_rule](#my_rule) ## Providers - [MyFooInfo](#MyFooInfo) - [MyVeryDocumentedInfo](#MyVeryDocumentedInfo) ## Macros - [basic_macro](#basic_macro) ## Functions - [check_sources](#check_sources) - [returns_a_thing](#returns_a_thing) ## Aspects - [my_aspect](#my_aspect) - [other_aspect](#other_aspect) ## Repository Rules - [my_repo](#my_repo) ## Module Extensions - [my_ext](#my_ext) ## my_rule
load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "my_rule")

my_rule(name, first, fourth, second, third)
This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | first | first doc string | Label | required | | | fourth | fourth doc string | Boolean | optional | `False` | | second | - | Dictionary: String -> String | required | | | third | - | Label; nonconfigurable | required | | ## MyFooInfo
load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "MyFooInfo")

MyFooInfo(bar, baz)
Stores information about a foo. **FIELDS** | Name | Description | | :------------- | :------------- | | bar | - | | baz | - | ## MyVeryDocumentedInfo
load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "MyVeryDocumentedInfo")

MyVeryDocumentedInfo(favorite_food, favorite_color)
A provider with some really neat documentation. Look on my works, ye mighty, and despair! **FIELDS** | Name | Description | | :------------- | :------------- | | favorite_food | A string representing my favorite food

Expected to be delicious. | | favorite_color | A string representing my favorite color | ## check_sources
load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "check_sources")

check_sources(name, required_param, bool_param, srcs, string_param, int_param, dict_param,
              struct_param)
Runs some checks on the given source files. This rule runs checks on a given set of source files. Use `bazel build` to run the check. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | A unique name for this rule. | none | | required_param | Use your imagination. | none | | bool_param |

-

| `True` | | srcs | Source files to run the checks against. | `[]` | | string_param |

-

| `""` | | int_param | Your favorite number. | `2` | | dict_param |

-

| `{}` | | struct_param |

-

| `struct(foo = "bar")` | ## returns_a_thing
load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "returns_a_thing")

returns_a_thing(name)
Returns a suffixed name. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | A unique name for this rule. | none | **RETURNS** A suffixed version of the name. ## basic_macro
load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "basic_macro")

basic_macro(*, name, srcs, operation, visibility)
Initializes some targets. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this macro instance. Normally, this is also the name for the macro's main or only target. The names of any other targets that this macro might create will be this name with a string suffix. | Name | required | | | srcs | Source files | List of labels | optional | `[]` | | operation | Operation to perform | String; nonconfigurable | optional | `"FROBNICATE"` | | visibility | The visibility to be passed to this macro's exported targets. It always implicitly includes the location where this macro is instantiated, so this attribute only needs to be explicitly set if you want the macro's targets to be additionally visible somewhere else. | List of labels; nonconfigurable | optional | | ## my_aspect
load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "my_aspect")

my_aspect(first, second)
This is my aspect. It does stuff. **ASPECT ATTRIBUTES** | Name | Type | | :------------- | :------------- | | deps| String | | attr_aspect| String | **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | first | - | Boolean | required | | | second | - | String | required | | ## other_aspect
load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "other_aspect")

other_aspect(third)
This is another aspect. **ASPECT ATTRIBUTES** **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | third | - | Integer | required | | ## my_repo
load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "my_repo")

my_repo(name, repo_mapping, useless)
Minimal example of a repository rule. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this repository. | Name | required | | | repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).

This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | Dictionary: String -> String | optional | | | useless | This argument will be ignored.

You don't have to specify it, but you may. | String | optional | `"ignoreme"` | **ENVIRONMENT VARIABLES** This repository rule depends on the following environment variables: * `FOO_CC` * `BAR_PATH` ## my_ext
my_ext = use_extension("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "my_ext")
my_ext.install(artifacts)
my_ext.artifact(artifact, group)
Minimal example of a module extension. **TAG CLASSES** ### install Install tag **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | artifacts | Install artifacts | List of strings | optional | `[]` | ### artifact Artifact tag **Attributes** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | artifact | Artifact | String | required | | | group | Group name | String | optional | `"my_group"` | stardoc-0.8.1/test/testdata/unknown_name_test/000077500000000000000000000000001513642521100215055ustar00rootroot00000000000000stardoc-0.8.1/test/testdata/unknown_name_test/golden.md000066400000000000000000000006651513642521100233060ustar00rootroot00000000000000 ## my_rule_impl
load("@stardoc//test:testdata/unknown_name_test/input.bzl", "my_rule_impl")

my_rule_impl(ctx)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | ctx |

-

| none | stardoc-0.8.1/test/testdata/unknown_name_test/input.bzl000066400000000000000000000007061513642521100233600ustar00rootroot00000000000000# buildifier: disable=module-docstring def my_rule_impl(ctx): _ignore = [ctx] # @unused return [] # buildifier: disable=unsorted-dict-items rule( implementation = my_rule_impl, attrs = { "first": attr.label(mandatory = True, allow_single_file = True), "second": attr.string_dict(mandatory = True), "third": attr.output(mandatory = True), "fourth": attr.bool(default = False, mandatory = False), }, ) stardoc-0.8.1/update-release-binary.sh000077500000000000000000000033461513642521100177060ustar00rootroot00000000000000#!/usr/bin/env bash # Copyright 2019 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # Updates vendored Stardoc output protos from @io_bazel git. set -eu echo "** Copying stardoc_output.proto from source..." # Path of proto definition relative to Bazel source tree root PROTO_SRC=src/main/protobuf/stardoc_output.proto # Branch or commit in https://github.com/bazelbuild/bazel : "${BAZEL_BRANCH:=master}" # Retrieve the first commit to modify ${PROTO_SRC} in the history of ${BAZEL_BRANCH} # using Github API; see https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28 PROTO_SRC_SHA="$(curl -s -L -H "Accept: application/vnd.github+json" \ "https://api.github.com/repos/bazelbuild/bazel/commits?sha=${BAZEL_BRANCH}&path=${PROTO_SRC}" \ | grep -m 1 '"sha":' | sed 's/.*"sha": "\(.*\)",.*/\1/')" # Copy proto file and insert "Vendored from" slug immediately below the license. curl -s -L "https://raw.githubusercontent.com/bazelbuild/bazel/${PROTO_SRC_SHA}/${PROTO_SRC}" \ | sed '/^\/\/ limitations under the License./ a \ //\ // Vendored from '"${PROTO_SRC}"'\ // in the Bazel source tree at commit '"${PROTO_SRC_SHA}"'\ ' > stardoc/proto/stardoc_output.proto echo "** stardoc_output.proto copied." stardoc-0.8.1/update-stardoc-docs.sh000077500000000000000000000022041513642521100173610ustar00rootroot00000000000000#!/usr/bin/env bash # Copyright 2019 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # Renerates the Stardoc rule documentation from source. set -eu # Allow users to override the bazel command with e.g. bazelisk. : "${USE_BAZEL_VERSION:=8.0.0-pre.20240603.2}" : "${BAZEL:=bazelisk}" echo "** Generating Stardoc documentation..." USE_BAZEL_VERSION="${USE_BAZEL_VERSION}" ${BAZEL} build //stardoc:stardoc_doc.md echo "** Copying result to docs/stardoc_rule.md ..." cp bazel-bin/stardoc/stardoc_doc.md docs/stardoc_rule.md echo "** Done! Please manually verify the new documentation looks good before committing." stardoc-0.8.1/update-stardoc-tests.sh000077500000000000000000000053651513642521100176060ustar00rootroot00000000000000#!/usr/bin/env bash # Copyright 2019 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # Renerates most Stardoc golden files for Stardoc golden tests. # # When run, every golden file which is changed as a result of this script should # be manually examined and *heavily* scrutinized, as this usually indicates a large # in-place change of core rendering functionality of Stardoc. set -eu function run_buildozer () { # buildozer uses return code 3 to signal a no-op, so we can't use "set -e" set +e buildozer "$@" ret=$? set -e if [[ $ret != 0 && $ret != 3 ]]; then return $ret fi } function update_non_manual_tests () { echo "** Querying for non-manual tests..." regenerate $(${BAZEL} query "kind(sh_binary, //test:all) - attr(tags, manual, //test:all)" | grep _regenerate) } function update_manual_tests_with_tag () { local manual_tag="$1"; shift echo "** Querying for tests tagged \"${manual_tag}\", \"manual\" using 'USE_BAZEL_VERSION=${USE_BAZEL_VERSION:-} ${BAZEL}' $@ ..." BUILD_FLAGS="$@" regenerate $(${BAZEL} query "attr(tags, ${manual_tag}, attr(tags, manual, kind(sh_binary, //test:all)))" | grep _regenerate) } function regenerate () { echo "** Regenerating and copying goldens..." local run_cmd="run ${BUILD_FLAGS:-}" for regen_target in $@; do if [[ -z ${USE_BAZEL_VERSION:-} ]]; then echo "** Running '${BAZEL} ${run_cmd} ${regen_target}' ..." else echo "** Running 'USE_BAZEL_VERSION=${USE_BAZEL_VERSION} ${BAZEL} ${run_cmd} ${regen_target}' BAZEL_BUILD_FLAGS ..." fi ${BAZEL} ${run_cmd} "${regen_target}" done } # Allow users to override the bazel command with e.g. bazelisk. : "${BAZEL:=bazelisk}" update_non_manual_tests USE_BAZEL_VERSION="9.0.0" update_manual_tests_with_tag "bazel_9" USE_BAZEL_VERSION="8.5.1" update_manual_tests_with_tag "bazel_8" USE_BAZEL_VERSION="8.5.1" update_manual_tests_with_tag "noenable_bzlmod" --noenable_bzlmod --enable_workspace USE_BAZEL_VERSION="7.7.1" update_manual_tests_with_tag "bazel_7" echo "** Files copied." echo "Please note that not all golden files are correctly copied by this script." echo "You may want to manually run:" echo "" echo "${BAZEL} test //test:all" echo "" echo "...and manually update tests which are still broken." stardoc-0.8.1/version.bzl000066400000000000000000000012131513642521100153520ustar00rootroot00000000000000# Copyright 2021 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """The version of Stardoc.""" version = "0.8.1"