diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 84e7edd29b..5483f68a6a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,8 +31,8 @@ needs doing: [desktop app](https://github.com/zulip/zulip-electron). * Building out our [Python API and bots](https://github.com/zulip/python-zulip-api) framework. -* [Writing an integration](https://zulip.readthedocs.io/en/latest/tutorials/integration-guide.html). -* Improving our [user](https://chat.zulip.org/help/) or +* [Writing an integration](https://zulipchat.com/api/integration-guide). +* Improving our [user](https://zulipchat.com/help/) or [developer](https://zulip.readthedocs.io/en/latest/) documentation. * [Reviewing code](https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html) and manually testing pull requests. diff --git a/docs/overview/directory-structure.md b/docs/overview/directory-structure.md index fccdca854d..8d4f3fea61 100644 --- a/docs/overview/directory-structure.md +++ b/docs/overview/directory-structure.md @@ -25,7 +25,8 @@ paths will be familiar to Django developers. * `zerver/views/*.py` Most [Django views](https://docs.djangoproject.com/en/1.8/topics/http/views/). -* `zerver/webhooks/` Webhook views and tests for [Zulip webhook integrations](../tutorials/integration-guide.html). +* `zerver/webhooks/` Webhook views and tests for [Zulip webhook integrations]( + https://zulipchat.com/api/integration-guide). * `zerver/tornado/views.py` Tornado views. diff --git a/docs/subsystems/client.md b/docs/subsystems/client.md index 5d0552d1ad..355e76b9ce 100644 --- a/docs/subsystems/client.md +++ b/docs/subsystems/client.md @@ -35,4 +35,4 @@ object as `request.client`. In most integrations, `request.client` is then passed to `check_send_stream_message`, where it is used to keep track of which client sent the message (which in turn is used by analytics). For more -information, see [the webhook walkthrough](../tutorials/webhook-walkthrough.html). +information, see [the webhook walkthrough](https://zulipchat.com/api/webhook-walkthrough). diff --git a/docs/subsystems/custom-apps.md b/docs/subsystems/custom-apps.md index d9241182df..5d3faf323f 100644 --- a/docs/subsystems/custom-apps.md +++ b/docs/subsystems/custom-apps.md @@ -177,7 +177,7 @@ you basically have to solve these problems: Zulip actually supports a bunch of integrations out-of-the-box that perform as **World Readers**. -The [three different integration models](../tutorials/integration-guide.html#types-of-integrations) +The [three different integration models](https://zulipchat.com/api/integration-guide#types-of-integrations) basically differ in where they perform the main functions of a **World Reader**. diff --git a/docs/images/helloworld-webhook.png b/static/images/api/helloworld-webhook.png similarity index 100% rename from docs/images/helloworld-webhook.png rename to static/images/api/helloworld-webhook.png diff --git a/docs/tutorials/integration-docs-guide.md b/templates/zerver/api/integration-docs-guide.md similarity index 100% rename from docs/tutorials/integration-docs-guide.md rename to templates/zerver/api/integration-docs-guide.md diff --git a/docs/tutorials/integration-guide.md b/templates/zerver/api/integration-guide.md similarity index 92% rename from docs/tutorials/integration-guide.md rename to templates/zerver/api/integration-guide.md index a10af258c9..e5cf812036 100644 --- a/docs/tutorials/integration-guide.md +++ b/templates/zerver/api/integration-guide.md @@ -15,11 +15,11 @@ On this page you'll find: * Details about writing [Python script and plugin integrations](#python-script-and-plugin-integrations). * A guide to - [documenting your integration](integration-docs-guide.html) is on a + [documenting your integration](integration-docs-guide) is on a separate page. A detailed walkthrough of a simple "Hello World" integration can be -found in the [webhook walkthrough](../tutorials/webhook-walkthrough.html). +found in the [webhook walkthrough](webhook-walkthrough). Contributions to this guide are very welcome, so if you run into any issues following these instructions or come up with any tips or tools @@ -99,7 +99,7 @@ New Zulip webhook integrations can take just a few hours to write, including tests and documentation, if you use the right process. **For detailed instructions, check out the ["Hello World" webhook walkthrough]( -../tutorials/webhook-walkthrough.html)**. +webhook-walkthrough)**. For a quick guide, read on. @@ -130,8 +130,8 @@ For a quick guide, read on. test-backend zerver/webhooks/pagerduty/ ``` - See [this guide](../testing/testing.html) for more details on the Zulip test - runner. + 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 @@ -142,7 +142,7 @@ For a quick guide, read on. the service. * Finally, write documentation for the integration; there's a - [detailed guide](integration-docs-guide.html). + [detailed guide](integration-docs-guide). ### Files that need to be created @@ -152,22 +152,24 @@ for a webhook named 'MyWebHook'. * `static/images/integrations/logos/mywebhook.svg`: An image to represent your integration in the user interface. Generally this should be the logo of the platform/server/product you are integrating. See [Documenting your - integration](integration-docs-guide.html) for details. + integration](integration-docs-guide) for details. * `static/images/integrations/mywebbook/001.svg`: A screen capture of your integration for use in the user interface. You can add as many images as needed to effectively document your webhook integration. See [Documenting your - integration](integration-docs-guide.html) for details. + integration](integration-docs-guide) for details. * `zerver/webhooks/mywebhook/fixtures/messagetype.json`: Sample json payload data used by tests. Add one fixture file per type of message supported by your - integration. See [Testing and writing tests](../testing/testing.html) for details. + integration. See [Testing and writing tests]( + https://zulip.readthedocs.io/en/latest/testing/testing.html) for details. * `zerver/webhooks/mywebhook/__init__.py`: Empty file that is obligatory part of every python package. Remember to `git add` it. * `zerver/webhooks/mywebhook/view.py`: Includes the main webhook integration function including any needed helper functions. * `zerver/webhooks/mywebhook/tests.py`: Add tests for your - webbook. See [Testing and writing tests](../testing/testing.html) for details. + webbook. See [Testing and writing tests]( + https://zulip.readthedocs.io/en/latest/testing/testing.html) for details. * `zerver/webhooks/mywebhook/doc.html`: Add end-user documentation. See - [Documenting your integration](integration-docs-guide.html) for details. + [Documenting your integration](integration-docs-guide) for details. ### Files that need to be updated diff --git a/templates/zerver/api/sidebar.md b/templates/zerver/api/sidebar.md index 3d9a50519e..a8a0a790fd 100644 --- a/templates/zerver/api/sidebar.md +++ b/templates/zerver/api/sidebar.md @@ -6,14 +6,14 @@ ## Integrations -* [Overview](https://zulip.readthedocs.io/en/latest/tutorials/integration-guide.html) +* [Overview](/api/integration-guide) * [Existing integrations](/integrations) ## Writing webhook integrations -* [Overview](https://zulip.readthedocs.io/en/latest/tutorials/integration-guide.html#webhook-integrations) -* [Walkthrough](https://zulip.readthedocs.io/en/latest/tutorials/webhook-walkthrough.html) -* [Documenting integrations](https://zulip.readthedocs.io/en/latest/tutorials/integration-docs-guide.html) +* [Overview](/api/integration-guide#webhook-integrations) +* [Walkthrough](/api/webhook-walkthrough) +* [Documenting integrations](/api/integration-docs-guide) ## Interactive bots (experimental) diff --git a/docs/tutorials/webhook-walkthrough.md b/templates/zerver/api/webhook-walkthrough.md similarity index 94% rename from docs/tutorials/webhook-walkthrough.md rename to templates/zerver/api/webhook-walkthrough.md index 2ff4b9b4ae..11aa89695f 100644 --- a/docs/tutorials/webhook-walkthrough.md +++ b/templates/zerver/api/webhook-walkthrough.md @@ -40,7 +40,7 @@ for each distinct message condition your webhook supports. You'll also need a corresponding fixture for each of these tests. Depending on the type of data the 3rd party service sends, your fixture may contain JSON, URL encoded text, or some other kind of data. See [Step 4: Create tests](#step-4-create-tests) or -[Testing](../testing/testing.html) for further details. +[Testing](https://zulip.readthedocs.io/en/latest/testing/testing.html) for further details. ## Step 1: Initialize your webhook python package @@ -94,7 +94,8 @@ The above code imports the required functions and defines the main webhook function `api_helloworld_webhook`, decorating it with `api_key_only_webhook_view` and `has_request_variables`. The `has_request_variables` decorator allows you to access request variables with `REQ()`. You can find more about `REQ` and request -variables in [Writing views](writing-views.html#request-variables). +variables in [Writing views]( +https://zulip.readthedocs.io/en/latest/tutorials/writing-views.html#request-variables). You must pass the name of your webhook to the `api_key_only_webhook_view` decorator so your webhook can access the `user_profile` and `request.client` @@ -124,8 +125,8 @@ it must exist before a message can be created in it. (See [Step 4: Create tests](#step-4-create-tests) for how to handle this in tests.) The line that begins `# type` is a mypy type annotation. See [this -page](../contributing/mypy.html) for details about how to properly annotate your webhook -functions. +page](https://zulip.readthedocs.io/en/latest/contributing/mypy.html) for details about +how to properly annotate your webhook functions. In the body of the function we define the body of the message as `Hello! I am happy to be here! :smile:`. The `:smile:` indicates an emoji. Then we append a @@ -204,7 +205,7 @@ After which you should see: Using either method will create a message in Zulip: -![Image of Hello World webhook message](../images/helloworld-webhook.png) + ## Step 4: Create tests @@ -332,7 +333,7 @@ The Hello World webhook will use the `test` stream, which is created by default in the Zulip dev environment. If you are running Zulip in production, you should make sure that this stream exists. -Next, on your {{ ../subsystems/settings.html|safe }}, create a Hello World bot. +Next, on your {{ settings_html|safe }}, create a Hello World bot. Construct the URL for the Hello World bot using the API key and stream name: @@ -362,7 +363,7 @@ Markdown/Jinja2 framework that includes macros for common instructions in Zulip's webhooks/integrations documentation. See -[our guide on documenting an integration](integration-docs-guide.html) +[our guide on documenting an integration](integration-docs-guide) for further details, including how to easily create the message screenshot. @@ -373,11 +374,14 @@ available in the Zulip product, follow these steps to prepare your pull request: 1. Run tests including linters and ensure you have addressed any issues they - report. See [Testing](../testing/testing.html) and [Linters](../testing/linters.html) for details. -2. Read through [Code styles and conventions](../contributing/code-style.html) and take a look + report. See [Testing](https://zulip.readthedocs.io/en/latest/testing/testing.html) + and [Linters](https://zulip.readthedocs.io/en/latest/testing/linters.html) for details. +2. Read through [Code styles and conventions]( + https://zulip.readthedocs.io/en/latest/contributing/code-style.html) and take a look through your code to double-check that you've followed Zulip's guidelines. 3. Take a look at your git history to ensure your commits have been clear and - logical (see [Version Control](../contributing/version-control.html) for tips). If not, + logical (see [Version Control]( + https://zulip.readthedocs.io/en/latest/contributing/version-control.html) for tips). If not, consider revising them with `git rebase --interactive`. For most webhooks, you'll want to squash your changes into a single commit and include a good, clear commit message. @@ -386,10 +390,11 @@ request: If you would like feedback on your integration as you go, feel free to post a message on the [public Zulip instance](https://chat.zulip.org/#narrow/stream/bots). -You can also create a [`[WIP]` pull request](../overview/contributing.html#working-on-an-issue) -while you are still working on your integration. See the -[Git guide](../contributing/git-guide.html#create-a-pull-request) for more on Zulip's pull -request process. +You can also create a [`[WIP]` pull request]( +https://zulip.readthedocs.io/en/latest/overview/contributing.html#working-on-an-issue) while you +are still working on your integration. See the +[Git guide](https://zulip.readthedocs.io/en/latest/contributing/git-guide.html#create-a-pull-request) +for more on Zulip's pull request process. ## Advanced topics diff --git a/templates/zerver/api/writing-bots.md b/templates/zerver/api/writing-bots.md index 8c2fb5abbf..1dd31bd435 100644 --- a/templates/zerver/api/writing-bots.md +++ b/templates/zerver/api/writing-bots.md @@ -4,9 +4,7 @@ Zulip's API supports a few different ways of integrating with a third-party service. * **Incoming webhook integrations**, for when you just want notifications from - a tool to be sent into Zulip. See the - [integrations guide]( - https://zulip.readthedocs.io/en/latest/tutorials/integration-guide.html?highlight=integrations). + a tool to be sent into Zulip. See the [integrations guide](integration-guide). * **Interactive bots**, for when you want the tool to react to messages in Zulip. diff --git a/templates/zerver/help/getting-your-organization-started-with-zulip.md b/templates/zerver/help/getting-your-organization-started-with-zulip.md index a1ed546bf2..6ae2354cc9 100644 --- a/templates/zerver/help/getting-your-organization-started-with-zulip.md +++ b/templates/zerver/help/getting-your-organization-started-with-zulip.md @@ -139,7 +139,7 @@ you use! A few recommendations: GitHub or wiki page with a nice badge. - [Automatically linkify](/help/add-a-custom-linkification-filter) issue numbers and commit IDs. -- [Write custom integrations](https://zulip.readthedocs.io/en/latest/tutorials/integration-guide.html) +- [Write custom integrations](https://zulipchat.com/api/integration-guide) for your community’s unique tools. - If your users primarily speak a language other than English, [set a default language for your organization](/help/change-the-default-language-for-your-organization). diff --git a/templates/zerver/integrations/index.html b/templates/zerver/integrations/index.html index 77eb626617..64c4f9a0c1 100644 --- a/templates/zerver/integrations/index.html +++ b/templates/zerver/integrations/index.html @@ -108,7 +108,7 @@ {% endif %} {% endfor %} - +