workspace: Adds rules to generate markdown docs
diff --git a/cc_toolchain/BUILD.bazel b/cc_toolchain/BUILD.bazel index 952167f..c1d3272 100644 --- a/cc_toolchain/BUILD.bazel +++ b/cc_toolchain/BUILD.bazel
@@ -4,6 +4,8 @@ "@rules_cc_toolchain//cc_toolchain:cc_toolchain_import.bzl", "cc_toolchain_import", ) +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") cc_toolchain_import( name = "all_imports", @@ -131,3 +133,35 @@ toolchain = ":linux_x86_64_toolchain", toolchain_type = "@rules_cc//cc:toolchain_type", ) + +STARLARK_SRCS = [ + "cc_toolchain", + "cc_toolchain_import", + "sysroot", + "toolchain_config", +] + +bzl_library( + name = "srcs", + srcs = [src + ".bzl" for src in STARLARK_SRCS], + visibility = ["//visibility:public"], +) + +[ + stardoc( + name = src + "_doc", + out = src + "_doc.md", + input = src + ".bzl", + deps = [ + ":srcs", + "//third_party:bazel_tools_cc_action_names", + "//third_party:rules_cc", + ], + ) + for src in STARLARK_SRCS +] + +filegroup( + name = "docs", + srcs = [":" + src + "_doc" for src in STARLARK_SRCS], +)
diff --git a/cc_toolchain/features/BUILD.bazel b/cc_toolchain/features/BUILD.bazel index 844fb7a..7050823 100644 --- a/cc_toolchain/features/BUILD.bazel +++ b/cc_toolchain/features/BUILD.bazel
@@ -4,6 +4,10 @@ "cc_toolchain_import_feature", "cc_toolchain_sysroot_feature", ) +load( + "@io_bazel_stardoc//stardoc:stardoc.bzl", + "stardoc", +) package( default_visibility = ["//cc_toolchain:__pkg__"], @@ -183,3 +187,13 @@ ], provides = ["c_standard"], ) for c_version in C_VERSIONS] + +stardoc( + name = "features_doc", + out = "features_doc.md", + input = "features.bzl", + deps = [ + "//cc_toolchain:srcs", + "//third_party:rules_cc", + ], +)
diff --git a/config/BUILD.bazel b/config/BUILD.bazel index dd4e519..f94d4cd 100644 --- a/config/BUILD.bazel +++ b/config/BUILD.bazel
@@ -1,4 +1,5 @@ load("//cc_toolchain:cc_toolchain_import.bzl", "cc_toolchain_import") +load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") package( default_visibility = ["//visibility:public"], @@ -65,3 +66,14 @@ cc_toolchain_import( name = "empty", ) + +stardoc( + name = "rules_cc_toolchain_config_docs", + out = "rules_cc_toolchain_config_docs.md", + input = "rules_cc_toolchain_config_repository.bzl", +) + +filegroup( + name = "docs", + srcs = [":rules_cc_toolchain_config_docs"], +)
diff --git a/config/rules_cc_toolchain_config_repository.bzl b/config/rules_cc_toolchain_config_repository.bzl index 8eb102e..a549ddf 100644 --- a/config/rules_cc_toolchain_config_repository.bzl +++ b/config/rules_cc_toolchain_config_repository.bzl
@@ -7,6 +7,29 @@ "build_file": attr.label( allow_single_file = True, default = "@rules_cc_toolchain//config:rules_cc_toolchain_config.BUILD", + doc = "The build file containing the configurations for this toolchain.", ), }, + doc = """ +A toolchain configuration. + +To override the default configuration use this rule before calling `rules_cc_toolchain_deps`. + +Example: +```python +load("@rules_cc_toolchain//config:rules_cc_toolchain_config_repository.bzl", + "rules_cc_toolchain_config") + +rules_cc_toolchain_config( + name = "rules_cc_toolchain_config", + build_file = "@my_workspace//config:my_config.BUILD", +) + +load("//:rules_cc_toolchain_deps.bzl", "rules_cc_toolchain_deps") + +# Must be called after rules_cc_toolchain_config rule to successfully override +# the configuration. +rules_cc_toolchain_deps() +``` +""", )
diff --git a/rules_cc_toolchain_deps.bzl b/rules_cc_toolchain_deps.bzl index 8a8578e..aefb91c 100644 --- a/rules_cc_toolchain_deps.bzl +++ b/rules_cc_toolchain_deps.bzl
@@ -3,6 +3,8 @@ load("@rules_cc_toolchain//config:rules_cc_toolchain_config_repository.bzl", "rules_cc_toolchain_config") def rules_cc_toolchain_deps(): + """Fetches the toolchain dependencies """ + # Setup latest version of Bazels platform repos. This should be called # before all other workspace deps. # Required by modules: cc_toolchain.
diff --git a/third_party/BUILD b/third_party/BUILD index e69de29..558e6e9 100644 --- a/third_party/BUILD +++ b/third_party/BUILD
@@ -0,0 +1,17 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +bzl_library( + name = "rules_cc", + srcs = [ + "@rules_cc//cc:srcs", + ], + visibility = ["//visibility:public"], +) + +bzl_library( + name = "bazel_tools_cc_action_names", + srcs = [ + "@bazel_tools//tools/build_defs/cc:action_names", + ], + visibility = ["//visibility:public"], +)
diff --git a/tools/clang_tidy/BUILD.bazel b/tools/clang_tidy/BUILD.bazel index 4540fd9..eb3f58a 100644 --- a/tools/clang_tidy/BUILD.bazel +++ b/tools/clang_tidy/BUILD.bazel
@@ -1,7 +1,19 @@ load(":clang_tidy.bzl", "clang_tidy_config") +load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") clang_tidy_config( name = "default", config = ".clang-tidy", visibility = ["//visibility:public"], ) + +stardoc( + name = "docs", + out = "clang_tidy_doc.md", + input = "clang_tidy.bzl", + symbol_names = [ + "clang_tidy_config", + "clang_tidy_aspect", + ], + deps = ["//third_party:rules_cc"], +)
diff --git a/tools/clang_tidy/clang_tidy.bzl b/tools/clang_tidy/clang_tidy.bzl index 4969f3b..20b5ce7 100644 --- a/tools/clang_tidy/clang_tidy.bzl +++ b/tools/clang_tidy/clang_tidy.bzl
@@ -170,44 +170,44 @@ }, toolchains = ["@bazel_tools//tools/cpp:toolchain_type"], doc = """ - Runs clang-tidy on the given C++ sources +Runs clang-tidy on the given C++ sources - This aspect runs clang-tidy on the given set of c/c++ sources. You can use this aspect - by running; - ``` sh - bazel build //my:target \\ - --aspects build_bazel_rules_cc//cc:clang_tidy:clang_tidy.bzl%clang_tidy_aspect - ``` +This aspect runs clang-tidy on the given set of c/c++ sources. You can use this aspect +by running; +``` sh +bazel build //my:target \\ + --aspects build_bazel_rules_cc//cc:clang_tidy:clang_tidy.bzl%clang_tidy_aspect +``` - You can override the default configuration by using the clang_tidy_config rule. e.g. - ```py - # //BUILD.bazel - cc_toolchain_config( - name = "my_config", - config = ".clang-tidy", - ) - ``` - The passing in a command line flag to point the aspect at your new config rule e.g. - ``` sh - bazel build //my:target \\ - --aspects @build_bazel_rules_cc//cc:clang_tidy:clang_tidy.bzl%clang_tidy_aspect \\ - --@rules_cc_toolchain_config//:clang_tidy_config=//:my_config - ``` +You can override the default configuration by using the clang_tidy_config rule. e.g. +```py +# //BUILD.bazel +cc_toolchain_config( + name = "my_config", + config = ".clang-tidy", +) +``` +The passing in a command line flag to point the aspect at your new config rule e.g. +``` sh +bazel build //my:target \\ + --aspects @build_bazel_rules_cc//cc:clang_tidy:clang_tidy.bzl%clang_tidy_aspect \\ + --@rules_cc_toolchain_config//:clang_tidy_config=//:my_config +``` - In most cases it is likely that you will want to shorten the command line flags using - your .bazelrc file. e.g. - ``` - # //.bazelrc - build:analyze --aspects @build_bazel_rules_cc//cc:clang_tidy:clang_tidy.bzl%clang_tidy_aspect - build:analyze --@rules_cc_toolchain_config//:clang_tidy_config=//:my_config - ``` +In most cases it is likely that you will want to shorten the command line flags using +your .bazelrc file. e.g. +``` +# //.bazelrc +build:analyze --aspects @build_bazel_rules_cc//cc:clang_tidy:clang_tidy.bzl%clang_tidy_aspect +build:analyze --@rules_cc_toolchain_config//:clang_tidy_config=//:my_config +``` - You can then run the analysis using the following command; - ``` sh - bazel build //my:target --config analyze - ``` +You can then run the analysis using the following command; +``` sh +bazel build //my:target --config analyze +``` - """, +""", ) def _clang_tidy_config_impl(ctx): @@ -218,6 +218,8 @@ attrs = { "config": attr.label( allow_single_file = [".clang-tidy"], + mandatory = True, + doc = "Clang tidy config file.", ), }, provides = [ClangTidyConfigInfo],