commit 29c83baeccf4b5dc27308999e5cca65eb3774e86
author Tim Swast <swast@google.com> Tue Feb 11 13:40:17 2020 -0600
committer GitHub <noreply@github.com> Tue Feb 11 11:40:17 2020 -0800
tree 616915e41afbfaba8d7c7e822659b4bf08cfb113
parent 1a74ba4cb4c2faee902e9088281d824385ba2bc6

python: add sphinx docs (#6525)

* python: generate documentation with Sphinx and Read the Docs

Background:

Formerly, the Python protobuf reference documentation was built with
[Epydoc](http://epydoc.sourceforge.net/). This package has not been
updated since 2008, and it has inconsistent formatting (see internal
issue 131415575) with most Python documentation. Sphinx is used for the
official docs.python.org docs as well as most other Python packages,
including the Google client libraries and related packages, such as
https://googleapis.dev/python/google-api-core/latest/

To build the docs with Sphinx:

1. Install the needed packages (`sphinx`, `sphinxcontrib-napoleon` for
Google-style docstring support). I've created a conda environment file
to make this easier:

```
conda env create -f python/docs/environment.yml
```

2. (Optional) Generate reference docs files and regenerate index:

```
cd python
python generate_docs.py
cd ..
```

3. Run Sphinx.

```
cd python/docs
make html
```

About this change:

The script at `python/generate_docs.py` creates a ReStructured Text file
for each public module in the protobuf Python package. The script also
updates the table of contents in `python/docs/index.rst` to point to
these module references.

Future work:

Testing the docs build on PRs requires contributors to actually do some
setup work to configure builds on their fork. It'd be better if CI had a
docs build session to verify that the Sphinx docs generation at least
runs.

There are many warnings due to not-quite-correct docstrings in the
actual Python code itself. I'm choosing to ignore these errors to keep
the PR small, but I recommend you fix these and then enable "fail on
warnings" in the docs build on CI.

* add docs to EXTRA_DIST

* add instructions to build documentation to generate_docs.py

* exclude python/odcs from cpp_distcheck