)]}'
{
  "commit": "d2bd4320ec1a3d840e557f2e2848e9c4206c7a25",
  "tree": "d9088d92bb797ba539bd9e3ad9ad9885d910aa57",
  "parents": [
    "ced0c109b3403911e75f36be8e9ee895ea8f0962"
  ],
  "author": {
    "name": "Richard Levasseur",
    "email": "rlevasseur@google.com",
    "time": "Wed Oct 16 10:00:37 2024 -0700"
  },
  "committer": {
    "name": "GitHub",
    "email": "noreply@github.com",
    "time": "Wed Oct 16 17:00:37 2024 +0000"
  },
  "message": "sphinxdocs: add typedef directive for documenting user-defined types (#2300)\n\nThis adds support for documenting user-defined Starlark \"types\".\nStarlark doesn\u0027t have\nuser-defined types as a first-class concept, but an equivalent can be\ndone by using\n`struct` with lambdas and closures. On the documentation side, the\nstructure of these\nobjects can be shown by have a module-level struct with matching\nattributes.\n\nOn the Sphinx side of things, this is simple to support (and the\nfunctionality was largely\nalready there): it\u0027s just having a directive with other directives\nwithin it (this\nis the same way other languages handle it).\n\nOn the Starlark side of things, its a bit more complicated. Stardoc can\nprocess a\nmodule-level struct, but essentially returns a list of `(dotted_name,\nobject_proto)`,\nand it will only include object types it recognizes (e.g. functions,\nproviders, rules, etc).\n\nTo work within this limitation, the proto-to-markdown converter special\ncases the name\n\"TYPEDEF\" to indicate a typedef. Everything with the same prefix is then\ntreated as\na member of the typedef and nested within the generated typedef\ndirective. Conveniently,\nbecause the \"TYPEDEF\" object is a function, it can then include that in\nthe output\nand we get \"class doc\" functionality for free.\n\nThis is mostly motivated by converting rules_testing to use sphinxdocs.\nWhile rules_python\nhas a couple user-define types (e.g. the depset/runfiles/PyInfo\nbuilders),\nrules_testing has dozens of such types, which makes it untenable to\nhand-write docs\ndescribing them all. Today, rules_testing is already mostly following\nthe format sphinxdocs\nproscribes to generate its at\nhttps://rules-testing.readthedocs.io/en/latest/api/index.html,\nand it\u0027s worked pretty well.",
  "tree_diff": [
    {
      "type": "modify",
      "old_id": "73ae138f0ea7804621c20aad24fc578d5e075970",
      "old_mode": 33188,
      "old_path": "sphinxdocs/docs/sphinx-bzl.md",
      "new_id": "8376f60679a125e32719afa35b73930fa5747d50",
      "new_mode": 33188,
      "new_path": "sphinxdocs/docs/sphinx-bzl.md"
    },
    {
      "type": "modify",
      "old_id": "d131607c8ea9d7d230a3c23f6f741691c5cc93bd",
      "old_mode": 33188,
      "old_path": "sphinxdocs/docs/starlark-docgen.md",
      "new_id": "ba4ab516f505739f07d049ab86f0c91a8e7e8b2c",
      "new_mode": 33188,
      "new_path": "sphinxdocs/docs/starlark-docgen.md"
    },
    {
      "type": "modify",
      "old_id": "d667eeca00377fa2efa93173d69605f2baa47836",
      "old_mode": 33188,
      "old_path": "sphinxdocs/private/proto_to_markdown.py",
      "new_id": "1f0fe3143e17424224abdd98cae36a95b3210e3c",
      "new_mode": 33188,
      "new_path": "sphinxdocs/private/proto_to_markdown.py"
    },
    {
      "type": "modify",
      "old_id": "54b1285a840f217273987a64caf753ea18b68de0",
      "old_mode": 33188,
      "old_path": "sphinxdocs/src/sphinx_bzl/bzl.py",
      "new_id": "90fb10961459bc62c38b519e063f4845a78da2ac",
      "new_mode": 33188,
      "new_path": "sphinxdocs/src/sphinx_bzl/bzl.py"
    },
    {
      "type": "modify",
      "old_id": "3b664a533585618f9b65f8ab7126c1fbeeca7443",
      "old_mode": 33188,
      "old_path": "sphinxdocs/tests/proto_to_markdown/proto_to_markdown_test.py",
      "new_id": "7835d64c311575a00301430b33550968342ea6cb",
      "new_mode": 33188,
      "new_path": "sphinxdocs/tests/proto_to_markdown/proto_to_markdown_test.py"
    },
    {
      "type": "modify",
      "old_id": "3741e4169cb16515a7e31a9914d48e578c65c663",
      "old_mode": 33188,
      "old_path": "sphinxdocs/tests/sphinx_stardoc/BUILD.bazel",
      "new_id": "60a5e8d766c3e034b0616d8f7616f52616251435",
      "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": "5afd0bf837e9d297d023a69ba5309080721374e3",
      "new_mode": 33188,
      "new_path": "sphinxdocs/tests/sphinx_stardoc/bzl_typedef.bzl"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "08c4aa2c1b81cd920c44556e9faa496b276b9c83",
      "new_mode": 33188,
      "new_path": "sphinxdocs/tests/sphinx_stardoc/typedef.md"
    }
  ]
}