This is the project report for Refactoring the Existing Docs Site of gRPC-Gateway which was completed during Google Season of Docs 2020. The status of the project can be regarded as complete due to the fact that all pull requests have been merged and all the initial premises of the project have been fulfilled.
The final work product can be found at https://grpc-ecosystem.github.io/grpc-gateway/.
- Bi-weekly meeting schedule agreed.
- gRPC-Gateway slack channel invite was arranged.
- Focus in the first three weeks before the start of the project was on:
- Working through existing documentation and noting gaps areas.
- Putting together a timeline for the three months of the project, with weekly milestones.
- Gone through all the documentation-based Jekyll themes across various sites.
- Made a document with a comparison between different themes considered.
- Selected the Jekyll theme which suits the best for gRPC-Gateway.
- Deployed the theme to my gRPC-Gateway fork.
- Imported all the existing contents of the old website to the new website.
- Made the first draft of the Landing Page.
- Added contents on the Landing page.
- Added section for Release Notes and Changelog.
- Added Commenting System.
- Added a script to generate the Changelog file automatically from the gRPC-Gateway repository.
- Made a basic gRPC-Gateway installation with a Go backend server ready.
- Created a basic arithmetic gRPC server frontend that uses gRPC-Gateway.
- Added notes to the new Installation guide in the process of learning and installing.
- Deployed the basic arithmetic gRPC server online.
- Imported new contents from the main gRPC-Gateway repository to my gRPC-Gateway fork after the merge of branch v2 to master.
- Created a new Tutorials directory.
- Added documentation about generating gRPC stub via both
bufandprotocin the tutorials directory and made sure that all the commands required to generate basic protobuf files are present. - Added documentation on creating the basic protos with HTTP annotations and included a lot of links of https://google.aip.dev/127.
- Created a hello world program that uses gRPC-Gateway.
- Made an empty
main.gothat has enough to run the binary. - Made an HTTP server. Added a
net/httphandler that renders the wordhello world. - Installed the gRPC-Gateway handler in the HTTP handler. Tested the server by giving a single cURL command to view it.
- Added documentation in Tutorials directory on hello world program and how to use gRPC-Gateway in it.
- Added more FAQ entries.
- Added a new architecture introduction diagram and removed the old one.
- Checked and fixed indentations, grammatical errors, typographical errors, and broken links across all the files including both previous and new documentations.
- Finalized the project deliverables and refactored the code if any, based on the feedback.
- Made the project report and requested mentors to review the project report.
- Finalized and submitted the project report.
- Submitted the evaluation of the project and the experience working with the mentors.
My mentors suggested I work on my gRPC-Gateway fork and make all the changes there and make pull requests after I got a large number of changes rather than making a separate pull request for every change.
These are my pull request which holds all my project deliverables:
| Link | Description |
|---|---|
| #1786 | This pull request holds work from week 1 to week 5 which is based on the new Jekyll theme added to the documentation website of gRPC-Gateway. |
| #1829 | This pull request holds work from week 6 to week 10 which is based on the new Tutorials directory of gRPC-Gateway which is made on basis of the hello world program and basic arithmetic gRPC server program. |
| #1844 | This pull request holds work of week 11 which is on FAQ entries. |
| #1845 | This pull request holds work of week 11 which is on the architecture introduction diagram. |
| #1851 | This pull request holds work of week 11 which is on refactoring the documentation files. |
Works that are not yet added or not sure to be added are:
- Adding section for Release Notes and Changelog.
- Adding Commenting System.
- Adding a script to generate the Changelog file automatically from the gRPC-Gateway repository.
| Meeting No. | Date and Time |
|---|---|
| 1 | Saturday, August 22, 2020⋅8:30 – 9:00pm |
| 2 | Saturday, September 12, 2020⋅9:00 – 9:30pm |
| 3 | Saturday, September 26, 2020⋅9:00 – 9:30pm |
| 4 | Saturday, October 10, 2020⋅9:00 – 9:30pm |
| 5 | Saturday, October 24, 2020⋅9:00 – 9:30pm |
| 6 | Saturday, November 7, 2020⋅10:00 – 10:30pm |
| 7 | Saturday, November 14, 2020⋅10:00 – 10:30pm |
| 8 | Saturday, November 21, 2020⋅10:00 – 10:30pm |
| 9 | Saturday, November 28, 2020⋅10:00 – 10:30pm |
| 10 | Saturday, December 5, 2020⋅10:00 – 10:30pm |
All dates and times are in Indian Standard Time (IST) with a time offset of UTC+05:30.
I am very glad that I had the opportunity to take part in the Google Season of Docs program. Participating in this program has helped me to:
- Got involved with an amazing community i.e. gRPC-Gateway.
- Learned about gRPC and gRPC-Gateway.
- Learned a lot of tools like Docker, Postman and Swagger UI, etc.
- Worked on Go server and protobuf files.
I am deeply grateful to my mentors Johan Brandhorst-Satzkorn and Andrew Z Allen, who guided me patiently through the project and was always ready to help, review work in progress, gave feedback regarding the overall shape of the project and the feasibility of certain solutions, and maintained a very friendly, supportive, and stimulating atmosphere on the team. They devoted a lot of time to this project and led the fortnightly video meetings in a well-organized, yet non-stressful manner. Their support and positivity helped me through this project and made me enjoy every bit of it. The project could not be completed without the generous feedback and help from the team. Last but not least, I would like to thank Google and Google Season of Docs organizers for this initiative.