From 9284d3283745be12e78fb4190d3ac4cdbce10836 Mon Sep 17 00:00:00 2001 From: Viraat Chandra Date: Fri, 26 Jan 2018 18:07:54 +0530 Subject: [PATCH] docs: Improve consistency and quality of API Documentation. --- templates/zerver/api/integration-guide.md | 13 ++++++------- templates/zerver/api/running-bots.md | 2 +- templates/zerver/api/webhook-walkthrough.md | 12 ++++++------ templates/zerver/api/writing-bots.md | 5 ++--- 4 files changed, 15 insertions(+), 17 deletions(-) diff --git a/templates/zerver/api/integration-guide.md b/templates/zerver/api/integration-guide.md index e5cf812036..90eb15e35a 100644 --- a/templates/zerver/api/integration-guide.md +++ b/templates/zerver/api/integration-guide.md @@ -2,8 +2,8 @@ Integrations are one of the most important parts of a group chat tool like Zulip, and we are committed to making integrating with Zulip and -getting you integration merged upstream so everyone else can benefit -from it as easy as possible while maintaining the high quality of the +getting your integration merged upstream so that everyone else can benefit +from it, as easy as possible while maintaining the high quality of the Zulip integrations library. On this page you'll find: @@ -37,8 +37,8 @@ products, ordered here by which types we prefer to write: content to a particular URI on our site with data about the event. For these, you usually just need to create a new python package in the `zerver/webhooks/` directory. You can easily find recent - commits adding new integrations to crib from via `git log - zerver/webhooks/`. + commits adding new integrations to crib from via + `git log zerver/webhooks/`. 2. **[Python script integrations](#python-script-and-plugin-integrations)** (examples: SVN, Git), where we can get the service to call our integration @@ -125,13 +125,12 @@ For a quick guide, read on. without ever needing to post directly from the service you're integrating with to your Zulip development machine. You can run just the tests for one integration like this: - ``` test-backend zerver/webhooks/pagerduty/ ``` - See [this guide](https://zulip.readthedocs.io/en/latest/testing/testing.html) - for more details on the Zulip test runner. + *Hint: See [this guide](https://zulip.readthedocs.io/en/latest/testing/testing.html) + for more details on the Zulip test runner.* * Once you've gotten your webhook working and passing a test, capture payloads for the other common types of posts the service's webhook diff --git a/templates/zerver/api/running-bots.md b/templates/zerver/api/running-bots.md index 8ef949df55..c86083e45e 100644 --- a/templates/zerver/api/running-bots.md +++ b/templates/zerver/api/running-bots.md @@ -1,7 +1,7 @@ # Interactive bots Zulip's API has a powerful framework for interactive bots that react -the messages in Zulip. This page documents how to run a bot +to messages in Zulip. This page documents how to run a bot implemented using that framework, both on your laptop for quick testing as well in a production server environment. diff --git a/templates/zerver/api/webhook-walkthrough.md b/templates/zerver/api/webhook-walkthrough.md index a9f373d45b..dbcbcb8b17 100644 --- a/templates/zerver/api/webhook-walkthrough.md +++ b/templates/zerver/api/webhook-walkthrough.md @@ -1,9 +1,9 @@ # Webhook walkthrough -Below explains each part of a simple webhook integration, called **Hello -World**. This webhook sends a "hello" message to the `test` stream and includes -a link to the Wikipedia article of the day, which it formats from json data it -receives in the http request. +Below, we explain each part of a simple webhook integration, called +**Hello World**. This webhook sends a "hello" message to the `test` +stream and includes a link to the Wikipedia article of the day, which +it formats from json data it receives in the http request. Use this walkthrough to learn how to write your first webhook integration. @@ -47,8 +47,8 @@ some other kind of data. See [Step 4: Create tests](#step-4-create-tests) or In the `zerver/webhooks/` directory, create new subdirectory that will contain all of corresponding code. In our example it will be `helloworld`. The new directory will be a python package, so you have -to create an empty `__init__.py` file in that directory via e.g. `touch -zerver/webhooks/helloworld/__init__.py`. +to create an empty `__init__.py` file in that directory via e.g. +`touch zerver/webhooks/helloworld/__init__.py`. ## Step 2: Create main webhook code diff --git a/templates/zerver/api/writing-bots.md b/templates/zerver/api/writing-bots.md index 402258633b..6bdf8b1d7e 100644 --- a/templates/zerver/api/writing-bots.md +++ b/templates/zerver/api/writing-bots.md @@ -8,9 +8,8 @@ third-party service. * **Interactive bots**, for when you want the tool to react to messages in Zulip. -* This guide is about writing and testing interactive bots. We assume - familiarity with our - [guide for running bots](running-bots). +This guide is about writing and testing interactive bots. We assume +familiarity with our [guide for running bots](running-bots). On this page you'll find: