29c83baecc
* 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
212 lines
4.1 KiB
Plaintext
212 lines
4.1 KiB
Plaintext
# autogen.sh-generated files
|
|
Makefile.in
|
|
src/Makefile.in
|
|
config.guess
|
|
config.h.in
|
|
config.sub
|
|
configure
|
|
depcomp
|
|
install-sh
|
|
ltmain.sh
|
|
missing
|
|
|
|
aclocal.m4
|
|
m4/libtool.m4
|
|
m4/ltoptions.m4
|
|
m4/ltsugar.m4
|
|
m4/ltversion.m4
|
|
m4/lt~obsolete.m4
|
|
autom4te.cache
|
|
|
|
# downloaded files
|
|
/gmock
|
|
|
|
# in-tree configure-generated files
|
|
Makefile
|
|
src/Makefile
|
|
/config.h
|
|
config.log
|
|
config.status
|
|
|
|
libtool
|
|
protobuf-lite.pc
|
|
protobuf.pc
|
|
.deps
|
|
stamp-h1
|
|
|
|
# in-tree build products
|
|
*.o
|
|
*.lo
|
|
*.la
|
|
src/.libs
|
|
*.so
|
|
|
|
.dirstamp
|
|
|
|
any_test.pb.*
|
|
map*unittest.pb.*
|
|
unittest*.pb.*
|
|
cpp_test*.pb.*
|
|
src/google/protobuf/util/**/*.pb.cc
|
|
src/google/protobuf/util/**/*.pb.h
|
|
|
|
*.pyc
|
|
*.egg-info
|
|
*_pb2.py
|
|
python/**/*.egg
|
|
python/.eggs/
|
|
python/.tox
|
|
python/build/
|
|
python/docs/_build/
|
|
|
|
src/js_embed
|
|
src/protoc
|
|
src/unittest_proto_middleman
|
|
|
|
# vim generated
|
|
*.swp
|
|
|
|
# Generated test scaffolding
|
|
src/no_warning_test.cc
|
|
src/no-warning-test
|
|
src/protobuf*-test
|
|
src/test_plugin
|
|
src/testzip.*
|
|
src/zcg*zip
|
|
ar-lib
|
|
|
|
test-driver
|
|
compile
|
|
|
|
src/**/*.log
|
|
src/**/*.trs
|
|
|
|
# JavaBuild output.
|
|
java/core/target
|
|
java/util/target
|
|
javanano/target
|
|
java/.idea
|
|
java/**/*.iml
|
|
|
|
# Windows native output.
|
|
cmake/build
|
|
build_msvc
|
|
|
|
# NuGet packages: we want the repository configuration, but not the
|
|
# packages themselves.
|
|
/csharp/src/packages/*/
|
|
|
|
# OS X's Finder creates these for state about opened windows/etc.
|
|
**/.DS_Store
|
|
|
|
# Cocoapods artifacts
|
|
# Podfile.lock and the workspace file are tracked, to ease deleting them. That's
|
|
# needed to trigger "pod install" to rerun the preinstall commands.
|
|
Pods/
|
|
|
|
# Comformance test output
|
|
conformance/.libs/
|
|
conformance/com/
|
|
conformance/conformance-cpp
|
|
conformance/conformance-csharp
|
|
conformance/conformance-java
|
|
conformance/conformance-objc
|
|
conformance/conformance-test-runner
|
|
conformance/conformance.pb.cc
|
|
conformance/conformance.pb.h
|
|
conformance/Conformance.pbobjc.h
|
|
conformance/Conformance.pbobjc.m
|
|
conformance/conformance_pb.js
|
|
conformance/conformance_pb.rb
|
|
conformance/core
|
|
conformance/failing_tests.txt
|
|
conformance/google/
|
|
conformance/google-protobuf/
|
|
conformance/javac_middleman
|
|
conformance/lite/
|
|
conformance/nonexistent_tests.txt
|
|
conformance/protoc_middleman
|
|
conformance/succeeding_tests.txt
|
|
conformance/Conformance/
|
|
conformance/GPBMetadata/
|
|
conformance/Google/
|
|
conformance/Protobuf_test_messages/
|
|
conformance/conformance-php
|
|
conformance/conformance-php-c
|
|
conformance/*.class
|
|
|
|
# php test output
|
|
composer.lock
|
|
php/tests/generated/
|
|
php/tests/old_protoc
|
|
php/tests/protobuf/
|
|
php/tests/core
|
|
php/tests/vgcore*
|
|
php/tests/multirequest.result
|
|
php/tests/nohup.out
|
|
php/ext/google/protobuf/.libs/
|
|
php/ext/google/protobuf/Makefile.fragments
|
|
php/ext/google/protobuf/Makefile.global
|
|
php/ext/google/protobuf/Makefile.objects
|
|
php/ext/google/protobuf/acinclude.m4
|
|
php/ext/google/protobuf/build/
|
|
php/ext/google/protobuf/config.h
|
|
php/ext/google/protobuf/config.h.in~
|
|
php/ext/google/protobuf/config.nice
|
|
php/ext/google/protobuf/configure.ac
|
|
php/ext/google/protobuf/configure.in
|
|
php/ext/google/protobuf/mkinstalldirs
|
|
php/ext/google/protobuf/run-tests.php
|
|
vendor/
|
|
|
|
# JavaScript artifacts
|
|
js/commonjs_out/
|
|
js/compatibility_tests/v3.0.0/commonjs_out*
|
|
js/compatibility_tests/v3.0.0/protoc
|
|
js/compatibility_tests/v3.0.0/testproto_libs1.js
|
|
js/compatibility_tests/v3.0.0/testproto_libs1_new.js
|
|
js/compatibility_tests/v3.0.0/testproto_libs2.js
|
|
js/compatibility_tests/v3.0.0/testproto_libs2_new.js
|
|
js/deps.js
|
|
js/google-protobuf.js
|
|
js/google/
|
|
js/node_modules/
|
|
js/testproto_libs1.js
|
|
js/testproto_libs2.js
|
|
|
|
# Ignore the bazel symlinks
|
|
/bazel-*
|
|
|
|
# ruby test output
|
|
ruby/lib/
|
|
ruby/tests/basic_test_pb.rb
|
|
ruby/tests/basic_test_proto2_pb.rb
|
|
ruby/tests/generated_code_pb.rb
|
|
ruby/tests/test_import_pb.rb
|
|
ruby/tests/test_ruby_package_pb.rb
|
|
ruby/tests/generated_code_proto2_pb.rb
|
|
ruby/tests/test_import_proto2_pb.rb
|
|
ruby/tests/test_ruby_package_proto2_pb.rb
|
|
ruby/Gemfile.lock
|
|
ruby/compatibility_tests/v3.0.0/protoc
|
|
ruby/compatibility_tests/v3.0.0/tests/generated_code_pb.rb
|
|
ruby/compatibility_tests/v3.0.0/tests/test_import_pb.rb
|
|
|
|
# IntelliJ CLion Config files and build output
|
|
cmake/.idea
|
|
cmake/cmake-build-debug/
|
|
|
|
# Common build subdirectories.
|
|
./.build/
|
|
./_build/
|
|
|
|
# Visual Studio 2017
|
|
.vs
|
|
|
|
# Visual Studio Code
|
|
/.vscode/
|
|
|
|
# IntelliJ
|
|
.idea
|
|
*.iml
|