Skip to content

docs: enforce that api docs are up-to-date #540

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexeagle merged 2 commits into from
Oct 12, 2021
Merged

docs: enforce that api docs are up-to-date #540

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a729bc1
docs: enforce that api docs are up-to-date
alexeagle Sep 27, 2021
2547b75
Fix py_import example to work on python 3
alexeagle Oct 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,14 @@ merged.

### Documentation

To regenerate the content under the `docs/` directory, run this script in the
repository root:
To regenerate the content under the `docs/` directory, run this command:

```shell
./update_docs.sh
bazel run //docs:update
```

This needs to be done whenever the docstrings in the corresponding .bzl files
are changed; see `docs/BUILD`.
are changed; a test failure will remind you to run this command when needed.

### Precompiled tools

Expand Down
49 changes: 41 additions & 8 deletions docs/BUILD
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,22 @@
# See the License for the specific language governing permissions and
# limitations under the License.

###############################################################################
# To regenerate documentation, run the top-level update_docs.sh script. #
###############################################################################

load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
load("@bazel_skylib//rules:write_file.bzl", "write_file")
load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")

package(default_visibility = ["//visibility:public"])

licenses(["notice"]) # Apache 2.0

_DOCS = {
"packaging": "//docs:packaging-docs",
"pip": "//docs:pip-docs",
"python": "//docs:core-docs",
"whl": "//docs:whl-docs",
}

# We define these bzl_library targets here rather than in the //python package
# because they're only used for doc generation. This way, we avoid requiring
# our users to depend on Skylib.
Expand Down Expand Up @@ -68,7 +73,7 @@ bzl_library(

stardoc(
name = "core-docs",
out = "python.md",
out = "python.md_",
input = "//python:defs.bzl",
deps = [":defs"],
)
Expand All @@ -79,7 +84,7 @@ stardoc(

stardoc(
name = "pip-docs",
out = "pip.md",
out = "pip.md_",
input = "//python:pip.bzl",
deps = [
":bazel_repo_tools",
Expand All @@ -90,12 +95,40 @@ stardoc(

stardoc(
name = "whl-docs",
out = "whl.md",
out = "whl.md_",
input = "//python:whl.bzl",
)

stardoc(
name = "packaging-docs",
out = "packaging.md",
out = "packaging.md_",
input = "//python:packaging.bzl",
)

[
diff_test(
name = "check_" + k,
failure_message = "Please run: bazel run //docs:update",
file1 = k + ".md",
file2 = k + ".md_",
)
for k in _DOCS.keys()
]

write_file(
name = "gen_update",
out = "update.sh",
content = [
"#!/usr/bin/env bash",
"cd $BUILD_WORKSPACE_DIRECTORY",
] + [
"cp -fv bazel-bin/docs/{0}.md_ docs/{0}.md".format(k)
for k in _DOCS.keys()
],
)

sh_binary(
name = "update",
srcs = ["update.sh"],
data = _DOCS.values(),
)
6 changes: 4 additions & 2 deletions examples/py_import/BUILD
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@
# See the License for the specific language governing permissions and
# limitations under the License.

load("@pip//:requirements.bzl", "requirement")
load("@rules_python//python:defs.bzl", "py_import", "py_test")

package(default_visibility = ["//visibility:public"])
Expand All @@ -29,8 +28,11 @@ py_import(
# examples/py_import/helloworld.py=examples/legacy_pip_import/helloworld/helloworld.py \
# examples/__init__.py= \
# examples/py_import/__init__.py=
# TODO: we should construct an egg from local sources, or to make
# the example more meaningful for users, find an egg on the internet.
# Also it would help illustrate the rules if the egg has some other
# dependency, requiring deps here.
srcs = ["helloworld.egg"],
deps = [requirement("futures")],
)

py_test(
Expand Down
1 change: 0 additions & 1 deletion examples/py_import/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +0,0 @@
futures>=3.1
9 changes: 5 additions & 4 deletions internal_deps.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,11 @@ def rules_python_internal_deps():
maybe(
http_archive,
name = "bazel_skylib",
strip_prefix = "bazel-skylib-1.0.2",
url = "https://github.com/bazelbuild/bazel-skylib/archive/1.0.2.zip",
type = "zip",
sha256 = "64ad2728ccdd2044216e4cec7815918b7bb3bb28c95b7e9d951f9d4eccb07625",
sha256 = "c6966ec828da198c5d9adbaa94c05e3a1c7f21bd012a0b29ba8ddbccb2c93b0d",
urls = [
"https://github.com/bazelbuild/bazel-skylib/releases/download/1.1.1/bazel-skylib-1.1.1.tar.gz",
"https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.1.1/bazel-skylib-1.1.1.tar.gz",
],
)

maybe(
Expand Down
24 changes: 0 additions & 24 deletions update_docs.sh
View file
Open in desktop

This file was deleted.