feat: add write_source_file to public API (#295)

docs/write_source_files.md

@@ -2,6 +2,41 @@
 
 Public API for write_source_files
 
+<a id="write_source_file"></a>
+
+## write_source_file
+
+<pre>
+write_source_file(<a href="#write_source_file-name">name</a>, <a href="#write_source_file-in_file">in_file</a>, <a href="#write_source_file-out_file">out_file</a>, <a href="#write_source_file-executable">executable</a>, <a href="#write_source_file-additional_update_targets">additional_update_targets</a>,
+                  <a href="#write_source_file-suggested_update_target">suggested_update_target</a>, <a href="#write_source_file-diff_test">diff_test</a>, <a href="#write_source_file-kwargs">kwargs</a>)
+</pre>
+
+Write a file or directory to the source tree.
+
+By default, `diff_test` targets are generated that ensure the source tree file or directory to be written to
+is up to date and the rule also checks that the source tree file or directory to be written to exists.
+To disable the exists check and up-to-date test set `diff_test` to `False`.
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="write_source_file-name"></a>name |  Name of the runnable target that creates or updates the source tree file or directory.   |  none |
+| <a id="write_source_file-in_file"></a>in_file |  File or directory to use as the desired content to write to <code>out_file</code>.<br><br>This is typically a file or directory output of another target. If <code>in_file</code> is a directory then entire directory contents are copied.   |  <code>None</code> |
+| <a id="write_source_file-out_file"></a>out_file |  The file or directory to write to in the source tree. Must be within the same bazel package as the target.   |  <code>None</code> |
+| <a id="write_source_file-executable"></a>executable |  Whether source tree file or files within the source tree directory written should be made executable.   |  <code>False</code> |
+| <a id="write_source_file-additional_update_targets"></a>additional_update_targets |  List of other <code>write_source_files</code> or <code>write_source_file</code> targets to call in the same run.   |  <code>[]</code> |
+| <a id="write_source_file-suggested_update_target"></a>suggested_update_target |  Label of the <code>write_source_files</code> or <code>write_source_file</code> target to suggest running when files are out of date.   |  <code>None</code> |
+| <a id="write_source_file-diff_test"></a>diff_test |  Test that the source tree file or directory exist and is up to date.   |  <code>True</code> |
+| <a id="write_source_file-kwargs"></a>kwargs |  Other common named parameters such as <code>tags</code> or <code>visibility</code>   |  none |
+
+**RETURNS**
+
+Name of the generated test target if requested, otherwise None.
+
+
 <a id="write_source_files"></a>
 
 ## write_source_files
@@ -103,8 +138,8 @@ NOTE: If you run formatters or linters on your codebase, it is advised that you
 | <a id="write_source_files-name"></a>name |  Name of the runnable target that creates or updates the source tree files and/or directories.   |  none |
 | <a id="write_source_files-files"></a>files |  A dict where the keys are files or directories in the source tree to write to and the values are labels pointing to the desired content, typically file or directory outputs of other targets.<br><br>Source tree files and directories must be within the same bazel package as the target.   |  <code>{}</code> |
 | <a id="write_source_files-executable"></a>executable |  Whether source tree files written should be made executable.<br><br>This applies to all source tree files written by this target. This attribute is not propagated to <code>additional_update_targets</code>.<br><br>To set different executable permissions on different source tree files use multiple <code>write_source_files</code> targets.   |  <code>False</code> |
-| <a id="write_source_files-additional_update_targets"></a>additional_update_targets |  List of other <code>write_source_files</code> or other executable updater targets to call in the same run.   |  <code>[]</code> |
-| <a id="write_source_files-suggested_update_target"></a>suggested_update_target |  Label of the <code>write_source_files</code> target to suggest running when files are out of date.   |  <code>None</code> |
+| <a id="write_source_files-additional_update_targets"></a>additional_update_targets |  List of other <code>write_source_files</code> or <code>write_source_file</code> targets to call in the same run.   |  <code>[]</code> |
+| <a id="write_source_files-suggested_update_target"></a>suggested_update_target |  Label of the <code>write_source_files</code> or <code>write_source_file</code> target to suggest running when files are out of date.   |  <code>None</code> |
 | <a id="write_source_files-diff_test"></a>diff_test |  Test that the source tree files and/or directories exist and are up to date.   |  <code>True</code> |
 | <a id="write_source_files-kwargs"></a>kwargs |  Other common named parameters such as <code>tags</code> or <code>visibility</code>   |  none |
 

lib/private/write_source_file.bzl

@@ -38,7 +38,7 @@ def write_source_file(
 
         executable: Whether source tree file or files within the source tree directory written should be made executable.
 
-        additional_update_targets: List of other `write_source_files`, write_source_file` or other executable updater targets to call in the same run.
+        additional_update_targets: List of other `write_source_files` or `write_source_file` targets to call in the same run.
 
         suggested_update_target: Label of the `write_source_files` or `write_source_file` target to suggest running when files are out of date.
 

lib/write_source_files.bzl

@@ -5,9 +5,6 @@ load(
     _write_source_file = "write_source_file",
 )
 
-# TODO: Make write_source_file part of the public API
-# write_source_file = _write_source_file
-
 def write_source_files(
         name,
         files = {},
@@ -113,9 +110,9 @@ def write_source_files(
 
             To set different executable permissions on different source tree files use multiple `write_source_files` targets.
 
-        additional_update_targets: List of other `write_source_files` or other executable updater targets to call in the same run.
+        additional_update_targets: List of other `write_source_files` or `write_source_file` targets to call in the same run.
 
-        suggested_update_target: Label of the `write_source_files` target to suggest running when files are out of date.
+        suggested_update_target: Label of the `write_source_files` or `write_source_file` target to suggest running when files are out of date.
 
         diff_test: Test that the source tree files and/or directories exist and are up to date.
 
@@ -168,3 +165,5 @@ def write_source_files(
             diff_test = False,
             **kwargs
         )
+
+write_source_file = _write_source_file