Chiebot-Mirror
/
protobuf
mirror of https://github.com/protocolbuffers/protobuf.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity
Protocol Buffers - Google's data interchange format (grpc依赖) https://developers.google.com/protocol-buffers/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
8000 Commits
204 Branches
352 Tags
257 MiB
Tag: Branch: Tree: 4008d229aa
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '4008d229aa'
${ noResults }
protobuf/python/docs/index.rst

64 lines
1.9 KiB
Raw Normal View History Unescape

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
5 years ago
.. Protocol Buffers documentation master file, created by
sphinx-quickstart on Thu Aug 15 13:56:43 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
python: publish sphinx docs to read the docs Background: This is a follow-up to the PR that adds sphinx docs. Read the Docs is a hosting platform for documentation, primarily Python docs. It supports builds at commit time as well as at specific git labels to support versioned docs. I have claimed the protobuf.readthedocs.io project and can add any Googlers who need access to be able to configure and trigger builds. https://readthedocs.org/projects/protobuf/builds/ It's also relatively easy to create a new project to test the documentation builds from a fork, such as https://readthedocs.org/projects/tswast-protobuf/builds/ About this change: Once web hooks are configured, Read the Docs will automatically build the docs for the latest changes on the master branch. I needed to update `python/setup.py` to support installation from the root of the repository because Read the Docs does not `cd python` before installing the protobuf package with `setup.py install`. To support this, I updated the file paths to use the absolute path to files. The `__file__` special variable comes in handy for this, as it provides the path to the `setup.py` file. A banner is added to the docs when published to readthedocs. This links to the official documentation and the future home of the stable API reference on googleapis.dev.
5 years ago
.. ifconfig:: build_env == 'readthedocs'
.. warning::
You are reading the documentation for the `latest committed changes
<https://github.com/protocolbuffers/protobuf/tree/master/python>`_ of
the `Protocol Buffers package for Python
<https://developers.google.com/protocol-buffers/docs/pythontutorial>`_.
Some features may not yet be released. Read the documentation for the
latest released package at `googleapis.dev
<https://googleapis.dev/python/protobuf/latest/>`_.
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
5 years ago
Protocol Buffers Python API Reference
=====================================
The complete documentation for Protocol Buffers is available via the web at:
https://developers.google.com/protocol-buffers/
Modules and Packages
--------------------
.. START REFTOC, generated by generate_docs.py.
.. toctree::
google/protobuf
google/protobuf/any_pb2
google/protobuf/descriptor
google/protobuf/descriptor_database
google/protobuf/descriptor_pb2
google/protobuf/descriptor_pool
google/protobuf/duration_pb2
google/protobuf/empty_pb2
google/protobuf/field_mask_pb2
Sync from Piper @308829107 PROTOBUF_SYNC_PIPER
5 years ago
google/protobuf/internal/containers
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
5 years ago
google/protobuf/json_format
google/protobuf/message
google/protobuf/message_factory
google/protobuf/proto_builder
google/protobuf/reflection
google/protobuf/service
google/protobuf/service_reflection
google/protobuf/struct_pb2
google/protobuf/symbol_database
google/protobuf/text_encoding
google/protobuf/text_format
google/protobuf/timestamp_pb2
google/protobuf/type_pb2
google/protobuf/wrappers_pb2
.. END REFTOC.
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`