Add docs for various rule and macros (#17)

* Add docstrings for user facing rules

* Move the cuda_flags grammar docs to cuda_archs_flag rule

* Add docstrings for user facing macros

* Generate user docs from docstrings by stardoc

* Add docstrings for predefined toolchain configurations

* Add docstrings for toolchain configuration rules

* Generate toolchain configuration docs from docstrings by stardoc

* Update providers docstring

* Generate providers docs from docstrings by stardoc

.gitignore

@@ -1 +1,2 @@
 /bazel-*
+/docs/bazel-*

BUILD.bazel

@@ -0,0 +1,8 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+bzl_library(
+    name = "bzl_srcs",
+    srcs = glob(["**/*.bzl"]),
+    visibility = ["//visibility:public"],
+    deps = ["//cuda:bzl_srcs"],
+)

cuda/BUILD.bazel

@@ -1,3 +1,4 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load(
     "@bazel_skylib//rules:common_settings.bzl",
     "bool_flag",
@@ -8,6 +9,13 @@ load("//cuda/private:rules/flags.bzl", "cuda_archs_flag")
 
 package(default_visibility = ["//visibility:public"])
 
+bzl_library(
+    name = "bzl_srcs",
+    srcs = glob(["*.bzl"]),
+    visibility = ["//visibility:public"],
+    deps = ["//cuda/private:bzl_srcs"],
+)
+
 toolchain_type(name = "toolchain_type")
 
 # Command line flag to set ":is_enabled" config setting.

cuda/private/BUILD.bazel

@@ -0,0 +1,17 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//visibility:private"])
+
+bzl_library(
+    name = "bzl_srcs",
+    srcs = glob(["**/*.bzl"]),
+    visibility = ["//visibility:public"],
+    deps = [
+        "@bazel_skylib//:lib",
+        "@bazel_skylib//rules:common_settings",
+        "@bazel_tools//tools/build_defs/repo:http.bzl",
+        "@bazel_tools//tools/build_defs/repo:utils.bzl",
+        "@bazel_tools//tools/cpp:cc_toolchain_config_lib.bzl",
+        "@bazel_tools//tools/cpp:toolchain_utils.bzl",
+    ],
+)

cuda/private/providers.bzl

@@ -1,3 +1,5 @@
+"""Defines all providers that are used in this repo."""
+
 cuda_archs = [
     "30",
     "32",
@@ -19,7 +21,11 @@ cuda_archs = [
 ]
 
 Stage2ArchInfo = provider(
-    "",
+    """Provides the information of how the stage 2 complation is carried out.
+
+One and only one of `virtual`, `gpu` and `lto` must be set to True. For example, if `arch` is set to `80` and `virtual` is `True`, then a
+ptx embedding process is carried out for `compute_80`. Multiple `Stage2ArchInfo` can be used for specifying how a stage 1 result is
+transformed into its final form.""",
     fields = {
         "arch": "str, arch number",
         "virtual": "bool, use virtual arch, default False",
@@ -29,7 +35,8 @@ Stage2ArchInfo = provider(
 )
 
 ArchSpecInfo = provider(
-    "",
+    """Provides the information of how [GPU compilation](https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#gpu-compilation)
+is carried out of a single virtual architecture.""",
     fields = {
         "stage1_arch": "A virtual architecture, str, arch number only",
         "stage2_archs": "A list of virtual or gpu architecture, list of Stage2ArchInfo",
@@ -39,49 +46,20 @@ ArchSpecInfo = provider(
 CudaArchsInfo = provider(
     """Provides a list of CUDA archs to compile for.
 
-    To retain the flexiblity of NVCC, the extended notation is adopted, see
-    https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#extended-notation
-
-    cuda_archs spec grammar as follows:
-
-        ARCH_SPECS   ::= ARCH_SPEC [ ';' ARCH_SPECS ]
-        ARCH_SPEC    ::= [ VIRTUAL_ARCH ':' ] GPU_ARCHS
-        GPU_ARCHS    ::= GPU_ARCH [ ',' GPU_ARCHS ]
-        GPU_ARCH     ::= ( 'sm_' | 'lto_' ) ARCH_NUMBER
-                       | VIRTUAL_ARCH
-        VIRTUAL_ARCH ::= ( 'compute_' | 'lto_' ) ARCH_NUMBER
-        ARCH_NUMBER  ::= (a string in predefined cuda_archs list)
-
-    E.g.:
-        - compute_80:sm_80,sm_86
-          Use compute_80 PTX, generate cubin with sm_80 and sm_86, no PTX embedded
-        - compute_80:compute_80,sm_80,sm_86
-          Use compute_80 PTX, generate cubin with sm_80 and sm_86, PTX embedded
-        - compute_80:compute_80
-          Embed compute_80 PTX, fully relay on ptxas
-        - sm_80,sm_86
-          Same as "compute_80:sm_80,sm_86", the arch with minimum integer value will be automatically populated.
-        - sm_80;sm_86
-          Two specs used.
-        - compute_80
-          Same as "compute_80:compute_80"
-
-    Best Practices:
-        - Library supports a full range of archs from xx to yy, you should embed the yy PTX
-        - Library supports a sparse range of archs from xx to yy, you should embed the xx PTX
-
-    Read the whole chapter 5 of CUDA Compiler Driver NVCC Reference Guide, at
-    https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#gpu-compilation
-    """,
+Read the whole [Chapter 5 of CUDA Compiler Driver NVCC Reference Guide](https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#gpu-compilation)
+if more detail is needed.""",
     fields = {
         "arch_specs": "A list of ArchSpecInfo",
     },
 )
 
 CudaInfo = provider(
-    """Provider that wraps cuda build information.""",
+    """Provides cuda build artifacts that can be consumed by device linking or linking process.
+
+This provider is analog to [CcInfo](https://bazel.build/rules/lib/CcInfo) but only contains necessary information for
+linking in a flat structure.""",
     fields = {
-        "defines": "A depset of strings",
+        "defines": "A depset of strings. It is used for the compilation during device linking.",
         "objects": "A depset of objects.",  # but not rdc and pic
         "rdc_objects": "A depset of relocatable device code objects.",  # but not pic
         "pic_objects": "A depset of position indepentent code objects.",  # but not rdc
@@ -90,7 +68,7 @@ CudaInfo = provider(
 )
 
 CudaToolkitInfo = provider(
-    "",
+    """Provides the information of CUDA Toolkit.""",
     fields = {
         "path": "string of path to cuda toolkit root",
         "version_major": "int of the cuda toolkit major version, e.g, 11 for 11.6",
@@ -99,11 +77,11 @@ CudaToolkitInfo = provider(
         "link_stub": "File to the link.stub file",
         "bin2c": "File to the bin2c executable",
         "fatbinary": "File to the fatbinary executable",
-    }
+    },
 )
 
 CudaToolchainConfigInfo = provider(
-    """""",
+    """Provides the information of what the toolchain is and how the toolchain is configured.""",
     fields = {
         "action_configs": "A list of action_configs.",
         "artifact_name_patterns": "A list of artifact_name_patterns.",

cuda/private/repositories.bzl

@@ -176,6 +176,7 @@ _local_cuda = repository_rule(
 )
 
 def rules_cuda_deps():
+    """Populate the dependencies for rules_cuda. This will setup workspace dependencies (other bazel rules) and local toolchains."""
     maybe(
         name = "bazel_skylib",
         repo_rule = http_archive,

cuda/private/rules/cuda_library.bzl

@@ -97,6 +97,8 @@ def _cuda_library_impl(ctx):
     ]
 
 cuda_library = rule(
+    doc = """This rule compiles and creates static library for CUDA kernel code. The resulting targets can then be consumed by
+[C/C++ Rules](https://bazel.build/reference/be/c-cpp#rules).""",
     implementation = _cuda_library_impl,
     attrs = {
         "srcs": attr.label_list(allow_files = ALLOW_CUDA_SRCS + ALLOW_CUDA_HDRS),

cuda/private/rules/cuda_objects.bzl

@@ -75,6 +75,8 @@ def _cuda_objects_impl(ctx):
     ]
 
 cuda_objects = rule(
+    doc = """This rule produces incomplete object files that can only be consumed by `cuda_library`. It is created for relocatable device
+code and device link time optimization source files.""",
     implementation = _cuda_objects_impl,
     attrs = {
         "srcs": attr.label_list(allow_files = ALLOW_CUDA_SRCS + ALLOW_CUDA_HDRS),

cuda/private/rules/cuda_toolkit.bzl

@@ -13,14 +13,15 @@ def _impl(ctx):
     )
 
 cuda_toolkit = rule(
+    doc = """This rule provides CudaToolkitInfo.""",
     implementation = _impl,
     attrs = {
-        "path": attr.string(mandatory = True),
-        "version": attr.string(mandatory = True),
-        "nvlink": attr.label(allow_single_file = True),
-        "link_stub": attr.label(allow_single_file = True),
-        "bin2c": attr.label(allow_single_file = True),
-        "fatbinary": attr.label(allow_single_file = True),
+        "path": attr.string(mandatory = True, doc = "Root path to the CUDA Toolkit."),
+        "version": attr.string(mandatory = True, doc = "Version of the CUDA Toolkit."),
+        "nvlink": attr.label(allow_single_file = True, doc = "The nvlink executable."),
+        "link_stub": attr.label(allow_single_file = True, doc = "The link.stub text file."),
+        "bin2c": attr.label(allow_single_file = True, doc = "The bin2c executable."),
+        "fatbinary": attr.label(allow_single_file = True, doc = "The fatbinary executable."),
     },
     provides = [CudaToolkitInfo],
 )

cuda/private/rules/flags.bzl

@@ -6,6 +6,37 @@ def _cuda_archs_flag_impl(ctx):
     return CudaArchsInfo(arch_specs = cuda_helper.get_arch_specs(specs_str))
 
 cuda_archs_flag = rule(
+    doc = """A build setting for specifying cuda archs to compile for.
+
+To retain the flexiblity of NVCC, the [extended notation](https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#extended-notation) is adopted.
+
+When passing cuda_archs from commandline, its spec grammar is as follows:
+
+    ARCH_SPECS   ::= ARCH_SPEC [ ';' ARCH_SPECS ]
+    ARCH_SPEC    ::= [ VIRTUAL_ARCH ':' ] GPU_ARCHS
+    GPU_ARCHS    ::= GPU_ARCH [ ',' GPU_ARCHS ]
+    GPU_ARCH     ::= ( 'sm_' | 'lto_' ) ARCH_NUMBER
+                    | VIRTUAL_ARCH
+    VIRTUAL_ARCH ::= ( 'compute_' | 'lto_' ) ARCH_NUMBER
+    ARCH_NUMBER  ::= (a string in predefined cuda_archs list)
+
+E.g.:
+- compute_80:sm_80,sm_86
+    Use compute_80 PTX, generate cubin with sm_80 and sm_86, no PTX embedded
+- compute_80:compute_80,sm_80,sm_86
+    Use compute_80 PTX, generate cubin with sm_80 and sm_86, PTX embedded
+- compute_80:compute_80
+    Embed compute_80 PTX, fully relay on ptxas
+- sm_80,sm_86
+    Same as "compute_80:sm_80,sm_86", the arch with minimum integer value will be automatically populated.
+- sm_80;sm_86
+    Two specs used.
+- compute_80
+    Same as "compute_80:compute_80"
+
+Best Practices:
+- Library supports a full range of archs from xx to yy, you should embed the yy PTX
+- Library supports a sparse range of archs from xx to yy, you should embed the xx PTX""",
     implementation = _cuda_archs_flag_impl,
     build_setting = config.string(flag = True),
     provides = [CudaArchsInfo],

cuda/private/toolchain.bzl

@@ -24,15 +24,15 @@ def _cuda_toolchain_impl(ctx):
     ]
 
 cuda_toolchain = rule(
+    doc = """This rule consumes a `CudaToolchainConfigInfo` and provides a `platform_common.ToolchainInfo`, a.k.a, the CUDA Toolchain.""",
     implementation = _cuda_toolchain_impl,
     attrs = {
         "toolchain_config": attr.label(
             mandatory = True,
             providers = [CudaToolchainConfigInfo],
+            doc = "A target that provides a `CudaToolchainConfigInfo`.",
         ),
-        "compiler_executable": attr.string(
-            mandatory = True,
-        ),
+        "compiler_executable": attr.string(mandatory = True, doc = "The path of the main executable of this toolchain."),
         "_cc_toolchain": attr.label(default = "@bazel_tools//tools/cpp:current_cc_toolchain"),
     },
 )
@@ -56,7 +56,12 @@ def find_cuda_toolchain(ctx):
 def find_cuda_toolkit(ctx):
     return ctx.toolchains[CUDA_TOOLCHAIN_TYPE].cuda_toolkit[CudaToolkitInfo]
 
+# buildifier: disable=unnamed-macro
 def register_detected_cuda_toolchains():
+    """Helper to register the automatically detected CUDA toolchain(s).
+
+User can setup their own toolchain if needed and ignore the detected ones by not calling this macro.
+"""
     native.register_toolchains(
         "@local_cuda//toolchain:nvcc-local-toolchain",
         "@local_cuda//toolchain/clang:clang-local-toolchain",

cuda/private/toolchain_configs/clang.bzl

@@ -503,9 +503,10 @@ def _impl(ctx):
     )]
 
 cuda_toolchain_config = rule(
+    doc = """This rule provides the predefined cuda toolchain configuration for Clang.""",
     implementation = _impl,
     attrs = {
-        "cuda_toolkit": attr.label(mandatory = True, providers = [CudaToolkitInfo]),
+        "cuda_toolkit": attr.label(mandatory = True, providers = [CudaToolkitInfo], doc = "A target that provides a `CudaToolkitInfo`."),
         "toolchain_identifier": attr.string(values = ["clang"], mandatory = True),
         "_cc_toolchain": attr.label(default = "@bazel_tools//tools/cpp:current_cc_toolchain"),  # legacy behaviour
     },

cuda/private/toolchain_configs/nvcc.bzl

@@ -423,12 +423,13 @@ def _impl(ctx):
     )]
 
 cuda_toolchain_config = rule(
+    doc = """This rule provides the predefined cuda toolchain configuration for NVCC with non MSVC as host compiler.""",
     implementation = _impl,
     attrs = {
-        "cuda_toolkit": attr.label(mandatory = True, providers = [CudaToolkitInfo]),
+        "cuda_toolkit": attr.label(mandatory = True, providers = [CudaToolkitInfo], doc = "A target that provides a `CudaToolkitInfo`."),
         "toolchain_identifier": attr.string(values = ["nvcc"], mandatory = True),
-        "nvcc_version_major": attr.int(),
-        "nvcc_version_minor": attr.int(),
+        "nvcc_version_major": attr.int(doc="The CUDA Toolkit major version, e.g, 11 for 11.6"),
+        "nvcc_version_minor": attr.int(doc="The CUDA Toolkit minor version, e.g, 6 for 11.6"),
         "_cc_toolchain": attr.label(default = "@bazel_tools//tools/cpp:current_cc_toolchain"),  # legacy behaviour
     },
     provides = [CudaToolchainConfigInfo],

cuda/private/toolchain_configs/nvcc_msvc.bzl

@@ -512,13 +512,14 @@ def _impl(ctx):
     )]
 
 cuda_toolchain_config = rule(
+    doc = """This rule provides the predefined cuda toolchain configuration for NVCC with MSVC as host compiler.""",
     implementation = _impl,
     attrs = {
-        "cuda_toolkit": attr.label(mandatory = True, providers = [CudaToolkitInfo]),
+        "cuda_toolkit": attr.label(mandatory = True, providers = [CudaToolkitInfo], doc = "A target that provides a `CudaToolkitInfo`."),
         "toolchain_identifier": attr.string(values = ["nvcc"], mandatory = True),
-        "nvcc_version_major": attr.int(),
-        "nvcc_version_minor": attr.int(),
-        "msvc_env_tmp": attr.string(),
+        "nvcc_version_major": attr.int(doc="The CUDA Toolkit major version, e.g, 11 for 11.6"),
+        "nvcc_version_minor": attr.int(doc="The CUDA Toolkit minor version, e.g, 6 for 11.6"),
+        "msvc_env_tmp": attr.string(doc="The TEMP directory."),
         "_cc_toolchain": attr.label(default = "@bazel_tools//tools/cpp:current_cc_toolchain"),  # legacy behaviour
     },
     provides = [CudaToolchainConfigInfo],

docs/.bazelversion

@@ -0,0 +1 @@
+../.bazelversion

docs/BUILD.bazel

@@ -0,0 +1,22 @@
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+
+stardoc(
+    name = "user_docs",
+    out = "user_docs.md",
+    input = "user_docs.bzl",
+    deps = ["@rules_cuda//:bzl_srcs"],
+)
+
+stardoc(
+    name = "toolchain_config_docs",
+    out = "toolchain_config_docs.md",
+    input = "toolchain_config_docs.bzl",
+    deps = ["@rules_cuda//:bzl_srcs"],
+)
+
+stardoc(
+    name = "providers_docs",
+    out = "providers_docs.md",
+    input = "providers_docs.bzl",
+    deps = ["@rules_cuda//:bzl_srcs"],
+)

docs/WORKSPACE.bazel

@@ -0,0 +1,25 @@
+workspace(name = "rules_cuda_docs")
+
+local_repository(
+    name = "rules_cuda",
+    path = "..",
+)
+
+load("@rules_cuda//cuda:deps.bzl", "rules_cuda_deps")
+
+rules_cuda_deps()
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "io_bazel_stardoc",
+    sha256 = "05fb57bb4ad68a360470420a3b6f5317e4f722839abc5b17ec4ef8ed465aaa47",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.2/stardoc-0.5.2.tar.gz",
+        "https://github.com/bazelbuild/stardoc/releases/download/0.5.2/stardoc-0.5.2.tar.gz",
+    ],
+)
+
+load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
+
+stardoc_repositories()

docs/providers_docs.bzl

@@ -0,0 +1,17 @@
+load(
+    "@rules_cuda//cuda/private:providers.bzl",
+    _ArchSpecInfo = "ArchSpecInfo",
+    _CudaArchsInfo = "CudaArchsInfo",
+    _CudaInfo = "CudaInfo",
+    _CudaToolchainConfigInfo = "CudaToolchainConfigInfo",
+    _CudaToolkitInfo = "CudaToolkitInfo",
+    _Stage2ArchInfo = "Stage2ArchInfo",
+)
+
+ArchSpecInfo = _ArchSpecInfo
+Stage2ArchInfo = _Stage2ArchInfo
+
+CudaArchsInfo = _CudaArchsInfo
+CudaInfo = _CudaInfo
+CudaToolkitInfo = _CudaToolkitInfo
+CudaToolchainConfigInfo = _CudaToolchainConfigInfo