Skip to content

Navigation Menu

Sign in

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 13bf8b7

Browse filesBrowse files
brandjonbrandjon
authored
Fix packaging rules documentation generation (bazel-contrib#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 bazel-contrib#255), and regenerates the rendered docs.
1 parent a610ace commit 13bf8b7
Copy full SHA for 13bf8b7

File tree

4 files changed

+108
-35
lines changed
Filter options

4 files changed

+108
-35
lines changed

‎docs/pip.md

Copy file name to clipboardExpand all lines: docs/pip.md
+43Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,46 @@
88
pip_import(<a href="#pip_import-name">name</a>, <a href="#pip_import-requirements">requirements</a>)
99
</pre>
1010

11+
A rule for importing `requirements.txt` dependencies into Bazel.
12+
13+
This rule imports a `requirements.txt` file and generates a new
14+
`requirements.bzl` file. This is used via the `WORKSPACE` pattern:
15+
16+
```python
17+
pip_import(
18+
name = "foo",
19+
requirements = ":requirements.txt",
20+
)
21+
load("@foo//:requirements.bzl", "pip_install")
22+
pip_install()
23+
```
24+
25+
You can then reference imported dependencies from your `BUILD` file with:
26+
27+
```python
28+
load("@foo//:requirements.bzl", "requirement")
29+
py_library(
30+
name = "bar",
31+
...
32+
deps = [
33+
"//my/other:dep",
34+
requirement("futures"),
35+
requirement("mock"),
36+
],
37+
)
38+
```
39+
40+
Or alternatively:
41+
```python
42+
load("@foo//:requirements.bzl", "all_requirements")
43+
py_binary(
44+
name = "baz",
45+
...
46+
deps = [
47+
":foo",
48+
] + all_requirements,
49+
)
50+
```
1151

1252

1353
### Attributes
@@ -31,6 +71,9 @@ pip_import(<a href="#pip_import-name">name</a>, <a href="#pip_import-requirement
3171
<td><code>requirements</code></td>
3272
<td>
3373
<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; required
74+
<p>
75+
The label of the requirements.txt file.
76+
</p>
3477
</td>
3578
</tr>
3679
</tbody>

‎docs/whl.md

Copy file name to clipboardExpand all lines: docs/whl.md
+28Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,22 @@
88
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>)
99
</pre>
1010

11+
A rule for importing `.whl` dependencies into Bazel.
12+
13+
<b>This rule is currently used to implement `pip_import`. It is not intended to
14+
work standalone, and the interface may change.</b> See `pip_import` for proper
15+
usage.
16+
17+
This rule imports a `.whl` file as a `py_library`:
18+
```python
19+
whl_library(
20+
name = "foo",
21+
whl = ":my-whl-file",
22+
requirements = "name of pip_import rule",
23+
)
24+
```
25+
26+
This rule defines `@foo//:pkg` as a `py_library` target.
1127

1228

1329
### Attributes
@@ -31,18 +47,30 @@ whl_library(<a href="#whl_library-name">name</a>, <a href="#whl_library-extras">
3147
<td><code>extras</code></td>
3248
<td>
3349
List of strings; optional
50+
<p>
51+
A subset of the "extras" available from this <code>.whl</code> for which
52+
<code>requirements</code> has the dependencies.
53+
</p>
3454
</td>
3555
</tr>
3656
<tr id="whl_library-requirements">
3757
<td><code>requirements</code></td>
3858
<td>
3959
String; optional
60+
<p>
61+
The name of the <code>pip_import</code> repository rule from which to load this
62+
<code>.whl</code>'s dependencies.
63+
</p>
4064
</td>
4165
</tr>
4266
<tr id="whl_library-whl">
4367
<td><code>whl</code></td>
4468
<td>
4569
<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; required
70+
<p>
71+
The path to the <code>.whl</code> file. The name is expected to follow [this
72+
convention](https://www.python.org/dev/peps/pep-0427/#file-name-convention)).
73+
</p>
4674
</td>
4775
</tr>
4876
</tbody>

‎python/pip.bzl

Copy file name to clipboardExpand all lines: python/pip.bzl
+16-15Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ pip_import = repository_rule(
4444
"requirements": attr.label(
4545
mandatory = True,
4646
allow_single_file = True,
47+
doc = "The label of the requirements.txt file.",
4748
),
4849
"_script": attr.label(
4950
executable = True,
@@ -52,22 +53,24 @@ pip_import = repository_rule(
5253
),
5354
},
5455
implementation = _pip_import_impl,
55-
doc = """A rule for importing <code>requirements.txt</code> dependencies into Bazel.
56+
doc = """A rule for importing `requirements.txt` dependencies into Bazel.
5657
57-
This rule imports a <code>requirements.txt</code> file and generates a new
58-
<code>requirements.bzl</code> file. This is used via the <code>WORKSPACE</code>
59-
pattern:
60-
<pre><code>pip_import(
58+
This rule imports a `requirements.txt` file and generates a new
59+
`requirements.bzl` file. This is used via the `WORKSPACE` pattern:
60+
61+
```python
62+
pip_import(
6163
name = "foo",
6264
requirements = ":requirements.txt",
6365
)
6466
load("@foo//:requirements.bzl", "pip_install")
6567
pip_install()
66-
</code></pre>
68+
```
69+
70+
You can then reference imported dependencies from your `BUILD` file with:
6771
68-
You can then reference imported dependencies from your <code>BUILD</code>
69-
file with:
70-
<pre><code>load("@foo//:requirements.bzl", "requirement")
72+
```python
73+
load("@foo//:requirements.bzl", "requirement")
7174
py_library(
7275
name = "bar",
7376
...
@@ -77,21 +80,19 @@ py_library(
7780
requirement("mock"),
7881
],
7982
)
80-
</code></pre>
83+
```
8184
8285
Or alternatively:
83-
<pre><code>load("@foo//:requirements.bzl", "all_requirements")
86+
```python
87+
load("@foo//:requirements.bzl", "all_requirements")
8488
py_binary(
8589
name = "baz",
8690
...
8791
deps = [
8892
":foo",
8993
] + all_requirements,
9094
)
91-
</code></pre>
92-
93-
Args:
94-
requirements: The label of a requirements.txt file.
95+
```
9596
""",
9697
)
9798

‎python/whl.bzl

Copy file name to clipboardExpand all lines: python/whl.bzl
+21-20Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,21 @@ def _whl_impl(repository_ctx):
3737

3838
whl_library = repository_rule(
3939
attrs = {
40-
"extras": attr.string_list(),
41-
"requirements": attr.string(),
40+
"extras": attr.string_list(doc = """
41+
A subset of the "extras" available from this <code>.whl</code> for which
42+
<code>requirements</code> has the dependencies.
43+
"""),
44+
"requirements": attr.string(doc = """
45+
The name of the <code>pip_import</code> repository rule from which to load this
46+
<code>.whl</code>'s dependencies.
47+
"""),
4248
"whl": attr.label(
4349
mandatory = True,
4450
allow_single_file = True,
51+
doc = """
52+
The path to the <code>.whl</code> file. The name is expected to follow [this
53+
convention](https://www.python.org/dev/peps/pep-0427/#file-name-convention)).
54+
""",
4555
),
4656
"_script": attr.label(
4757
executable = True,
@@ -50,30 +60,21 @@ whl_library = repository_rule(
5060
),
5161
},
5262
implementation = _whl_impl,
53-
doc = """A rule for importing <code>.whl</code> dependencies into Bazel.
63+
doc = """A rule for importing `.whl` dependencies into Bazel.
5464
55-
<b>This rule is currently used to implement <code>pip_import</code>,
56-
it is not intended to work standalone, and the interface may change.</b>
57-
See <code>pip_import</code> for proper usage.
65+
<b>This rule is currently used to implement `pip_import`. It is not intended to
66+
work standalone, and the interface may change.</b> See `pip_import` for proper
67+
usage.
5868
59-
This rule imports a <code>.whl</code> file as a <code>py_library</code>:
60-
<pre><code>whl_library(
69+
This rule imports a `.whl` file as a `py_library`:
70+
```python
71+
whl_library(
6172
name = "foo",
6273
whl = ":my-whl-file",
6374
requirements = "name of pip_import rule",
6475
)
65-
</code></pre>
66-
67-
This rule defines a <code>@foo//:pkg</code> <code>py_library</code> target.
68-
69-
Args:
70-
whl: The path to the .whl file (the name is expected to follow [this
71-
convention](https://www.python.org/dev/peps/pep-0427/#file-name-convention))
72-
73-
requirements: The name of the pip_import repository rule from which to
74-
load this .whl's dependencies.
76+
```
7577
76-
extras: A subset of the "extras" available from this <code>.whl</code> for which
77-
<code>requirements</code> has the dependencies.
78+
This rule defines `@foo//:pkg` as a `py_library` target.
7879
""",
7980
)

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.