protobuf

Protocol Buffers - Google's data interchange format (grpc依赖) https://developers.google.com/protocol-buffers/

Tag: Branch: Tree: dec4939439

David L. Jones 6f129c123e Update docs so we can generate better output from Sphinx. (#7295 ) This change updates docstrings and comments so that they will produce nicer formatting and cross-references from Sphinx. There are a few broad categories of changes: - Paramter and attribute docs are updated so that types will be recognized by Napoleon (https://sphinxcontrib-napoleon.readthedocs.io/en/latest/) This usually just means moving a colon in the docstring, so `name: (type) description` becomes `name (type): description`. - References to other symbols can be cross-references if they have the right format. For example, "attr_name" might become ":attr:`attr_name`". https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects - For fenced code blocks, adding a double-colon `::` signifies a literal block. https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks - Some bits of docstrings move from docstring to comments. For TODOs, this means we won't be putting stale (or otherwise unrelated) noise into the docs. For `Message.DESCRIPTOR`, the change means it gets appropriate documentation. - There are some wording tweaks for consistency, and some new docstrings (especially for methods in Message). For types, I used the convention of `list[Foo]` and `dict(foo, bar)`, which seem to be common among other Python rst docstrings. Sphinx should generally recognize both, and cross-links them correctly (both internally and to Python library documentation). Upgrading to Python3-style type annotations would allow us to use `sphinx-autodoc-typehints`; the changes in this commit are very similar to typing-based hints.	5 years ago
..
protobuf	Update docs so we can generate better output from Sphinx. (#7295 )	5 years ago
__init__.py	Add a modified patch from craigcitro@ to handle namespace sharing.	9 years ago

Update docs so we can generate better output from Sphinx. (#7295 )

This change updates docstrings and comments so that they will produce nicer
formatting and cross-references from Sphinx. There are a few broad categories of
changes:

- Paramter and attribute docs are updated so that types will be recognized by
Napoleon (https://sphinxcontrib-napoleon.readthedocs.io/en/latest/) This
usually just means moving a colon in the docstring, so
`name: (type) description` becomes `name (type): description`.

- References to other symbols can be cross-references if they have the right
format. For example, "attr_name" might become ":attr:`attr_name`".
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects

- For fenced code blocks, adding a double-colon `::` signifies a literal block.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks

- Some bits of docstrings move from docstring to comments. For TODOs, this
means we won't be putting stale (or otherwise unrelated) noise into the docs.
For `Message.DESCRIPTOR`, the change means it gets appropriate documentation.

- There are some wording tweaks for consistency, and some new docstrings
(especially for methods in Message).

For types, I used the convention of `list[Foo]` and `dict(foo, bar)`, which seem
to be common among other Python rst docstrings. Sphinx should generally
recognize both, and cross-links them correctly (both internally and to Python
library documentation). Upgrading to Python3-style type annotations would allow
us to use `sphinx-autodoc-typehints`; the changes in this commit are very
similar to typing-based hints.

5 years ago

protobuf

Update docs so we can generate better output from Sphinx. (#7295 )

5 years ago

__init__.py

Add a modified patch from craigcitro@ to handle namespace sharing.

9 years ago