Fix packaging rules documentation generation (bazel-contrib#251)

brandjon · web-flow · commit 13bf8b7769c5 · 2019-11-11T10:50:37.000-05:00
For some reason the rendered docs for the packaging rules' weren't up-to-date. The docstrings also used an outdated format. This change moves docstrings into `doc=` notation where applicable, switches to markdown syntax where possible (but see bazel-contrib#255), and regenerates the rendered docs.
diff --git a/docs/pip.md b/docs/pip.md
@@ -8,6 +8,46 @@
 pip_import(<a href="#pip_import-name">name</a>, <a href="#pip_import-requirements">requirements</a>)
 </pre>
 
+A rule for importing `requirements.txt` dependencies into Bazel.
+
+This rule imports a `requirements.txt` file and generates a new
+`requirements.bzl` file.  This is used via the `WORKSPACE` pattern:
+
+```python
+pip_import(
+    name = "foo",
+    requirements = ":requirements.txt",
+)
+load("@foo//:requirements.bzl", "pip_install")
+pip_install()
+```
+
+You can then reference imported dependencies from your `BUILD` file with:
+
+```python
+load("@foo//:requirements.bzl", "requirement")
+py_library(
+    name = "bar",
+    ...
+    deps = [
+       "//my/other:dep",
+       requirement("futures"),
+       requirement("mock"),
+    ],
+)
+```
+
+Or alternatively:
+```python
+load("@foo//:requirements.bzl", "all_requirements")
+py_binary(
+    name = "baz",
+    ...
+    deps = [
+       ":foo",
+    ] + all_requirements,
+)
+```
 
 
 ### Attributes
@@ -31,6 +71,9 @@ pip_import(<a href="#pip_import-name">name</a>, <a href="#pip_import-requirement
       <td><code>requirements</code></td>
       <td>
         <a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; required
+        <p>
+          The label of the requirements.txt file.
+        </p>
       </td>
     </tr>
   </tbody>
diff --git a/docs/whl.md b/docs/whl.md
@@ -8,6 +8,22 @@
 whl_library(<a href="#whl_library-name">name</a>, <a href="#whl_library-extras">extras</a>, <a href="#whl_library-requirements">requirements</a>, <a href="#whl_library-whl">whl</a>)
 </pre>
 
+A rule for importing `.whl` dependencies into Bazel.
+
+<b>This rule is currently used to implement `pip_import`. It is not intended to
+work standalone, and the interface may change.</b> See `pip_import` for proper
+usage.
+
+This rule imports a `.whl` file as a `py_library`:
+```python
+whl_library(
+    name = "foo",
+    whl = ":my-whl-file",
+    requirements = "name of pip_import rule",
+)
+```
+
+This rule defines `@foo//:pkg` as a `py_library` target.
 
 
 ### Attributes
@@ -31,18 +47,30 @@ whl_library(<a href="#whl_library-name">name</a>, <a href="#whl_library-extras">
       <td><code>extras</code></td>
       <td>
         List of strings; optional
+        <p>
+          A subset of the "extras" available from this <code>.whl</code> for which
+<code>requirements</code> has the dependencies.
+        </p>
       </td>
     </tr>
     <tr id="whl_library-requirements">
       <td><code>requirements</code></td>
       <td>
         String; optional
+        <p>
+          The name of the <code>pip_import</code> repository rule from which to load this
+<code>.whl</code>'s dependencies.
+        </p>
       </td>
     </tr>
     <tr id="whl_library-whl">
       <td><code>whl</code></td>
       <td>
         <a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; required
+        <p>
+          The path to the <code>.whl</code> file. The name is expected to follow [this
+convention](https://www.python.org/dev/peps/pep-0427/#file-name-convention)).
+        </p>
       </td>
     </tr>
   </tbody>
diff --git a/python/pip.bzl b/python/pip.bzl
@@ -44,6 +44,7 @@ pip_import = repository_rule(
         "requirements": attr.label(
             mandatory = True,
             allow_single_file = True,
+            doc = "The label of the requirements.txt file.",
         ),
         "_script": attr.label(
             executable = True,
@@ -52,22 +53,24 @@ pip_import = repository_rule(
         ),
     },
     implementation = _pip_import_impl,
-    doc = """A rule for importing <code>requirements.txt</code> dependencies into Bazel.
+    doc = """A rule for importing `requirements.txt` dependencies into Bazel.
 
-This rule imports a <code>requirements.txt</code> file and generates a new
-<code>requirements.bzl</code> file.  This is used via the <code>WORKSPACE</code>
-pattern:
-<pre><code>pip_import(
+This rule imports a `requirements.txt` file and generates a new
+`requirements.bzl` file.  This is used via the `WORKSPACE` pattern:
+
+```python
+pip_import(
     name = "foo",
     requirements = ":requirements.txt",
 )
 load("@foo//:requirements.bzl", "pip_install")
 pip_install()
-</code></pre>
+```
+
+You can then reference imported dependencies from your `BUILD` file with:
 
-You can then reference imported dependencies from your <code>BUILD</code>
-file with:
-<pre><code>load("@foo//:requirements.bzl", "requirement")
+```python
+load("@foo//:requirements.bzl", "requirement")
 py_library(
     name = "bar",
     ...
@@ -77,21 +80,19 @@ py_library(
        requirement("mock"),
     ],
 )
-</code></pre>
+```
 
 Or alternatively:
-<pre><code>load("@foo//:requirements.bzl", "all_requirements")
+```python
+load("@foo//:requirements.bzl", "all_requirements")
 py_binary(
     name = "baz",
     ...
     deps = [
        ":foo",
     ] + all_requirements,
 )
-</code></pre>
-
-Args:
-  requirements: The label of a requirements.txt file.
+```
 """,
 )
 
diff --git a/python/whl.bzl b/python/whl.bzl
@@ -37,11 +37,21 @@ def _whl_impl(repository_ctx):
 
 whl_library = repository_rule(
     attrs = {
-        "extras": attr.string_list(),
-        "requirements": attr.string(),
+        "extras": attr.string_list(doc = """
+A subset of the "extras" available from this <code>.whl</code> for which
+<code>requirements</code> has the dependencies.
+"""),
+        "requirements": attr.string(doc = """
+The name of the <code>pip_import</code> repository rule from which to load this
+<code>.whl</code>'s dependencies.
+"""),
         "whl": attr.label(
             mandatory = True,
             allow_single_file = True,
+            doc = """
+The path to the <code>.whl</code> file. The name is expected to follow [this
+convention](https://www.python.org/dev/peps/pep-0427/#file-name-convention)).
+""",
         ),
         "_script": attr.label(
             executable = True,
@@ -50,30 +60,21 @@ whl_library = repository_rule(
         ),
     },
     implementation = _whl_impl,
-    doc = """A rule for importing <code>.whl</code> dependencies into Bazel.
+    doc = """A rule for importing `.whl` dependencies into Bazel.
 
-<b>This rule is currently used to implement <code>pip_import</code>,
-it is not intended to work standalone, and the interface may change.</b>
-See <code>pip_import</code> for proper usage.
+<b>This rule is currently used to implement `pip_import`. It is not intended to
+work standalone, and the interface may change.</b> See `pip_import` for proper
+usage.
 
-This rule imports a <code>.whl</code> file as a <code>py_library</code>:
-<pre><code>whl_library(
+This rule imports a `.whl` file as a `py_library`:
+```python
+whl_library(
     name = "foo",
     whl = ":my-whl-file",
     requirements = "name of pip_import rule",
 )
-</code></pre>
-
-This rule defines a <code>@foo//:pkg</code> <code>py_library</code> target.
-
-Args:
-  whl: The path to the .whl file (the name is expected to follow [this
-    convention](https://www.python.org/dev/peps/pep-0427/#file-name-convention))
-
-  requirements: The name of the pip_import repository rule from which to
-    load this .whl's dependencies.
+```
 
-  extras: A subset of the "extras" available from this <code>.whl</code> for which
-    <code>requirements</code> has the dependencies.
+This rule defines `@foo//:pkg` as a `py_library` target.
 """,
 )
