[READ ONLY MIRROR] Envoy REST/proto API definitions and documentation. (grpc依赖)
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.
 
 
 
 
 

77 lines
3.1 KiB

# Contributing guide
## API changes
All API changes should follow the [style guide](STYLE.md).
API changes are regular PRs in https://github.com/envoyproxy/envoy for the API/configuration
changes. They may be as part of a larger implementation PR. Please follow the standard Bazel and CI
process for validating build/test sanity of `api/` before submitting a PR.
*Note: New .proto files should be also included to [build.sh](https://github.com/envoyproxy/envoy/blob/master/docs/build.sh) and
[BUILD](https://github.com/envoyproxy/envoy/blob/master/api/docs/BUILD) in order to get the RSTs generated.*
## Documentation changes
The Envoy project takes documentation seriously. We view it as one of the reasons the project has
seen rapid adoption. As such, it is required that all features have complete documentation. This is
generally going to be a combination of API documentation as well as architecture/overview
documentation.
### Building documentation locally
The documentation can be built locally in the root of https://github.com/envoyproxy/envoy via:
```
docs/build.sh
```
Or to use a hermetic Docker container:
```
./ci/run_envoy_docker.sh './ci/do_ci.sh docs'
```
This process builds RST documentation directly from the proto files, merges it with the static RST
files, and then runs [Sphinx](https://www.sphinx-doc.org/en/stable/rest.html) over the entire tree to
produce the final documentation. The generated RST files are not committed as they are regenerated
every time the documentation is built.
### Viewing documentation
Once the documentation is built, it is available rooted at `generated/docs/index.html`. The
generated RST files are also viewable in `generated/rst`.
Note also that the generated documentation can be viewed in CI:
1. Open docs job in CircleCI.
2. Navigate to "artifacts" tab.
3. Expand files and click on `index.html`.
If you do not see an artifacts tab this is a bug in CircleCI. Try logging out and logging back in.
### Documentation guidelines
The following are some general guidelines around documentation.
* Cross link as much as possible. Sphinx is fantastic at this. Use it! See ample examples with the
existing documentation as a guide.
* Please use a **single space** after a period in documentation so that all generated text is
consistent.
* Comments can be left inside comments if needed (that's pretty deep, right?) via the `[#comment:]`
special tag. E.g.,
```
// This is a really cool field!
// [#comment:TODO(mattklein123): Do something cooler]
string foo_field = 3;
```
* Prefer *italics* for emphasis as `backtick` emphasis is somewhat jarring in our Sphinx theme.
* All documentation is expected to use proper English grammar with proper punctuation. If you are
not a fluent English speaker please let us know and we will help out.
* Tag messages/enum/files with `[#proto-status: draft|experimental|frozen]` to
reflect their [API
status](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/v2_overview#status).
Frozen entities do not need to be tagged except when overriding an outer scope
draft or experimental status.