1# Copyright 2017 The Bazel Authors. All rights reserved. 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14 15load("@bazel_skylib//:bzl_library.bzl", "bzl_library") 16load("@bazel_skylib//rules:diff_test.bzl", "diff_test") 17load("@bazel_skylib//rules:write_file.bzl", "write_file") 18load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") 19 20package(default_visibility = ["//visibility:public"]) 21 22licenses(["notice"]) # Apache 2.0 23 24_DOCS = { 25 "packaging": "//docs:packaging-docs", 26 "pip": "//docs:pip-docs", 27 "pip_repository": "//docs:pip-repository", 28 "py_cc_toolchain": "//docs:py_cc_toolchain-docs", 29 "py_cc_toolchain_info": "//docs:py_cc_toolchain_info-docs", 30 "python": "//docs:core-docs", 31} 32 33# We define these bzl_library targets here rather than in the //python package 34# because they're only used for doc generation. This way, we avoid requiring 35# our users to depend on Skylib. 36 37bzl_library( 38 name = "bazel_repo_tools", 39 srcs = [ 40 "@bazel_tools//tools:bzl_srcs", 41 ], 42) 43 44bzl_library( 45 name = "defs", 46 srcs = [ 47 "//python:defs.bzl", 48 "//python/private:reexports.bzl", 49 ], 50 deps = [ 51 ":bazel_repo_tools", 52 "//python:defs_bzl", 53 "//python/private:reexports_bzl", 54 ], 55) 56 57bzl_library( 58 name = "pip_install_bzl", 59 srcs = [ 60 "//python:bzl", 61 "//python/pip_install:bzl", 62 ], 63 deps = [ 64 ":defs", 65 "//:version.bzl", 66 ], 67) 68 69bzl_library( 70 name = "requirements_parser_bzl", 71 srcs = [ 72 "//python/pip_install:requirements_parser.bzl", 73 ], 74) 75 76bzl_library( 77 name = "packaging_bzl", 78 srcs = [ 79 "//python:packaging.bzl", 80 "//python/private:py_package.bzl", 81 "//python/private:py_wheel.bzl", 82 "//python/private:stamp.bzl", 83 "//python/private:util.bzl", 84 ], 85 deps = [ 86 "//python/private:util_bzl", 87 ], 88) 89 90# TODO: Stardoc does not guarantee consistent outputs accross platforms (Unix/Windows). 91# As a result we do not build or test docs on Windows. 92_NOT_WINDOWS = select({ 93 "@platforms//os:linux": [], 94 "@platforms//os:macos": [], 95 "//conditions:default": ["@platforms//:incompatible"], 96}) 97 98stardoc( 99 name = "core-docs", 100 out = "python.md_", 101 input = "//python:defs.bzl", 102 target_compatible_with = _NOT_WINDOWS, 103 deps = [":defs"], 104) 105 106stardoc( 107 name = "pip-docs", 108 out = "pip.md_", 109 input = "//python:pip.bzl", 110 target_compatible_with = _NOT_WINDOWS, 111 deps = [ 112 ":bazel_repo_tools", 113 ":pip_install_bzl", 114 "@bazel_skylib//lib:versions", 115 ], 116) 117 118stardoc( 119 name = "pip-repository", 120 out = "pip_repository.md_", 121 input = "//python/pip_install:pip_repository.bzl", 122 target_compatible_with = _NOT_WINDOWS, 123 deps = [ 124 ":bazel_repo_tools", 125 ":pip_install_bzl", 126 ":requirements_parser_bzl", 127 "@bazel_skylib//lib:versions", 128 ], 129) 130 131stardoc( 132 name = "packaging-docs", 133 out = "packaging.md_", 134 input = "//python:packaging.bzl", 135 target_compatible_with = _NOT_WINDOWS, 136 deps = [":packaging_bzl"], 137) 138 139stardoc( 140 name = "py_cc_toolchain-docs", 141 out = "py_cc_toolchain.md_", 142 # NOTE: The public file isn't used as the input because it would document 143 # the macro, which doesn't have the attribute documentation. The macro 144 # doesn't do anything interesting to users, so bypass it to avoid having to 145 # copy/paste all the rule's doc in the macro. 146 input = "//python/private:py_cc_toolchain_rule.bzl", 147 target_compatible_with = _NOT_WINDOWS, 148 deps = ["//python/private:py_cc_toolchain_bzl"], 149) 150 151stardoc( 152 name = "py_cc_toolchain_info-docs", 153 out = "py_cc_toolchain_info.md_", 154 input = "//python/cc:py_cc_toolchain_info.bzl", 155 deps = ["//python/cc:py_cc_toolchain_info_bzl"], 156) 157 158[ 159 diff_test( 160 name = "check_" + k, 161 failure_message = "Please run: bazel run //docs:update", 162 file1 = k + ".md", 163 file2 = k + ".md_", 164 target_compatible_with = _NOT_WINDOWS, 165 ) 166 for k in _DOCS.keys() 167] 168 169write_file( 170 name = "gen_update", 171 out = "update.sh", 172 content = [ 173 "#!/usr/bin/env bash", 174 "cd $BUILD_WORKSPACE_DIRECTORY", 175 ] + [ 176 "cp -fv bazel-bin/docs/{0}.md_ docs/{0}.md".format(k) 177 for k in _DOCS.keys() 178 ], 179 target_compatible_with = _NOT_WINDOWS, 180) 181 182sh_binary( 183 name = "update", 184 srcs = ["update.sh"], 185 data = _DOCS.values(), 186 target_compatible_with = _NOT_WINDOWS, 187) 188