feat: add documentation

.bazelignore

@@ -4,3 +4,4 @@
 .gitignore
 docs
 external
+test

BUILD.bazel

@@ -1,40 +1,15 @@
-load("@stardoc//stardoc:stardoc.bzl", "stardoc")
-load("@bzlws//:index.bzl", "bzlws_copy")
-load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("//rules:bzlws_copy.bzl", "bzlws_copy")
 
 package(default_visibility = ["//visibility:public"])
 
-exports_files(["index.bzl", "repo.bzl"])
-
-stardoc(
-    name = "docs",
-    tags = ["manual"],
-    input = "index.bzl",
-    out = "index.md",
-    deps = [":rules_cc"],
-)
-
-# SEE: https://github.com/bazelbuild/stardoc/issues/92
-bzl_library(
-    name = "rules_cc",
-    tags = ["manual"],
-    srcs = [
-        "@rules_cc//cc:action_names.bzl",
-        "@rules_cc//cc:defs.bzl",
-        "@rules_cc//cc:find_cc_toolchain.bzl",
-        "@rules_cc//cc/private/rules_impl:cc_flags_supplier.bzl",
-        "@rules_cc//cc/private/rules_impl:cc_flags_supplier_lib.bzl",
-        "@rules_cc//cc/private/rules_impl:compiler_flag.bzl",
-    ],
-    visibility = ["//visibility:public"],
-)
-
 bzlws_copy(
-    name = "docs_copy",
+    name = "update_docs",
     out = "docs/{FILENAME}",
     tags = ["manual"],
     force = True,
     srcs = [
-        ":docs",
+        "//rules:bzlws_copy_doc",
+        "//rules:bzlws_link_doc",
+        "//rules:bzlws_extract_doc",
     ],
 )

MODULE.bazel

@@ -8,7 +8,7 @@ bazel_dep(name = "bazel_skylib", version = "1.6.1")
 bazel_dep(name = "rules_cc", version = "0.0.9")
 bazel_dep(name = "yaml-cpp", version = "0.8.0")
 
-bazel_dep(name = "stardoc", version = "0.6.2", dev_dependency = True)
+bazel_dep(name = "stardoc", version = "0.7.0", dev_dependency = True)
 bazel_dep(name = "toolchains_llvm", version = "1.0.0", dev_dependency = True)
 bazel_dep(name = "hedron_compile_commands", dev_dependency = True)
 git_override(

WORKSPACE.bazel

@@ -1,4 +1 @@
-load("//:faux_repo.bzl", "faux_repo")
-
-faux_repo(name = "faux_repo")
 

docs/bzlws_copy.md

@@ -0,0 +1,40 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+
+<a id="bzlws_copy"></a>
+
+## bzlws_copy
+
+<pre>
+load("@bzlws//rules:bzlws_copy.bzl", "bzlws_copy")
+
+bzlws_copy(<a href="#bzlws_copy-name">name</a>, <a href="#bzlws_copy-srcs">srcs</a>, <a href="#bzlws_copy-out">out</a>, <a href="#bzlws_copy-force">force</a>, <a href="#bzlws_copy-strip_filepath_prefix">strip_filepath_prefix</a>, <a href="#bzlws_copy-metafile_path">metafile_path</a>, <a href="#bzlws_copy-substitutions">substitutions</a>,
+           <a href="#bzlws_copy-stamp_substitutions">stamp_substitutions</a>, <a href="#bzlws_copy-visibility">visibility</a>, <a href="#bzlws_copy-tags">tags</a>, <a href="#bzlws_copy-kwargs">kwargs</a>)
+</pre>
+
+Copy generated files into workspace directory
+
+```python
+load("@bzlws//rules:bzlws_copy.bzl", "bzlws_copy")
+```
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="bzlws_copy-name"></a>name |  Name used for executable target   |  `None` |
+| <a id="bzlws_copy-srcs"></a>srcs |  List of files that should be copied   |  `None` |
+| <a id="bzlws_copy-out"></a>out |  Output path within the workspace. Certain strings get replaced with workspace status values and information about the `srcs`. This happens in 2 phases.<br><br>**Phase 1:**<br><br>The [workspace status](https://docs.bazel.build/versions/master/user-manual.html#workspace_status) stamp values get replaced in this format: `{KEY}`. For example if you would like to have the name of the host machine in your output path you would put `out = "my/path/{BUILD_HOST}/{FILENAME}"`<br><br>**Phase 2:**<br><br>The following gets replaced about each items in `srcs`<br><br>`{BAZEL_LABEL_NAME}` - Label name<br><br>`{BAZEL_LABEL_PACKAGE}` - Label package<br><br>`{BAZEL_LABEL_WORKSPACE_NAME}`  - Workspace name of the label<br><br>`{BAZEL_FULL_LABEL}` - Fulll label string<br><br>`{BAZEL_LABEL}` - Full label without the workspace name<br><br>`{EXT}` - File extension (with the dot)<br><br>`{EXTNAME}` - File extension name (without the dot)<br><br>`{FILENAME}` - File name with extension<br><br>`{FILEPATH}` - File path. https://bazel.build/rules/lib/File#path<br><br>`{BASENAME}` - Path basename   |  `None` |
+| <a id="bzlws_copy-force"></a>force |  Overwrite existing paths even if they are not files   |  `None` |
+| <a id="bzlws_copy-strip_filepath_prefix"></a>strip_filepath_prefix |  Strip prefix of `{FILEPATH}`   |  `""` |
+| <a id="bzlws_copy-metafile_path"></a>metafile_path |  Path to metafile   |  `""` |
+| <a id="bzlws_copy-substitutions"></a>substitutions |  BzlwsInfo label keyed, string valued, dictionary. The values will be replaced in the source files with the values from the `bazel info` command. The available BzlwsInfo targets are in the `@bzlws//info` package.   |  `{}` |
+| <a id="bzlws_copy-stamp_substitutions"></a>stamp_substitutions |  Workspace status keyed, string valued, dictionary. The values will be replaced in the sources files the values from the workspace status matching the key.   |  `{}` |
+| <a id="bzlws_copy-visibility"></a>visibility |  visibility of the executable target   |  `None` |
+| <a id="bzlws_copy-tags"></a>tags |  forwarded to underlying targets   |  `[]` |
+| <a id="bzlws_copy-kwargs"></a>kwargs |  rest of arguments get passed to underlying targets   |  none |
+
+

docs/bzlws_extract.md

@@ -0,0 +1,31 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+
+<a id="bzlws_extract"></a>
+
+## bzlws_extract
+
+<pre>
+load("@bzlws//rules:bzlws_extract.bzl", "bzlws_extract")
+
+bzlws_extract(<a href="#bzlws_extract-name">name</a>, <a href="#bzlws_extract-srcs">srcs</a>, <a href="#bzlws_extract-out">out</a>, <a href="#bzlws_extract-force">force</a>, <a href="#bzlws_extract-strip_filepath_prefix">strip_filepath_prefix</a>, <a href="#bzlws_extract-metafile_path">metafile_path</a>, <a href="#bzlws_extract-visibility">visibility</a>, <a href="#bzlws_extract-kwargs">kwargs</a>)
+</pre>
+
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="bzlws_extract-name"></a>name |  <p align="center"> - </p>   |  `None` |
+| <a id="bzlws_extract-srcs"></a>srcs |  <p align="center"> - </p>   |  `None` |
+| <a id="bzlws_extract-out"></a>out |  <p align="center"> - </p>   |  `None` |
+| <a id="bzlws_extract-force"></a>force |  <p align="center"> - </p>   |  `None` |
+| <a id="bzlws_extract-strip_filepath_prefix"></a>strip_filepath_prefix |  <p align="center"> - </p>   |  `""` |
+| <a id="bzlws_extract-metafile_path"></a>metafile_path |  <p align="center"> - </p>   |  `""` |
+| <a id="bzlws_extract-visibility"></a>visibility |  <p align="center"> - </p>   |  `None` |
+| <a id="bzlws_extract-kwargs"></a>kwargs |  <p align="center"> - </p>   |  none |
+
+

docs/bzlws_link.md

@@ -0,0 +1,36 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+
+<a id="bzlws_link"></a>
+
+## bzlws_link
+
+<pre>
+load("@bzlws//rules:bzlws_link.bzl", "bzlws_link")
+
+bzlws_link(<a href="#bzlws_link-name">name</a>, <a href="#bzlws_link-srcs">srcs</a>, <a href="#bzlws_link-out">out</a>, <a href="#bzlws_link-force">force</a>, <a href="#bzlws_link-strip_filepath_prefix">strip_filepath_prefix</a>, <a href="#bzlws_link-metafile_path">metafile_path</a>, <a href="#bzlws_link-visibility">visibility</a>, <a href="#bzlws_link-kwargs">kwargs</a>)
+</pre>
+
+Symlink generated files into workspace directory
+
+```python
+load("@bzlws//:index.bzl", "bzlws_link")
+```
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="bzlws_link-name"></a>name |  Name used for executable target   |  `None` |
+| <a id="bzlws_link-srcs"></a>srcs |  List of files that should be symlinked   |  `None` |
+| <a id="bzlws_link-out"></a>out |  Output path within the workspace. Certain strings get replaced with workspace status values and information about the `srcs`. This happens in 2 phases.<br><br>**Phase 1:**<br><br>The [workspace status](https://docs.bazel.build/versions/master/user-manual.html#workspace_status) stamp values get replaced in this format: `{KEY}`. For example if you would like to have the name of the host machine in your output path you would put `out = "my/path/{BUILD_HOST}/{FILENAME}"`<br><br>**Phase 2:**<br><br>The following gets replaced about each items in `srcs`<br><br>`{BAZEL_LABEL_NAME}` - Label name<br><br>`{BAZEL_LABEL_PACKAGE}` - Label package<br><br>`{BAZEL_LABEL_WORKSPACE_NAME}`  - Workspace name of the label<br><br>`{BAZEL_FULL_LABEL}` - Fulll label string<br><br>`{BAZEL_LABEL}` - Full label without the workspace name<br><br>`{EXT}` - File extension (with the dot)<br><br>`{EXTNAME}` - File extension name (without the dot)<br><br>`{FILENAME}` - File name with extension<br><br>`{FILEPATH}` - File path. https://bazel.build/rules/lib/File#path<br><br>`{BASENAME}` - Path basename   |  `None` |
+| <a id="bzlws_link-force"></a>force |  Overwrite existing paths even if they are not symlinks   |  `None` |
+| <a id="bzlws_link-strip_filepath_prefix"></a>strip_filepath_prefix |  Strip prefix of `{FILEPATH}`   |  `""` |
+| <a id="bzlws_link-metafile_path"></a>metafile_path |  Path to metafile   |  `""` |
+| <a id="bzlws_link-visibility"></a>visibility |  visibility of the executable target   |  `None` |
+| <a id="bzlws_link-kwargs"></a>kwargs |  rest of arguments get passed to underlying targets   |  none |
+
+

rules/BUILD.bazel

@@ -0,0 +1,68 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
+
+bzl_library(
+    name = "bzlws_copy",
+    visibility = ["//visibility:public"],
+    srcs = [
+        "bzlws_copy.bzl",
+    ],
+    deps = [
+        "//rules/private:bzlws_info",
+        "//rules/private:bzlws_util",
+        "//rules/private:bzlws_tool_cc_binary",
+    ],
+)
+
+stardoc(
+    name = "bzlws_copy_doc",
+    visibility = ["//:__pkg__"],
+    input = "bzlws_copy.bzl",
+    out = "bzlws_copy.md",
+    symbol_names = ["bzlws_copy"],
+    deps = [":bzlws_copy"],
+)
+
+bzl_library(
+    name = "bzlws_link",
+    visibility = ["//visibility:public"],
+    srcs = [
+        "bzlws_link.bzl",
+    ],
+    deps = [
+        "//rules/private:bzlws_info",
+        "//rules/private:bzlws_util",
+        "//rules/private:bzlws_tool_cc_binary",
+    ],
+)
+
+stardoc(
+    name = "bzlws_link_doc",
+    visibility = ["//:__pkg__"],
+    input = "bzlws_link.bzl",
+    out = "bzlws_link.md",
+    symbol_names = ["bzlws_link"],
+    deps = [":bzlws_link"],
+)
+
+bzl_library(
+    name = "bzlws_extract",
+    visibility = ["//visibility:public"],
+    srcs = [
+        "bzlws_extract.bzl",
+    ],
+    deps = [
+        "//rules/private:bzlws_info",
+        "//rules/private:bzlws_util",
+        "//rules/private:bzlws_tool_cc_binary",
+    ],
+)
+
+stardoc(
+    name = "bzlws_extract_doc",
+    visibility = ["//:__pkg__"],
+    input = "bzlws_extract.bzl",
+    out = "bzlws_extract.md",
+    symbol_names = ["bzlws_extract"],
+    deps = [":bzlws_extract"],
+)

rules/bzlws_copy.bzl

@@ -1,12 +1,11 @@
-load("@rules_cc//cc:defs.bzl", "cc_binary")
 load("//rules/private:bzlws_tool_cc_binary.bzl", "bzlws_tool_cc_binary")
 load("//rules/private:bzlws_util.bzl", "bzlws_check_common_required_attrs")
 
 def bzlws_copy(name = None, srcs = None, out = None, force = None, strip_filepath_prefix = "", metafile_path = "", substitutions = {}, stamp_substitutions = {}, visibility = None, tags = [], **kwargs):
     """Copy generated files into workspace directory
 
     ```python
-    load("@bzlws//:index.bzl", "bzlws_copy")
+    load("@bzlws//rules:bzlws_copy.bzl", "bzlws_copy")
     ```
 
     Args:
@@ -73,17 +72,17 @@ def bzlws_copy(name = None, srcs = None, out = None, force = None, strip_filepat
     bzlws_check_common_required_attrs("bzlws_copy", name, srcs, out)
 
     bzlws_tool_cc_binary(
-         name = name,
-         srcs = srcs,
-         out = out,
-         strip_filepath_prefix = strip_filepath_prefix,
-         force = force,
-         metafile_path = metafile_path,
-         substitutions = substitutions,
-         stamp_substitutions = stamp_substitutions,
-         tool = "bzlws_copy",
-         deps = ["@bzlws//tools/bzlws_copy"],
-         visibility = ["//visibility:private"],
-         tags = tags + ["ibazel_notify_changes"],
-         **kwargs
+        name = name,
+        srcs = srcs,
+        out = out,
+        strip_filepath_prefix = strip_filepath_prefix,
+        force = force,
+        metafile_path = metafile_path,
+        substitutions = substitutions,
+        stamp_substitutions = stamp_substitutions,
+        tool = "bzlws_copy",
+        deps = ["@bzlws//tools/bzlws_copy"],
+        visibility = ["//visibility:private"],
+        tags = tags + ["ibazel_notify_changes"],
+        **kwargs
     )

rules/bzlws_extract.bzl

@@ -1,12 +1,11 @@
-load("@rules_cc//cc:defs.bzl", "cc_binary")
 load("//rules/private:bzlws_tool_cc_binary.bzl", "bzlws_tool_cc_binary")
 load("//rules/private:bzlws_util.bzl", "bzlws_check_common_required_attrs")
 
 def bzlws_extract(name = None, srcs = None, out = None, force = None, strip_filepath_prefix = "", metafile_path = "", visibility = None, **kwargs):
     bzlws_check_common_required_attrs("bzlws_extract", name, srcs, out)
 
     bzlws_tool_cc_binary(
-        name = sh_script_name,
+        name = name,
         srcs = srcs,
         out = out,
         strip_filepath_prefix = strip_filepath_prefix,

rules/bzlws_link.bzl

@@ -1,4 +1,3 @@
-load("@rules_cc//cc:defs.bzl", "cc_binary")
 load("//rules/private:bzlws_tool_cc_binary.bzl", "bzlws_tool_cc_binary")
 load("//rules/private:bzlws_util.bzl", "bzlws_check_common_required_attrs")