Fix packaging rules documentation generation (#251)
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 #255), and regenerates the rendered docs.
diff --git a/docs/pip.md b/docs/pip.md
index 312fc08..70fcd91 100755
--- 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 @@
<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
index 68e68b4..e7c35c1 100755
--- 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 @@
<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
index cc69425..b926de3 100644
--- a/python/pip.bzl
+++ b/python/pip.bzl
@@ -44,6 +44,7 @@
"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 @@
),
},
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 <code>BUILD</code>
-file with:
-<pre><code>load("@foo//:requirements.bzl", "requirement")
+You can then reference imported dependencies from your `BUILD` file with:
+
+```python
+load("@foo//:requirements.bzl", "requirement")
py_library(
name = "bar",
...
@@ -77,10 +80,11 @@
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",
...
@@ -88,10 +92,7 @@
":foo",
] + all_requirements,
)
-</code></pre>
-
-Args:
- requirements: The label of a requirements.txt file.
+```
""",
)
diff --git a/python/whl.bzl b/python/whl.bzl
index 174352a..1dfa9be 100644
--- a/python/whl.bzl
+++ b/python/whl.bzl
@@ -37,11 +37,21 @@
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 @@
),
},
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.
""",
)
