Rough prototype of @since processing. (#617)

When we merge generated docs into the final form, convert
@since(text) to emphasized (currently italic) text.

This is not intended to be perfect. It is just to get the concept out
there to start playing with it. Ideally, StarDoc will eventually support
@since natively and we can delete this.

3 files changed, 6 insertions, 2 deletions

diff --git a/doc_build/merge.py b/doc_build/merge.py
index d4a7e55..7c518ff 100755
--- a/doc_build/merge.py
+++ b/doc_build/merge.py
@@ -25,6 +25,7 @@ import typing
 
 ID_RE = re.compile(r'<a id="#(.*)">')
 WRAPS_RE = re.compile(r'@wraps\((.*)\)')
+SINCE_RE = re.compile(r'@since\((.*)\)')
 CENTER_RE = re.compile(r'<p align="center">([^<]*)</p>')
 
 
@@ -52,6 +53,8 @@ def merge_text(text: str, out) -> None:
     out: an output file stream.
   """
   for line in text.split('\n'):
+    line = SINCE_RE.sub(r'<div class="since"><i>Since \1</i></div>', line)
+
     if line.startswith('| :'):
       line = fix_stardoc_table_align(line)
     # Compensate for https://github.com/bazelbuild/stardoc/issues/118.
diff --git a/docs/latest.md b/docs/latest.md
index bc67345..4ad0b75 100755
--- a/docs/latest.md
+++ b/docs/latest.md
@@ -1,4 +1,4 @@
-# rules_pkg - 0.7.0
+# rules_pkg - 0.7.1
 
 <div class="toc">
   <h2>Common Attributes</h2>
@@ -292,7 +292,7 @@ pkg_tar(<a href="#pkg_tar-name">name</a>, <a href="#pkg_tar-build_tar">build_tar
 | <a id="pkg_tar-private_stamp_detect"></a>private_stamp_detect |  -   | Boolean | optional | False |
 | <a id="pkg_tar-remap_paths"></a>remap_paths |  -   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
 | <a id="pkg_tar-srcs"></a>srcs |  -   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="pkg_tar-stamp"></a>stamp |  Enable file time stamping.  Possible values: <li>stamp = 1: Use the time of the build as the modification time of each file in the archive. <li>stamp = 0: Use an "epoch" time for the modification time of each file. This gives good build result caching. <li>stamp = -1: Control the chosen modification time using the --[no]stamp flag.   | Integer | optional | 0 |
+| <a id="pkg_tar-stamp"></a>stamp |  Enable file time stamping.  Possible values: <li>stamp = 1: Use the time of the build as the modification time of each file in the archive. <li>stamp = 0: Use an "epoch" time for the modification time of each file. This gives good build result caching. <li>stamp = -1: Control the chosen modification time using the --[no]stamp flag. <div class="since"><i>Since 0.5.0</i></div>   | Integer | optional | 0 |
 | <a id="pkg_tar-strip_prefix"></a>strip_prefix |  -   | String | optional | "" |
 | <a id="pkg_tar-symlinks"></a>symlinks |  -   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
 
diff --git a/pkg/private/tar/tar.bzl b/pkg/private/tar/tar.bzl
index 6360cad..6fa3e04 100644
--- a/pkg/private/tar/tar.bzl
+++ b/pkg/private/tar/tar.bzl
@@ -273,6 +273,7 @@ pkg_tar_impl = rule(
 <li>stamp = 1: Use the time of the build as the modification time of each file in the archive.
 <li>stamp = 0: Use an "epoch" time for the modification time of each file. This gives good build result caching.
 <li>stamp = -1: Control the chosen modification time using the --[no]stamp flag.
+@since(0.5.0)
 """,
             default = 0,
         ),