)]}'
{
  "commit": "29c83baeccf4b5dc27308999e5cca65eb3774e86",
  "tree": "616915e41afbfaba8d7c7e822659b4bf08cfb113",
  "parents": [
    "1a74ba4cb4c2faee902e9088281d824385ba2bc6"
  ],
  "author": {
    "name": "Tim Swast",
    "email": "swast@google.com",
    "time": "Tue Feb 11 13:40:17 2020 -0600"
  },
  "committer": {
    "name": "GitHub",
    "email": "noreply@github.com",
    "time": "Tue Feb 11 11:40:17 2020 -0800"
  },
  "message": "python: add sphinx docs (#6525)\n\n* python: generate documentation with Sphinx and Read the Docs\r\n\r\nBackground:\r\n\r\nFormerly, the Python protobuf reference documentation was built with\r\n[Epydoc](http://epydoc.sourceforge.net/). This package has not been\r\nupdated since 2008, and it has inconsistent formatting (see internal\r\nissue 131415575) with most Python documentation. Sphinx is used for the\r\nofficial docs.python.org docs as well as most other Python packages,\r\nincluding the Google client libraries and related packages, such as\r\nhttps://googleapis.dev/python/google-api-core/latest/\r\n\r\nTo build the docs with Sphinx:\r\n\r\n1. Install the needed packages (`sphinx`, `sphinxcontrib-napoleon` for\r\nGoogle-style docstring support). I\u0027ve created a conda environment file\r\nto make this easier:\r\n\r\n```\r\nconda env create -f python/docs/environment.yml\r\n```\r\n\r\n2. (Optional) Generate reference docs files and regenerate index:\r\n\r\n```\r\ncd python\r\npython generate_docs.py\r\ncd ..\r\n```\r\n\r\n3. Run Sphinx.\r\n\r\n```\r\ncd python/docs\r\nmake html\r\n```\r\n\r\nAbout this change:\r\n\r\nThe script at `python/generate_docs.py` creates a ReStructured Text file\r\nfor each public module in the protobuf Python package. The script also\r\nupdates the table of contents in `python/docs/index.rst` to point to\r\nthese module references.\r\n\r\nFuture work:\r\n\r\nTesting the docs build on PRs requires contributors to actually do some\r\nsetup work to configure builds on their fork. It\u0027d be better if CI had a\r\ndocs build session to verify that the Sphinx docs generation at least\r\nruns.\r\n\r\nThere are many warnings due to not-quite-correct docstrings in the\r\nactual Python code itself. I\u0027m choosing to ignore these errors to keep\r\nthe PR small, but I recommend you fix these and then enable \"fail on\r\nwarnings\" in the docs build on CI.\r\n\r\n* add docs to EXTRA_DIST\r\n\r\n* add instructions to build documentation to generate_docs.py\r\n\r\n* exclude python/odcs from cpp_distcheck\r\n",
  "tree_diff": [
    {
      "type": "modify",
      "old_id": "5e38bbf7c28348d18b3d659202cd8f3722c63776",
      "old_mode": 33188,
      "old_path": ".gitignore",
      "new_id": "0cbcf503800f507d7b1af8618008a50a756d7f15",
      "new_mode": 33188,
      "new_path": ".gitignore"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "298ea9e213e8c4c11f0431077510d4e325733c65",
      "new_mode": 33188,
      "new_path": "python/docs/Makefile"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "0b42b55d50a26c9c8cd22a396c40ccdee684b3ec",
      "new_mode": 33188,
      "new_path": "python/docs/conf.py"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "2c7a8d93efada9fc0b548dd7e6fb160f16e630eb",
      "new_mode": 33188,
      "new_path": "python/docs/environment.yml"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "9b76e0cac1b6700a4369b1f1d2a8e2ce76c60364",
      "new_mode": 33261,
      "new_path": "python/docs/generate_docs.py"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "0982bf31a81b5461bbe7d967df513b351d42e76a",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "42198c8cf646ef007eeb8a28778013fc0e742c79",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/any_pb2.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "949b97f61a6242e7aa804f7b6507705781edbf90",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/descriptor.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "912439d1f7d6a4bca82dcfd971274df940c59d9d",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/descriptor_database.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "6b18b44bb9b7528bdba9a5a4768823db8b138bcd",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/descriptor_pb2.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "8b1ab9943a032f55fc9f054325d4af5e9af5cf50",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/descriptor_pool.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "7e39f9e94eb1cf150d12ae16ce760cf3ad9d5aa4",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/duration_pb2.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "39cbb6431e8c473cc064fd2c01549e853725d33e",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/empty_pb2.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "3a0c40cd3ba9184e881532ea7e1c790f249401c3",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/field_mask_pb2.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "8f436e154d7fa815b7c0faff526049c980910629",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/json_format.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "03d0dda86f1c271b3660f0aacf7bd0401bcd84ed",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/message.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "b098a8d392c7fba748bc1c71856f868635d6bd0e",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/message_factory.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "5cc17409d3fe75cdbf212328574f4a4bf4b0408b",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/proto_builder.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "0bee3e5f45fa50ceec51d26c84c0d52e5016997c",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/reflection.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "9b3a7b326770ac862027821a981741568f55f3ab",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/service.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "1fb688531eefe22571b84fb16f6b99953f82d2e1",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/service_reflection.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "617a580f7870078e3a5969682f85ce9606502fb4",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/struct_pb2.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "76bcf2f4e5a50fe1b4e6ab7b4ab348af355f638b",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/symbol_database.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "0e3a5d97ba22eb636f6efd360d3be7327689faad",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/text_encoding.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "6b4c40a66152f64afb2165395114687cf1b530e1",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/text_format.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "4160fe073128229246fab5c59a7b79c975b064d6",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/timestamp_pb2.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "8f0fb1481cdf36e649c2d0d25f371d63c3ef6fc0",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/type_pb2.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "037af966f0172de49e5df217fdeeaa3f392af7a1",
      "new_mode": 33188,
      "new_path": "python/docs/google/protobuf/wrappers_pb2.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "d5bb39e7801b47f688cbc41aab60f66496594305",
      "new_mode": 33188,
      "new_path": "python/docs/index.rst"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "27f573b87af11e2cbbd9f54eb1ee285a58550146",
      "new_mode": 33188,
      "new_path": "python/docs/make.bat"
    },
    {
      "type": "add",
      "old_id": "0000000000000000000000000000000000000000",
      "old_mode": 0,
      "old_path": "/dev/null",
      "new_id": "2b3e98925ec72c1904f15b57cb770eb4e5923487",
      "new_mode": 33188,
      "new_path": "python/docs/requirements.txt"
    },
    {
      "type": "modify",
      "old_id": "77039d6c0ddddc62f8da1f3f8271a5b8985eac6d",
      "old_mode": 33261,
      "old_path": "tests.sh",
      "new_id": "9e72cb5fbbd492e26dd367ea0f6a731361c5c73c",
      "new_mode": 33261,
      "new_path": "tests.sh"
    }
  ]
}