)]}' { "commit": "6ca2f58bedca519f5ea6431ad7e11aaac84415c0", "tree": "63fe4f2f5aaed946172908a5c6b4f6f7e08d4001", "parents": [ "c7defbcd1181d30762632deb3b21e8a3a58f28a1" ], "author": { "name": "Richard Levasseur", "email": "rlevasseur@google.com", "time": "Thu May 23 20:44:47 2024 -0700" }, "committer": { "name": "GitHub", "email": "noreply@github.com", "time": "Fri May 24 03:44:47 2024 +0000" }, "message": "docs: generate Starlark domain markup instead of regular markdown (#1919)\n\nThis switches our doc generation over to using the Starlark domain\nmarkup from the sphinx_stardoc plugin instead of using regular markdown.\nThis allows the docs generated from code to better integrate with each\nother and other parts of the doc site.\n\nOverview of changes:\n\n* Makes the doc paths under the API directory more directly mirror their\nactual location. e.g. moves \"defs.md\" -\u003e \"python/defs.md\". This is so\nthe //tools doc entries have a more natural location, but can also be\nused for our other top-level directories.\n* Adds API docs for some of the well known targets we have. These aren\u0027t\nautomatically generated, but use the Starlark domain markup, so\nintegrate nicely with everything.\n* Ensures default values are parsable as Python expressions. Stardoc\nreturns values like \"\u003cfunction foo\u003e\" or \u0027Label(*, \"//bar\")\u0027 in some\ncases for the default value of args/attrs.\n* Ensures function signatures don\u0027t crash doc rendering. Stardoc gives\nbad/incomplete information, so reconstructing the original signature of\na function is tricky.\n* Allows references flags using leading slashes and a value, e.g.\n`--foo\u003dbar`. This makes it more natural to write while cross referencing\nto the flag.\n* Implements `{any}` xref resolution. It was just totally broken before.\n* Adds some additional bzl files that get documented.\n* Adds some more Bazel external references.\n* Fixes some missing bzl_library dependencies.\n* A few minor QoL improvements to the docs dev server:\n* Print the serving directory when CTRL+C is received. This makes it\neasier to find the raw files that are being generated.\n * Fix an error during shutdown about an unterminated generator.\n* The `sphinx_stardocs.footer` arg is removed. This was always just a\nhack to get extra link targets into the generated bzl docs. It\u0027s no\nlonger needed when the bzl domain is used.\n* Using `@repo//pkg:file.bzl%Name` syntax is supported in type\nexpressions (e.g. `:type:` option or `{type}` role) by quoting the\nlabel. The quoting is necessary because, under the hood, the expressions\nare parsed as Python.\n* Objects directives support an `:origin-key` directive. This records\nthe label identity that Bazel sees for an object (as from the Stardoc\norigin_key field). The markdown generate doesn\u0027t generate this for\neverything yet because some things are documented twice (e.g. py_binary\nin defs.bzl and py_binary.bzl), which would cause a crash (type things\ntrying to define the same id).\n* Add `*` and `**` to var-args and var-kwargs in signatures.\n* Allow providers to be refered to using the `type` role. This allows\nproviders to be referenced in `:type:` directives (e.g. in a provider\nfield).", "tree_diff": [ { "type": "modify", "old_id": "e3b9ad3f962df90b4adec4034cbb9d61835f3eca", "old_mode": 33188, "old_path": "docs/sphinx/BUILD.bazel", "new_id": "c2a1690ff38ccda6400dafce45856f8e18e4abe9", "new_mode": 33188, "new_path": "docs/sphinx/BUILD.bazel" }, { "type": "add", "old_id": "0000000000000000000000000000000000000000", "old_mode": 0, "old_path": "/dev/null", "new_id": "82a5b2a520208150ca026c166be861b60bcc9ab7", "new_mode": 33188, "new_path": "docs/sphinx/api/python/config_settings/index.md" }, { "type": "add", "old_id": "0000000000000000000000000000000000000000", "old_mode": 0, "old_path": "/dev/null", "new_id": "8026a7f14513ca8d0d0d85f4349ddad1069afd29", "new_mode": 33188, "new_path": "docs/sphinx/api/python/index.md" }, { "type": "add", "old_id": "0000000000000000000000000000000000000000", "old_mode": 0, "old_path": "/dev/null", "new_id": "1a476515921781401fb34d20e145600d44048bb2", "new_mode": 33188, "new_path": "docs/sphinx/api/tools/precompiler/index.md" }, { "type": "modify", "old_id": "b099f4270460cd409aa59740a4f88138f1a20fe0", "old_mode": 33188, "old_path": "docs/sphinx/bazel_inventory.txt", "new_id": "62cbdf89261a9d4344cc3283d6e6af845194f27f", "new_mode": 33188, "new_path": "docs/sphinx/bazel_inventory.txt" }, { "type": "modify", "old_id": "e9af97aa6e08e534c954bafd8ee676f8562b8d9f", "old_mode": 33188, "old_path": "docs/sphinx/conf.py", "new_id": "fef083cb53fc40a2dc9850f366a2debe57bc2d17", "new_mode": 33188, "new_path": "docs/sphinx/conf.py" }, { "type": "modify", "old_id": "e30fc947ad12b6567ab229b3523e8202693adb44", "old_mode": 33188, "old_path": "docs/sphinx/precompiling.md", "new_id": "52678e63ea7eef7d23125faf6587fc427b4ceb20", "new_mode": 33188, "new_path": "docs/sphinx/precompiling.md" }, { "type": "modify", "old_id": "3ab390df8ac4bb6c616157f06ac870ed465b0d2e", "old_mode": 33188, "old_path": "python/BUILD.bazel", "new_id": "5d31df5e9a0c4e4c3dbccc6679109a1d456ae1c4", "new_mode": 33188, "new_path": "python/BUILD.bazel" }, { "type": "modify", "old_id": "ab56fbef4d486bd3014cf29231ff2384a2d1306b", "old_mode": 33188, "old_path": "python/private/common/providers.bzl", "new_id": "5b84549185ce4cfce89c983fe61ebb0f2a660855", "new_mode": 33188, "new_path": "python/private/common/providers.bzl" }, { "type": "modify", "old_id": "a47a6a560d484dea210e483331faf75c7f99a80b", "old_mode": 33188, "old_path": "python/private/py_cc_toolchain_info.bzl", "new_id": "ae46bf4d4df3613d017424afbce5920e2d6fdd83", "new_mode": 33188, "new_path": "python/private/py_cc_toolchain_info.bzl" }, { "type": "modify", "old_id": "d17b008676b8e34c47195cd2b0dad2a1842dc69e", "old_mode": 33188, "old_path": "python/private/py_runtime_pair_rule.bzl", "new_id": "02f9a5ba890d7ee7b023dd6cd68124cb3a3ceea9", "new_mode": 33188, "new_path": "python/private/py_runtime_pair_rule.bzl" }, { "type": "modify", "old_id": "18d4e1e045e082965c41f8f68d8ad653722e84d1", "old_mode": 33188, "old_path": "sphinxdocs/private/proto_to_markdown.py", "new_id": "d667eeca00377fa2efa93173d69605f2baa47836", "new_mode": 33188, "new_path": "sphinxdocs/private/proto_to_markdown.py" }, { "type": "modify", "old_id": "e71889a6d35aebbe3105379dddac81c7486b8a08", "old_mode": 33188, "old_path": "sphinxdocs/private/sphinx_server.py", "new_id": "1f4fae86dedb5915c3a207cb166acd264c660da5", "new_mode": 33188, "new_path": "sphinxdocs/private/sphinx_server.py" }, { "type": "modify", "old_id": "810dca352487730c0bba425372dd3ae4fc98c3bc", "old_mode": 33188, "old_path": "sphinxdocs/private/sphinx_stardoc.bzl", "new_id": "e2b1756e129e81b732cc78a21f584dabaf9d4814", "new_mode": 33188, "new_path": "sphinxdocs/private/sphinx_stardoc.bzl" }, { "type": "modify", "old_id": "283fb67d770f5ee371310e965ac17b08b025dec6", "old_mode": 33188, "old_path": "sphinxdocs/src/sphinx_stardoc/stardoc.py", "new_id": "be38d8a7ca736fe3db98bceeec1aac87531c6694", "new_mode": 33188, "new_path": "sphinxdocs/src/sphinx_stardoc/stardoc.py" }, { "type": "modify", "old_id": "2964785eedbb03975bb1cc7a1470517ea44fe5fe", "old_mode": 33188, "old_path": "sphinxdocs/tests/proto_to_markdown/BUILD.bazel", "new_id": "09f537472cfb5e646b0131a24773cf0eb49e3ecf", "new_mode": 33188, "new_path": "sphinxdocs/tests/proto_to_markdown/BUILD.bazel" }, { "type": "modify", "old_id": "2f5b22e60b0e04cd8aeb838a039f8700afcb25eb", "old_mode": 33188, "old_path": "sphinxdocs/tests/proto_to_markdown/proto_to_markdown_test.py", "new_id": "3b664a533585618f9b65f8ab7126c1fbeeca7443", "new_mode": 33188, "new_path": "sphinxdocs/tests/proto_to_markdown/proto_to_markdown_test.py" }, { "type": "modify", "old_id": "5cf5736afa6ea76a30a152f666270a763d0a0f16", "old_mode": 33188, "old_path": "sphinxdocs/tests/sphinx_stardoc/BUILD.bazel", "new_id": "63e34fba3cfe85d0280c8e2e2afaa82a528e6408", "new_mode": 33188, "new_path": "sphinxdocs/tests/sphinx_stardoc/BUILD.bazel" }, { "type": "add", "old_id": "0000000000000000000000000000000000000000", "old_mode": 0, "old_path": "/dev/null", "new_id": "822ff26673b771dbe2bac5fd2582a698f15d5fe2", "new_mode": 33188, "new_path": "sphinxdocs/tests/sphinx_stardoc/bzl_function.bzl" }, { "type": "add", "old_id": "0000000000000000000000000000000000000000", "old_mode": 0, "old_path": "/dev/null", "new_id": "189d975d028bd3ab7f8989d5942fce9ae1d95d69", "new_mode": 33188, "new_path": "sphinxdocs/tests/sphinx_stardoc/bzl_providers.bzl" }, { "type": "add", "old_id": "0000000000000000000000000000000000000000", "old_mode": 0, "old_path": "/dev/null", "new_id": "d17c8bc087e05db37a8e09920e68a97572842bcb", "new_mode": 33188, "new_path": "sphinxdocs/tests/sphinx_stardoc/bzl_rule.bzl" }, { "type": "modify", "old_id": "b8cbd3727e9ea762922034835be5beecef2e3fa0", "old_mode": 33188, "old_path": "sphinxdocs/tests/sphinx_stardoc/function.md", "new_id": "de7d16aa4a4c56c407e44f357f97afd64d1b44d0", "new_mode": 33188, "new_path": "sphinxdocs/tests/sphinx_stardoc/function.md" }, { "type": "modify", "old_id": "a6f3a56b98efdeee79de460b9a82e38951ec3d7b", "old_mode": 33188, "old_path": "sphinxdocs/tests/sphinx_stardoc/rule.md", "new_id": "0f90ed32dc209ca88db66db3cbfa01fb7de844b1", "new_mode": 33188, "new_path": "sphinxdocs/tests/sphinx_stardoc/rule.md" }, { "type": "modify", "old_id": "f0ea038b3d2099c2c52e257fb1ecfa5909920095", "old_mode": 33188, "old_path": "sphinxdocs/tests/sphinx_stardoc/xrefs.md", "new_id": "9eb7b8178b48e05b9c48ada3f42029e53b13a9d9", "new_mode": 33188, "new_path": "sphinxdocs/tests/sphinx_stardoc/xrefs.md" } ] }