* 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
* Add scripts to test multirequest
* chmod ug+x multirequest.sh
* Add continuous test
* Compile c extension
* Class entry is obsolete in the second request
1) Needes to use class name in persistent map
2) Invalidate class entry stored in descriptor
* Add new files to dist
* Fix compile_extension
* Cleanup outputs for phpize
* Avoid initializing primitive fields in layout_init
* Avoid initializing string/bytes/message fields in layout_init
* Lazily create map when needed
* Lazily create repeated fields
* Change layout_init to only do memcpy
* Fix test for php-7.0
* Fix conformance test where default value of string/message map is not encoded
* Fix test for zts
* Clean up
* Fix comments
* Add binary conformance tests for map fields
* Update failure list
* Fix php conformance test
* Fix php conformance test
In 32-bit platform, int64 should be string. However, map iterator returns string key as integer.
* Add more test cases for map
* Update failure list
* Inherit from message instead of implement
When regestering class (implmenets other class) during MINIT, zend_class_implements
would call zend_class_entry->interface_gets_implemented(). In PHP-7.3 interface_gets_implemented shares the same location with create_object.
However, during MINIT, the global object storeage hasn't been initialized. And thus, caused segment fault in php 7.3.
* Use zend_string_init where interned string may be the value.
zend_string_dup will keep using the existing interned string.
In php 7.3, interned string cannot be destroyed from user's code.
* Uncommment debug code
* Use latest phpunit for each php versions
* Revert change in Dockerfile
* Update php test to use the new docker image
* Update composer
* Change docker organization
* Update phpunit
* Debug phpunit
* Store phpunit into bin dir in docker image
* Install valgrind to docker
* Fix compatibility test
* Remove generated_service_test from compatibility c extension test
* Update 32bit php test to the new docker image
* Install bison
* Fix build.sh
* Fix DOCKERIMAGE_PREFIX
* Fix basename
* Add comment to build_and_run_docker2.sh
* Remove commented code
* Fix comments
* Add support for primitive types in setters
* Update to address PR feedback
* Add tests and fixes for repeated fields
* Remove repeated field code, add getters
* Cleanup, test getters and oneofs
* Move boxing logic into separate class
* Add tests for wrapper type constructor args
* Update to add new setXXXValue methods
* Fix tests for invalid values
* Fix c extension for wrapper accessors
* Fix the bug that well known types didn't call Message_construct
* Address PR comments
* Refactoring init message with array logic
* Add include path to protoc
* Add missing TSRM_LS defintion
* Fix TSRM_LS
* Fix dist check
This change only adds basic proto2 support without advanced features
like extensions, custom options, maps, etc.
The protoc binary now generates ruby code for proto2 syntax.
However, for now, it is restricted to proto2 files without advanced features
like extensions, in which case it still errors out.
This change also modifies the DSL to add proto messages to the DescriptorPool.
There is a new DSL Builder#add_file to create a new FileDescriptor. With this,
the generated ruby DSL looks something like:
Google::Protobuf::DescriptorPool.generated_pool.build do
add_file "test.proto" do
add_message "foo" do
optional :val, :int32, 1
end
end
end
The compiler and util subpackages are created by the build_py class in
setup.py. This has caused an issue in the protobuf package in
conda-forge (https://github.com/conda-forge/protobuf-feedstock/issues/40),
which is fixed by this commit.
* Reserve unknown in ruby
* Revert ruby tests. Wait for cpp impl for conformance test
* Add conformance test for preserving unknown
* Add unknown field conformance test to csharp failure list.
* Fix comments
* Fix comment
* Fix comments
* Fix typo
* Use stringsink_string directly
* Mark hd unused
* Remove unused encodeunknown_handlerfunc
* Fix ruby segment fault
1) rb_ary_new cannot be called during allocate function. During allocate
fucntion, the containing object hasn't been marked and rb_ary_new may
invoke gc to collect containing object.
2) The global map should be marked before allocating it. Otherwise it
may be garbage collected.
* Add test
* Remove commented code
* Fix grammer error
Until now this file was just checked into the repo, but actually it
should be generated from any.js, struct.js, and timestamp.js. This
change updates the build system to make this happen. To make it work I
also had to remove some C++11 features from embed.cc.
This pull request includes two implementation: C extension and PHP
package. Both implementations support encode/decode of singular,
repeated and map fields.
Add note about JSON tests maybe being wrong.
- Add note about the JSON test maybe not being correct yet.
- Add test to checks the generated names for double underscores to be sure they
are what is expected.
- Update ruby conformance generation for rename of generated files that seems
to have happened.
- Update gitignores for the above and for the no-warnings-test.
- Hopefully complete the deps for other languages for the generated conformance proto sources.
- List the generated sources for cleanup by make's clean rules.
- Make the toplevel nuke the pyc files that can get created in the ObjC dir.
