Skip to content

Instantly share code, notes, and snippets.

@MSurfer20

MSurfer20/Enhancing Zulip API Documentation Framework.md

Last active August 23, 2021 13:18
Star
Embed
What would you like to do?
Learn more about clone URLs
Download ZIP
GSoC '21 Report
Raw
Enhancing Zulip API Documentation Framework.md

Work Product: Google Summer of Code 2021 with Zulip

I'm Suyash Vardhan Mathur, and I have been working on the project Enhancing Zulip API Documentation Framework under the GSoC'21 program at Zulip. As GSoC comes to an end, I would like to thank Tim Abbott, Steve Howell, Anders Kaseorg, my mentors Aditya Verma and Kartik Srivastava for their continuous guidance, reviews and for helping me out whenever I was stuck. I am also thankful to the entire Zulip community and Google for the amazing learning opportunity of participating in Google Summer of Code. This journey would've been impossible without the continuous support of the Zulip community, that helped me grow throughout the summer and has helped me become a better developer.

The goal of my project was to enhance the Zulip API documentation framework and work in related areas to improve Zulip. As GSoC concludes, I am elated to have 86 merged commits in zulip/zulip, having contributed in various areas like writing markdown extensions, dabbling with frontend, understanding and writing code for Zulip's event management system and backend, writing documentation, and much more.

Summary

Github profile: MSurfer20
Respositories contributed to: zulip/zulip & zulip/python-zulip-api
Pull Requests opened in zulip/zulip during GSoC
Commits made in zulip/zulip during GSoC
Pull Requests opened in zulip/python-zulip-api during GSoC

I achieved a lot of goals during the summer, such as:

  • Removed the redundant templates for API docs pages: Despite having its REST API documented using OpenAPI standard data, Zulip's actual docs were generated through different Markdown templates for each endpoint. These templates had different information hardcoded, and the testing and example generating systems too were dependent on these Markdown files. As a part of this project, the framework was modified to generate the docs directly from OpenAPI data and delete these 60 redundant templates. At each migration step, the diff of HTML pages was checked to ensure the migration happened properly. This also reduced the effort of adding a Markdown template when documenting a new endpoint. The culmination of this work happened in #18573.
  • Integrated OpenAPI Generator: Wrote code to integrate OpenAPI generator into Github Actions and auto-push the bindings for 137 languages in the to-be-created zulip/zulip-openapi repo. The Github Actions is configured to make commits to the repo only when changes happen in the auto-generated docs. The PR related to this is yet to be merged.
  • Worked on Zulip's backend & API: I worked on some backend issues, the highlight of which was writing the backend for the feature to mark messages as unread in #19307. This work involved writing code in Zulip's real-time events system, and the event was then applied on the client-side to sync the unread messages. I also worked on adding support for an API endpoint to fetch user-status for a given user ID.
  • Increased endpoint coverage by docs: Added the OpenAPI data and python examples for various high-priority endpoints which increased the endpoint coverage by Zulip's API docs.
  • Improved Zulip's frontend: I also managed to do some work in the direction of improving the frontend and UI of API docs in #19595 and #19175. This work involved changing the UI of get-events page to make the individual events collapsible, which made the documentation page much more organized and navigable. Also, I changed the title of responses to be auto-generated using the code of the response, and to have the response codes visually represented in the docs.
  • Along with the above-mentioned work, I also fixed various bugs I discovered along the way as well as made different enhancements to Zulip.

During the Application period, I was able to fix various bugs in Zulip's OpenAPI data and its framework, added the feature of parsing and rendering the data type of each variable in the docs, and made other enhancements to Zulip.

Pull Requests merged during Coding Period

Unmerged Pull Requests opened during Coding Period

Open/Merged Pull Requests made during Application Period

Closing Notes

GSoC was a great learning experience, as I worked with various kinds of technologies throughout the summer. The most satisfying bit was seeing my work getting merged, knowing that the code that I wrote would be useful to the numerous users and developers of Zulip.

In future, I would continue contributing to Zulip and exploring new and exciting areas in the project, and would also try my utmost to help newcomers get involved with Zulip and Open Source in general. I look forward to continuing association with Zulip and Open Source.

~ Suyash Vardhan Mathur

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment