From a729bc14ae6613b74590ddb6ccf7bcaef324f391 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Mon, 27 Sep 2021 16:59:25 -0700 Subject: [PATCH 1/2] docs: enforce that api docs are up-to-date Previously we just suggested you run a shell script to update, but there was no clue when that was needed in a PR --- CONTRIBUTING.md | 7 +++---- docs/BUILD | 49 +++++++++++++++++++++++++++++++++++++++-------- internal_deps.bzl | 9 +++++---- update_docs.sh | 24 ----------------------- 4 files changed, 49 insertions(+), 40 deletions(-) delete mode 100755 update_docs.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74afc7e7b8..676b60f282 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/docs/BUILD b/docs/BUILD index 0be577da26..1cc82d2ff9 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -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. @@ -68,7 +73,7 @@ bzl_library( stardoc( name = "core-docs", - out = "python.md", + out = "python.md_", input = "//python:defs.bzl", deps = [":defs"], ) @@ -79,7 +84,7 @@ stardoc( stardoc( name = "pip-docs", - out = "pip.md", + out = "pip.md_", input = "//python:pip.bzl", deps = [ ":bazel_repo_tools", @@ -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(), +) diff --git a/internal_deps.bzl b/internal_deps.bzl index f8b880a90b..de2226c05d 100644 --- a/internal_deps.bzl +++ b/internal_deps.bzl @@ -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( diff --git a/update_docs.sh b/update_docs.sh deleted file mode 100755 index 764530c7ce..0000000000 --- a/update_docs.sh +++ /dev/null @@ -1,24 +0,0 @@ -#!/bin/bash - -# Copyright 2017 The Bazel Authors. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -set -euo pipefail - -bazel build //docs/... - -cp bazel-bin/docs/python.md docs/ -cp bazel-bin/docs/pip.md docs/ -cp bazel-bin/docs/whl.md docs/ -cp bazel-bin/docs/packaging.md docs/ From 2547b75b34201fb32eedf4568c73acacd8094c1f Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Tue, 12 Oct 2021 16:40:24 -0700 Subject: [PATCH 2/2] Fix py_import example to work on python 3 --- examples/py_import/BUILD | 6 ++++-- examples/py_import/requirements.txt | 1 - 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/examples/py_import/BUILD b/examples/py_import/BUILD index 30ab5845a8..c3312c6936 100644 --- a/examples/py_import/BUILD +++ b/examples/py_import/BUILD @@ -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"]) @@ -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( diff --git a/examples/py_import/requirements.txt b/examples/py_import/requirements.txt index 372420dc2a..e69de29bb2 100644 --- a/examples/py_import/requirements.txt +++ b/examples/py_import/requirements.txt @@ -1 +0,0 @@ -futures>=3.1