1# Copyright 2023 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 15"""Implementation of sphinx rules.""" 16 17load("@bazel_skylib//lib:paths.bzl", "paths") 18load("@bazel_skylib//rules:build_test.bzl", "build_test") 19load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo") 20load("//python:py_binary.bzl", "py_binary") 21load("//python/private:util.bzl", "add_tag", "copy_propagating_kwargs") # buildifier: disable=bzl-visibility 22load(":sphinx_docs_library_info.bzl", "SphinxDocsLibraryInfo") 23 24_SPHINX_BUILD_MAIN_SRC = Label("//sphinxdocs/private:sphinx_build.py") 25_SPHINX_SERVE_MAIN_SRC = Label("//sphinxdocs/private:sphinx_server.py") 26 27_SphinxSourceTreeInfo = provider( 28 doc = "Information about source tree for Sphinx to build.", 29 fields = { 30 "source_dir_runfiles_path": """ 31:type: str 32 33Runfiles-root relative path of the root directory for the source files. 34""", 35 "source_root": """ 36:type: str 37 38Exec-root relative path of the root directory for the source files (which are in DefaultInfo.files) 39""", 40 }, 41) 42 43_SphinxRunInfo = provider( 44 doc = "Information for running the underlying Sphinx command directly", 45 fields = { 46 "per_format_args": """ 47:type: dict[str, struct] 48 49A dict keyed by output format name. The values are a struct with attributes: 50* args: a `list[str]` of args to run this format's build 51* env: a `dict[str, str]` of environment variables to set for this format's build 52""", 53 "source_tree": """ 54:type: Target 55 56Target with the source tree files 57""", 58 "sphinx": """ 59:type: Target 60 61The sphinx-build binary to run. 62""", 63 "tools": """ 64:type: list[Target] 65 66Additional tools Sphinx needs 67""", 68 }, 69) 70 71def sphinx_build_binary(name, py_binary_rule = py_binary, **kwargs): 72 """Create an executable with the sphinx-build command line interface. 73 74 The `deps` must contain the sphinx library and any other extensions Sphinx 75 needs at runtime. 76 77 Args: 78 name: {type}`str` name of the target. The name "sphinx-build" is the 79 conventional name to match what Sphinx itself uses. 80 py_binary_rule: {type}`callable` A `py_binary` compatible callable 81 for creating the target. If not set, the regular `py_binary` 82 rule is used. This allows using the version-aware rules, or 83 other alternative implementations. 84 **kwargs: {type}`dict` Additional kwargs to pass onto `py_binary`. The `srcs` and 85 `main` attributes must not be specified. 86 """ 87 add_tag(kwargs, "@rules_python//sphinxdocs:sphinx_build_binary") 88 py_binary_rule( 89 name = name, 90 srcs = [_SPHINX_BUILD_MAIN_SRC], 91 main = _SPHINX_BUILD_MAIN_SRC, 92 **kwargs 93 ) 94 95def sphinx_docs( 96 name, 97 *, 98 srcs = [], 99 deps = [], 100 renamed_srcs = {}, 101 sphinx, 102 config, 103 formats, 104 strip_prefix = "", 105 extra_opts = [], 106 tools = [], 107 **kwargs): 108 """Generate docs using Sphinx. 109 110 Generates targets: 111 * `<name>`: The output of this target is a directory for each 112 format Sphinx creates. This target also has a separate output 113 group for each format. e.g. `--output_group=html` will only build 114 the "html" format files. 115 * `<name>.serve`: A binary that locally serves the HTML output. This 116 allows previewing docs during development. 117 * `<name>.run`: A binary that directly runs the underlying Sphinx command 118 to build the docs. This is a debugging aid. 119 120 Args: 121 name: {type}`Name` name of the docs rule. 122 srcs: {type}`list[label]` The source files for Sphinx to process. 123 deps: {type}`list[label]` of {obj}`sphinx_docs_library` targets. 124 renamed_srcs: {type}`dict[label, dict]` Doc source files for Sphinx that 125 are renamed. This is typically used for files elsewhere, such as top 126 level files in the repo. 127 sphinx: {type}`label` the Sphinx tool to use for building 128 documentation. Because Sphinx supports various plugins, you must 129 construct your own binary with the necessary dependencies. The 130 {obj}`sphinx_build_binary` rule can be used to define such a binary, but 131 any executable supporting the `sphinx-build` command line interface 132 can be used (typically some `py_binary` program). 133 config: {type}`label` the Sphinx config file (`conf.py`) to use. 134 formats: (list of str) the formats (`-b` flag) to generate documentation 135 in. Each format will become an output group. 136 strip_prefix: {type}`str` A prefix to remove from the file paths of the 137 source files. e.g., given `//docs:foo.md`, stripping `docs/` makes 138 Sphinx see `foo.md` in its generated source directory. If not 139 specified, then {any}`native.package_name` is used. 140 extra_opts: {type}`list[str]` Additional options to pass onto Sphinx building. 141 On each provided option, a location expansion is performed. 142 See {any}`ctx.expand_location`. 143 tools: {type}`list[label]` Additional tools that are used by Sphinx and its plugins. 144 This just makes the tools available during Sphinx execution. To locate 145 them, use {obj}`extra_opts` and `$(location)`. 146 **kwargs: {type}`dict` Common attributes to pass onto rules. 147 """ 148 add_tag(kwargs, "@rules_python//sphinxdocs:sphinx_docs") 149 common_kwargs = copy_propagating_kwargs(kwargs) 150 151 internal_name = "_{}".format(name.lstrip("_")) 152 153 _sphinx_source_tree( 154 name = internal_name + "/_sources", 155 srcs = srcs, 156 deps = deps, 157 renamed_srcs = renamed_srcs, 158 config = config, 159 strip_prefix = strip_prefix, 160 **common_kwargs 161 ) 162 _sphinx_docs( 163 name = name, 164 sphinx = sphinx, 165 formats = formats, 166 source_tree = internal_name + "/_sources", 167 extra_opts = extra_opts, 168 tools = tools, 169 **kwargs 170 ) 171 172 html_name = internal_name + "_html" 173 native.filegroup( 174 name = html_name, 175 srcs = [name], 176 output_group = "html", 177 **common_kwargs 178 ) 179 180 py_binary( 181 name = name + ".serve", 182 srcs = [_SPHINX_SERVE_MAIN_SRC], 183 main = _SPHINX_SERVE_MAIN_SRC, 184 data = [html_name], 185 args = [ 186 "$(execpath {})".format(html_name), 187 ], 188 **common_kwargs 189 ) 190 sphinx_run( 191 name = name + ".run", 192 docs = name, 193 ) 194 195 build_test( 196 name = name + "_build_test", 197 targets = [name], 198 **kwargs # kwargs used to pick up target_compatible_with 199 ) 200 201def _sphinx_docs_impl(ctx): 202 source_tree_info = ctx.attr.source_tree[_SphinxSourceTreeInfo] 203 source_dir_path = source_tree_info.source_root 204 inputs = ctx.attr.source_tree[DefaultInfo].files 205 206 per_format_args = {} 207 outputs = {} 208 for format in ctx.attr.formats: 209 output_dir, args_env = _run_sphinx( 210 ctx = ctx, 211 format = format, 212 source_path = source_dir_path, 213 output_prefix = paths.join(ctx.label.name, "_build"), 214 inputs = inputs, 215 ) 216 outputs[format] = output_dir 217 per_format_args[format] = args_env 218 return [ 219 DefaultInfo(files = depset(outputs.values())), 220 OutputGroupInfo(**{ 221 format: depset([output]) 222 for format, output in outputs.items() 223 }), 224 _SphinxRunInfo( 225 sphinx = ctx.attr.sphinx, 226 source_tree = ctx.attr.source_tree, 227 tools = ctx.attr.tools, 228 per_format_args = per_format_args, 229 ), 230 ] 231 232_sphinx_docs = rule( 233 implementation = _sphinx_docs_impl, 234 attrs = { 235 "extra_opts": attr.string_list( 236 doc = "Additional options to pass onto Sphinx. These are added after " + 237 "other options, but before the source/output args.", 238 ), 239 "formats": attr.string_list(doc = "Output formats for Sphinx to create."), 240 "source_tree": attr.label( 241 doc = "Directory of files for Sphinx to process.", 242 providers = [_SphinxSourceTreeInfo], 243 ), 244 "sphinx": attr.label( 245 executable = True, 246 cfg = "exec", 247 mandatory = True, 248 doc = "Sphinx binary to generate documentation.", 249 ), 250 "tools": attr.label_list( 251 cfg = "exec", 252 doc = "Additional tools that are used by Sphinx and its plugins.", 253 ), 254 "_extra_defines_flag": attr.label(default = "//sphinxdocs:extra_defines"), 255 "_extra_env_flag": attr.label(default = "//sphinxdocs:extra_env"), 256 "_quiet_flag": attr.label(default = "//sphinxdocs:quiet"), 257 }, 258) 259 260def _run_sphinx(ctx, format, source_path, inputs, output_prefix): 261 output_dir = ctx.actions.declare_directory(paths.join(output_prefix, format)) 262 263 run_args = [] # Copy of the args to forward along to debug runner 264 args = ctx.actions.args() # Args passed to the action 265 266 args.add("--show-traceback") # Full tracebacks on error 267 run_args.append("--show-traceback") 268 args.add("--builder", format) 269 run_args.extend(("--builder", format)) 270 271 if ctx.attr._quiet_flag[BuildSettingInfo].value: 272 # Not added to run_args because run_args is for debugging 273 args.add("--quiet") # Suppress stdout informational text 274 275 # Build in parallel, if possible 276 # Don't add to run_args: parallel building breaks interactive debugging 277 args.add("--jobs", "auto") 278 args.add("--fresh-env") # Don't try to use cache files. Bazel can't make use of them. 279 run_args.append("--fresh-env") 280 args.add("--write-all") # Write all files; don't try to detect "changed" files 281 run_args.append("--write-all") 282 283 for opt in ctx.attr.extra_opts: 284 expanded = ctx.expand_location(opt) 285 args.add(expanded) 286 run_args.append(expanded) 287 288 extra_defines = ctx.attr._extra_defines_flag[_FlagInfo].value 289 args.add_all(extra_defines, before_each = "--define") 290 for define in extra_defines: 291 run_args.extend(("--define", define)) 292 293 args.add(source_path) 294 args.add(output_dir.path) 295 296 env = dict([ 297 v.split("=", 1) 298 for v in ctx.attr._extra_env_flag[_FlagInfo].value 299 ]) 300 301 tools = [] 302 for tool in ctx.attr.tools: 303 tools.append(tool[DefaultInfo].files_to_run) 304 305 ctx.actions.run( 306 executable = ctx.executable.sphinx, 307 arguments = [args], 308 inputs = inputs, 309 outputs = [output_dir], 310 tools = tools, 311 mnemonic = "SphinxBuildDocs", 312 progress_message = "Sphinx building {} for %{{label}}".format(format), 313 env = env, 314 ) 315 return output_dir, struct(args = run_args, env = env) 316 317def _sphinx_source_tree_impl(ctx): 318 # Sphinx only accepts a single directory to read its doc sources from. 319 # Because plain files and generated files are in different directories, 320 # we need to merge the two into a single directory. 321 source_prefix = ctx.label.name 322 sphinx_source_files = [] 323 324 # Materialize a file under the `_sources` dir 325 def _relocate(source_file, dest_path = None): 326 if not dest_path: 327 dest_path = source_file.short_path.removeprefix(ctx.attr.strip_prefix) 328 dest_file = ctx.actions.declare_file(paths.join(source_prefix, dest_path)) 329 ctx.actions.symlink( 330 output = dest_file, 331 target_file = source_file, 332 progress_message = "Symlinking Sphinx source %{input} to %{output}", 333 ) 334 sphinx_source_files.append(dest_file) 335 return dest_file 336 337 # Though Sphinx has a -c flag, we move the config file into the sources 338 # directory to make the config more intuitive because some configuration 339 # options are relative to the config location, not the sources directory. 340 source_conf_file = _relocate(ctx.file.config) 341 sphinx_source_dir_path = paths.dirname(source_conf_file.path) 342 343 for src in ctx.attr.srcs: 344 if SphinxDocsLibraryInfo in src: 345 fail(( 346 "In attribute srcs: target {src} is misplaced here: " + 347 "sphinx_docs_library targets belong in the deps attribute." 348 ).format(src = src)) 349 350 for orig_file in ctx.files.srcs: 351 _relocate(orig_file) 352 353 for src_target, dest in ctx.attr.renamed_srcs.items(): 354 src_files = src_target.files.to_list() 355 if len(src_files) != 1: 356 fail("A single file must be specified to be renamed. Target {} " + 357 "generate {} files: {}".format( 358 src_target, 359 len(src_files), 360 src_files, 361 )) 362 _relocate(src_files[0], dest) 363 364 for t in ctx.attr.deps: 365 info = t[SphinxDocsLibraryInfo] 366 for entry in info.transitive.to_list(): 367 for original in entry.files: 368 new_path = entry.prefix + original.short_path.removeprefix(entry.strip_prefix) 369 _relocate(original, new_path) 370 371 return [ 372 DefaultInfo( 373 files = depset(sphinx_source_files), 374 ), 375 _SphinxSourceTreeInfo( 376 source_root = sphinx_source_dir_path, 377 source_dir_runfiles_path = paths.dirname(source_conf_file.short_path), 378 ), 379 ] 380 381_sphinx_source_tree = rule( 382 implementation = _sphinx_source_tree_impl, 383 attrs = { 384 "config": attr.label( 385 allow_single_file = True, 386 mandatory = True, 387 doc = "Config file for Sphinx", 388 ), 389 "deps": attr.label_list( 390 providers = [SphinxDocsLibraryInfo], 391 ), 392 "renamed_srcs": attr.label_keyed_string_dict( 393 allow_files = True, 394 doc = "Doc source files for Sphinx that are renamed. This is " + 395 "typically used for files elsewhere, such as top level " + 396 "files in the repo.", 397 ), 398 "srcs": attr.label_list( 399 allow_files = True, 400 doc = "Doc source files for Sphinx.", 401 ), 402 "strip_prefix": attr.string(doc = "Prefix to remove from input file paths."), 403 }, 404) 405_FlagInfo = provider( 406 doc = "Provider for a flag value", 407 fields = ["value"], 408) 409 410def _repeated_string_list_flag_impl(ctx): 411 return _FlagInfo(value = ctx.build_setting_value) 412 413repeated_string_list_flag = rule( 414 implementation = _repeated_string_list_flag_impl, 415 build_setting = config.string_list(flag = True, repeatable = True), 416) 417 418def sphinx_inventory(*, name, src, **kwargs): 419 """Creates a compressed inventory file from an uncompressed on. 420 421 The Sphinx inventory format isn't formally documented, but is understood 422 to be: 423 424 ``` 425 # Sphinx inventory version 2 426 # Project: <project name> 427 # Version: <version string> 428 # The remainder of this file is compressed using zlib 429 name domain:role 1 relative-url display name 430 ``` 431 432 Where: 433 * `<project name>` is a string. e.g. `Rules Python` 434 * `<version string>` is a string e.g. `1.5.3` 435 436 And there are one or more `name domain:role ...` lines 437 * `name`: the name of the symbol. It can contain special characters, 438 but not spaces. 439 * `domain:role`: The `domain` is usually a language, e.g. `py` or `bzl`. 440 The `role` is usually the type of object, e.g. `class` or `func`. There 441 is no canonical meaning to the values, they are usually domain-specific. 442 * `1` is a number. It affects search priority. 443 * `relative-url` is a URL path relative to the base url in the 444 confg.py intersphinx config. 445 * `display name` is a string. It can contain spaces, or simply be 446 the value `-` to indicate it is the same as `name` 447 448 :::{seealso} 449 {bzl:obj}`//sphinxdocs/inventories` for inventories of Bazel objects. 450 ::: 451 452 Args: 453 name: {type}`Name` name of the target. 454 src: {type}`label` Uncompressed inventory text file. 455 **kwargs: {type}`dict` additional kwargs of common attributes. 456 """ 457 _sphinx_inventory(name = name, src = src, **kwargs) 458 459def _sphinx_inventory_impl(ctx): 460 output = ctx.actions.declare_file(ctx.label.name + ".inv") 461 args = ctx.actions.args() 462 args.add(ctx.file.src) 463 args.add(output) 464 ctx.actions.run( 465 executable = ctx.executable._builder, 466 arguments = [args], 467 inputs = depset([ctx.file.src]), 468 outputs = [output], 469 ) 470 return [DefaultInfo(files = depset([output]))] 471 472_sphinx_inventory = rule( 473 implementation = _sphinx_inventory_impl, 474 attrs = { 475 "src": attr.label(allow_single_file = True), 476 "_builder": attr.label( 477 default = "//sphinxdocs/private:inventory_builder", 478 executable = True, 479 cfg = "exec", 480 ), 481 }, 482) 483 484def _sphinx_run_impl(ctx): 485 run_info = ctx.attr.docs[_SphinxRunInfo] 486 487 builder = ctx.attr.builder 488 489 if builder not in run_info.per_format_args: 490 builder = run_info.per_format_args.keys()[0] 491 492 args_info = run_info.per_format_args.get(builder) 493 if not args_info: 494 fail("Format {} not built by {}".format( 495 builder, 496 ctx.attr.docs.label, 497 )) 498 499 args_str = [] 500 args_str.extend(args_info.args) 501 args_str = "\n".join(["args+=('{}')".format(value) for value in args_info.args]) 502 if not args_str: 503 args_str = "# empty custom args" 504 505 env_str = "\n".join([ 506 "sphinx_env+=({}='{}')".format(*item) 507 for item in args_info.env.items() 508 ]) 509 if not env_str: 510 env_str = "# empty custom env" 511 512 executable = ctx.actions.declare_file(ctx.label.name) 513 sphinx = run_info.sphinx 514 ctx.actions.expand_template( 515 template = ctx.file._template, 516 output = executable, 517 substitutions = { 518 "%SETUP_ARGS%": args_str, 519 "%SETUP_ENV%": env_str, 520 "%SOURCE_DIR_EXEC_PATH%": run_info.source_tree[_SphinxSourceTreeInfo].source_root, 521 "%SOURCE_DIR_RUNFILES_PATH%": run_info.source_tree[_SphinxSourceTreeInfo].source_dir_runfiles_path, 522 "%SPHINX_EXEC_PATH%": sphinx[DefaultInfo].files_to_run.executable.path, 523 "%SPHINX_RUNFILES_PATH%": sphinx[DefaultInfo].files_to_run.executable.short_path, 524 }, 525 is_executable = True, 526 ) 527 runfiles = ctx.runfiles( 528 transitive_files = run_info.source_tree[DefaultInfo].files, 529 ).merge(sphinx[DefaultInfo].default_runfiles).merge_all([ 530 tool[DefaultInfo].default_runfiles 531 for tool in run_info.tools 532 ]) 533 return [ 534 DefaultInfo( 535 executable = executable, 536 runfiles = runfiles, 537 ), 538 ] 539 540sphinx_run = rule( 541 implementation = _sphinx_run_impl, 542 doc = """ 543Directly run the underlying Sphinx command `sphinx_docs` uses. 544 545This is primarily a debugging tool. It's useful for directly running the 546Sphinx command so that debuggers can be attached or output more directly 547inspected without Bazel interference. 548""", 549 attrs = { 550 "builder": attr.string( 551 doc = "The output format to make runnable.", 552 default = "html", 553 ), 554 "docs": attr.label( 555 doc = "The {obj}`sphinx_docs` target to make directly runnable.", 556 providers = [_SphinxRunInfo], 557 ), 558 "_template": attr.label( 559 allow_single_file = True, 560 default = "//sphinxdocs/private:sphinx_run_template.sh", 561 ), 562 }, 563 executable = True, 564) 565