[GSoD] Refactoring the documentation files of gRPC-Gateway (#1851)

* fixed edit this page broken links

* refactored md files

* refactored documentation files

* refactored documentation files

* added requested changes

* added requested changes

Author: iamrajiv

ADOPTERS.md

@@ -3,14 +3,14 @@
 This is a list of organizations that have spoken publicly about their adoption or
 production users that have added themselves (in alphabetical order):
 
-* [Ad Hoc](http://adhocteam.us/) uses the gRPC-Gateway to serve millions of
-    API requests per day.
-* [Chef](https://www.chef.io/) uses gRPC-Gateway to provide the user-facing
-    API of [Chef Automate](https://automate.chef.io/). Furthermore, the generated
-    OpenAPI data serves as the basis for its [API documentation](https://automate.chef.io/docs/api/).
-    The code is Open Source, [see `github.com/chef/automate`](https://github.com/chef/automate).
-* [Scaleway](https://www.scaleway.com/en/) uses the gRPC-Gateway since 2018 to
-    serve millions of API requests per day [1].
+- [Ad Hoc](http://adhocteam.us/) uses the gRPC-Gateway to serve millions of
+  API requests per day.
+- [Chef](https://www.chef.io/) uses gRPC-Gateway to provide the user-facing
+  API of [Chef Automate](https://automate.chef.io/). Furthermore, the generated
+  OpenAPI data serves as the basis for its [API documentation](https://automate.chef.io/docs/api/).
+  The code is Open Source, [see `github.com/chef/automate`](https://github.com/chef/automate).
+- [Scaleway](https://www.scaleway.com/en/) uses the gRPC-Gateway since 2018 to
+  serve millions of API requests per day [1].
 
 If you have adopted the gRPC-Gateway and would like to be included in this list,
 feel free to submit a PR.

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # How to contribute
 
-Thank you for your contribution to grpc-gateway.
+Thank you for your contribution to gRPC-Gateway.
 Here's the recommended process of contribution.
 
 1. `go get github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway`
@@ -16,13 +16,13 @@ Here's the recommended process of contribution.
 When you work on a larger contribution, it is also recommended that you get in touch
 with us through the issue tracker.
 
-### Code reviews
+## Code reviews
 
 All submissions, including submissions by project members, require review.
 
-### I want to regenerate the files after making changes
+## I want to regenerate the files after making changes
 
-#### Using Docker
+### Using Docker
 
 It should be as simple as this (run from the root of the repository):
 
@@ -42,7 +42,7 @@ docker run -itv $(pwd):/grpc-gateway -w /grpc-gateway --entrypoint /bin/bash --r
 You may need to authenticate with GitHub to pull `docker.pkg.github.com/grpc-ecosystem/grpc-gateway/build-env`.
 You can do this by following the steps on the [GitHub Package docs](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages#authenticating-to-github-packages).
 
-#### Using Visual Studio Code dev containers
+### Using Visual Studio Code dev containers
 
 This repo contains a `devcontainer.json` configuration that sets up the build environment in a container using
 [VS Code dev containers](https://code.visualstudio.com/docs/remote/containers). If you're using the dev container,
@@ -58,22 +58,22 @@ $ bazel run :gazelle -- update-repos -from_file=go.mod -to_macro=repositories.bz
     bazel run :buildifier
 ```
 
-Note that the above listed docker commands will not work in the dev container, since volume mounts from
-nested docker container are not possible.
+Note that the above-listed docker commands will not work in the dev container, since volume mounts from
+nested docker container is not possible.
 
 If this has resulted in some file changes in the repo, please ensure you check those in with your merge request.
 
-### Making a release
+## Making a release
 
 To make a release, follow these steps:
 
 1. Decide on a release version. The `gorelease` job can
-    recommend whether the new release should be a patch or minor release.
-    See [CircleCI](https://app.circleci.com/pipelines/github/grpc-ecosystem/grpc-gateway/126/workflows/255a8a04-de9c-46a9-a66b-f107d2b39439/jobs/6428)
-    for an example.
+   recommend whether the new release should be a patch or minor release.
+   See [CircleCI](https://app.circleci.com/pipelines/github/grpc-ecosystem/grpc-gateway/126/workflows/255a8a04-de9c-46a9-a66b-f107d2b39439/jobs/6428)
+   for an example.
 1. Generate a GitHub token with `repo` access.
 1. Create a new branch and edit the Makefile `changelog` job, settings
-    the `future-release=` variable to the name of the version you plan to release
+   the `future-release=` variable to the name of the version you plan to release
 1. Run `CHANGELOG_GITHUB_TOKEN=<yourtoken> make changelog`
 1. Commit the `Makefile` and `CHANGELOG.md` changes.
 1. Open a PR and check that everything looks right.

README.md

@@ -1,13 +1,19 @@
-# grpc-gateway
+<div align="center">
+<h1>gRPC-Gateway</h1>
+<p>grpc-gateway
+gRPC to JSON proxy generator following the gRPC HTTP spec
+</p>
+<a href="https://circleci.com/gh/grpc-ecosystem/grpc-gateway"><img src="https://img.shields.io/circleci/build/github/grpc-ecosystem/grpc-gateway?color=379c9c&logo=circleci&logoColor=ffffff&style=flat-square"/></a>
+<a href="https://codecov.io/gh/grpc-ecosystem/grpc-gateway"><img src="https://img.shields.io/codecov/c/github/grpc-ecosystem/grpc-gateway?color=379c9c&logo=codecov&logoColor=ffffff&style=flat-square"/></a>
+<a href="https://app.slack.com/client/T029RQSE6/CBATURP1D"><img src="https://img.shields.io/badge/slack-grpc--gateway-379c9c?logo=slack&logoColor=ffffff&style=flat-square"/></a>
+<a href="https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt"><img src="https://img.shields.io/github/license/grpc-ecosystem/grpc-gateway?color=379c9c&style=flat-square"/></a>
+<a href="https://github.com/grpc-ecosystem/grpc-gateway/releases"><img src="https://img.shields.io/github/v/release/grpc-ecosystem/grpc-gateway?color=379c9c&logoColor=ffffff&style=flat-square"/></a>
+<a href="https://github.com/grpc-ecosystem/grpc-gateway/stargazers"><img src="https://img.shields.io/github/stars/grpc-ecosystem/grpc-gateway?color=379c9c&style=flat-square"/></a>
+</div>
 
-[![circleci](https://img.shields.io/circleci/build/github/grpc-ecosystem/grpc-gateway?color=379c9c&logo=circleci&logoColor=ffffff&style=flat-square)](https://circleci.com/gh/grpc-ecosystem/grpc-gateway)
-[![codecov](https://img.shields.io/codecov/c/github/grpc-ecosystem/grpc-gateway?color=379c9c&logo=codecov&logoColor=ffffff&style=flat-square)](https://codecov.io/gh/grpc-ecosystem/grpc-gateway)
-[![slack](https://img.shields.io/badge/slack-grpc--gateway-379c9c?logo=slack&logoColor=ffffff&style=flat-square)](https://app.slack.com/client/T029RQSE6/CBATURP1D)
-[![license](https://img.shields.io/github/license/grpc-ecosystem/grpc-gateway?color=379c9c&style=flat-square)](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt)
-[![release](https://img.shields.io/github/v/release/grpc-ecosystem/grpc-gateway?color=379c9c&logoColor=ffffff&style=flat-square)](https://github.com/grpc-ecosystem/grpc-gateway/releases)
-[![stars](https://img.shields.io/github/stars/grpc-ecosystem/grpc-gateway?color=379c9c&style=flat-square)](https://github.com/grpc-ecosystem/grpc-gateway/stargazers)
+## About
 
-The grpc-gateway is a plugin of the Google protocol buffers compiler
+The gRPC-Gateway is a plugin of the Google protocol buffers compiler
 [protoc](https://github.com/protocolbuffers/protobuf).
 It reads protobuf service definitions and generates a reverse-proxy server which
 translates a RESTful HTTP API into gRPC. This server is generated according to the
@@ -23,13 +29,11 @@ This helps you provide your APIs in both gRPC and RESTful style at the same time
 ## Testimonials
 
 > We use the gRPC-Gateway to serve millions of API requests per day,
-> and have been since 2018, and through all of that,
+> and have been since 2018 and through all of that,
 > we have never had any issues with it.
 >
 > _- William Mill, [Ad Hoc](http://adhocteam.us/)_
 
-## Check out our [documentation](https://grpc-ecosystem.github.io/grpc-gateway/)!
-
 ## Background
 
 gRPC is great -- it generates API clients and server stubs in many programming
@@ -46,7 +50,7 @@ that's needed to generate a reverse-proxy with this library.
 
 ## Installation
 
-The grpc-gateway requires a local installation of the Google protocol buffers
+The gRPC-Gateway requires a local installation of the Google protocol buffers
 compiler `protoc` v3.0.0 or above. Please install this via your local package
 manager or by downloading one of the releases from the official repository:
 
@@ -151,7 +155,7 @@ Make sure that your `$GOBIN` is in your `$PATH`.
 
    1. Using the default mapping
 
-   This requires no additional modification to the `.proto` file, but does require enabling a specific option when executing the plugin.
+   This requires no additional modification to the `.proto` file but does require enabling a specific option when executing the plugin.
    The `generate_unbound_methods` should be enabled.
 
    Here's what a `protoc` execution might look like with this option enabled:
@@ -213,7 +217,7 @@ Make sure that your `$GOBIN` is in your `$PATH`.
    ```
 
    3. External configuration
-      If you do not want to (or cannot) modify the proto file for use with grpc-gateway you can
+      If you do not want to (or cannot) modify the proto file for use with gRPC-Gateway you can
       alternatively use an external
       [gRPC Service Configuration](https://cloud.google.com/endpoints/docs/grpc/grpc-service-config) file.
       [Check our documentation](https://grpc-ecosystem.github.io/grpc-gateway/docs/grpcapiconfiguration.html)
@@ -292,15 +296,15 @@ Make sure that your `$GOBIN` is in your `$PATH`.
 
 This GopherCon UK 2019 presentation from our maintainer
 [@JohanBrandhorst](https://github.com/johanbrandhorst) provides a good intro to
-using the grpc-gateway. It uses the following boilerplate repo as a base:
+using the gRPC-Gateway. It uses the following boilerplate repo as a base:
 https://github.com/johanbrandhorst/grpc-gateway-boilerplate.
 
 [![gRPC-Gateway presentation](https://img.youtube.com/vi/Pq1paKC-fXk/0.jpg)](https://www.youtube.com/watch?v=Pq1paKC-fXk)
 
 ## Parameters and flags
 
-During code generation with `protoc`, flags to grpc-gateway tools must be passed
-through protoc using one of 2 patterns:
+During code generation with `protoc`, flags to gRPC-Gateway tools must be passed
+through `protoc` using one of 2 patterns:
 
 - as part of the `--<tool_suffix>_out` `protoc` parameter: `--<tool_suffix>_out=<flags>:<path>`
 
@@ -325,12 +329,12 @@ through protoc using one of 2 patterns:
 Golang import paths. They are compatible with
 [the parameters with the same names in `protoc-gen-go`](https://github.com/golang/protobuf#parameters).
 
-In addition we also support the `request_context` parameter in order to use the
+In addition, we also support the `request_context` parameter in order to use the
 `http.Request`'s Context (only for Go 1.7 and above). This parameter can be
 useful to pass the request-scoped context between the gateway and the gRPC service.
 
 `protoc-gen-grpc-gateway` also supports some more command line flags to control
-logging. You can give these flags together with parameters above. Run
+logging. You can give these flags together with the parameters above. Run
 `protoc-gen-grpc-gateway --help` for more details about the flags.
 
 Similarly, `protoc-gen-openapiv2` supports command-line flags to control OpenAPI
@@ -342,9 +346,9 @@ files with options from
 [a_bit_of_everything.proto](examples/internal/proto/examplepb/a_bit_of_everything.proto)
 for examples.
 
-## More Examples
+## More examples
 
-More examples are available under `examples` directory.
+More examples are available under the `examples` directory.
 
 - `proto/examplepb/echo_service.proto`, `proto/examplepb/a_bit_of_everything.proto`, `proto/examplepb/unannotated_echo_service.proto`: service definition
   - `proto/examplepb/echo_service.pb.go`, `proto/examplepb/a_bit_of_everything.pb.go`, `proto/examplepb/unannotated_echo_service.pb.go`: [generated] stub of the service
@@ -365,7 +369,7 @@ gRPC-gateway, and a gRPC server, see
 - Generating JSON API handlers.
 - Method parameters in the request body.
 - Method parameters in the request path.
-- Method parameters in query string.
+- Method parameters in the query string.
 - Enum fields in the path parameter (including repeated enum fields).
 - Mapping streaming APIs to newline-delimited JSON streams.
 - Mapping HTTP headers with `Grpc-Metadata-` prefix to gRPC metadata (prefixed with `grpcgateway-`)
@@ -381,14 +385,14 @@ gRPC-gateway, and a gRPC server, see
 
 ### No plan to support
 
-But patch is welcome.
+But patches are welcome.
 
 - Method parameters in HTTP headers.
 - Handling trailer metadata.
 - Encoding request/response body in XML.
 - True bi-directional streaming.
 
-# Mapping gRPC to HTTP
+## Mapping gRPC to HTTP
 
 - [How gRPC error codes map to HTTP status codes in the response](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/runtime/errors.go#L15).
 - HTTP request source IP is added as `X-Forwarded-For` gRPC request header.
@@ -404,11 +408,11 @@ But patch is welcome.
   [jsonpb](https://pkg.go.dev/github.com/golang/protobuf/jsonpb) with
   `OrigName: true`.
 
-# Contribution
+## Contribution
 
 See [CONTRIBUTING.md](http://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md).
 
-# License
+## License
 
-grpc-gateway is licensed under the BSD 3-Clause License.
+gRPC-Gateway is licensed under the BSD 3-Clause License.
 See [LICENSE.txt](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/LICENSE.txt) for more details.

docs/_config.yml

@@ -77,17 +77,17 @@ gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub"
 gh_edit_repository: "https://github.com/grpc-ecosystem/grpc-gateway" # the github URL for your repo
 gh_edit_branch: "master" # the branch that your docs is served from
-# gh_edit_source: docs # the source that your files originate from
+gh_edit_source: docs # the source that your files originate from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
 
 # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
 color_scheme: nil
 
 # Disqus Comments
 # disqus:
-  # Leave shortname blank to disable comments site-wide.
-  # Enable comments for any post by adding `comments: true` to that post's YAML Front Matter.
-  # shortname:
+# Leave shortname blank to disable comments site-wide.
+# Enable comments for any post by adding `comments: true` to that post's YAML Front Matter.
+# shortname:
 
 # Google Analytics Tracking
 # e.g, UA-1234567-89

docs/docs/contributing/contributing.md

@@ -0,0 +1,9 @@
+---
+layout: default
+title: Getting Started
+parent: Contributing
+---
+
+# How to contribute
+
+See CONTRIBUTING in [CONTRIBUTING.md](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md).

docs/docs/contributing/getting_started.md

@@ -1,19 +1,19 @@
 ---
 layout: default
-title: Adding the grpc-gateway annotations to an existing protobuf file
+title: Adding gRPC-Gateway annotations to an existing proto file
+nav_order: 4
 parent: Tutorials
-nav_order: 5
 ---
 
-# Adding the grpc-gateway annotations to an existing protobuf file
+# Adding gRPC-Gateway annotations to an existing proto file
 
-Now that we've got a working Go gRPC server, we need to add the grpc-gateway annotations.
+Now that we've got a working Go gRPC server, we need to add the gRPC-Gateway annotations.
 
 The annotations define how gRPC services map to the JSON request and response. When using protocol buffers, each RPC must define the HTTP method and path using the `google.api.http` annotation.
 
-So we will need to add the `google/api/http.proto` import to the proto file. We also need to add the HTTP->gRPC mapping we want. In this case, we're mapping `POST /v1/example/echo` to our `SayHello` rpc.
+So we will need to add the `google/api/http.proto` import to the proto file. We also need to add the HTTP->gRPC mapping we want. In this case, we're mapping `POST /v1/example/echo` to our `SayHello` RPC.
 
-```proto
+```protobuf
 syntax = "proto3";
 
 package helloworld;
@@ -44,11 +44,11 @@ message HelloReply {
 
 See [a_bit_of_everything.proto](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto) for examples of more annotations you can add to customize gateway behavior.
 
-## Generating the grpc-gateway stubs
+## Generating the gRPC-Gateway stubs
 
-Now that we've got the grpc-gateway annotations added to the proto file, we need to use the grpc-gateway generator to generate the stubs.
+Now that we've got the gRPC-Gateway annotations added to the proto file, we need to use the gRPC-Gateway generator to generate the stubs.
 
-Before we can do that, we need to copy some dependencies into our protofile structure. Copy the `third_party/googleapis` folder from the grpc-gateway repository to your local protofile structure. It should look like this afterwards:
+Before we can do that, we need to copy some dependencies into our proto file structure. Copy the `third_party/googleapis` folder from the gRPC-Gateway repository to your local proto file structure. It should look like this afterwards:
 
 ```
 proto
@@ -62,9 +62,9 @@ proto
 
 ### Using buf
 
-We'll need to add the grpc-gateway generator to the generation configuration:
+We'll need to add the gRPC-Gateway generator to the generation configuration:
 
-```yml
+```yaml
 version: v1beta1
 plugins:
   - name: go
@@ -86,9 +86,9 @@ $ buf generate
 
 It should produce a `*.gw.pb.go` file.
 
-### Using protoc
+### Using `protoc`
 
-Now we need to add the grpc-gateway generator to the protoc invocation:
+Now we need to add the gRPC-Gateway generator to the `protoc` invocation:
 
 ```sh
 $ protoc -I ./proto \
@@ -100,7 +100,7 @@ $ protoc -I ./proto \
 
 This should generate a `*.gw.pb.go` file.
 
-We also need to add and serve the gRPC-gateway mux in our `main.go` file.
+We also need to add and serve the gRPC-Gateway mux in our `main.go` file.
 
 ```go
 package main

docs/docs/tutorials/adding_annotations.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: Creating main.go
+nav_order: 3
 parent: Tutorials
-nav_order: 4
 ---
 
 # Creating main.go

docs/docs/tutorials/creating_main.go.md

@@ -2,7 +2,7 @@
 layout: default
 title: Generating stubs
 parent: Tutorials
-nav_order: 3
+nav_order: 2
 has_children: true
 ---