From 5703b38ffbfbfacd30c805d013af30632b7cd9d7 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Wed, 8 Nov 2017 10:03:03 -0800 Subject: [PATCH] api: Move usage instructions to their own page. --- .../zerver/api/installation-instructions.md | 149 ------------------ templates/zerver/api/sidebar.md | 1 + templates/zerver/api/usage.md | 149 ++++++++++++++++++ zerver/tests/test_docs.py | 3 +- 4 files changed, 152 insertions(+), 150 deletions(-) create mode 100644 templates/zerver/api/usage.md diff --git a/templates/zerver/api/installation-instructions.md b/templates/zerver/api/installation-instructions.md index 9f32343449..7275a1acb9 100644 --- a/templates/zerver/api/installation-instructions.md +++ b/templates/zerver/api/installation-instructions.md @@ -50,152 +50,3 @@ npm install zulip-js -### Usage examples -
- -
- -
-#### Stream message - -``` -curl {{ api_url }}/v1/messages \ - -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ - -d "type=stream" \ - -d "to=Denmark" \ - -d "subject=Castle" \ - -d "content=Something is rotten in the state of Denmark." -``` - -#### Private message -``` -curl {{ api_url }}/v1/messages \ - -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ - -d "type=private" \ - -d "to=hamlet@example.com" \ - -d "content=I come not, friends, to steal away your hearts." -``` -
- -
-```python -#!/usr/bin/env python - -import zulip -import sys - -# Keyword arguments 'email' and 'api_key' are not required if you are using ~/.zuliprc -client = zulip.Client(email="othello-bot@example.com", - api_key="a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5", - site="{{ api_url }}") - -# Send a stream message -client.send_message({ - "type": "stream", - "to": "Denmark", - "subject": "Castle", - "content": "Something is rotten in the state of Denmark." -}) -# Send a private message -client.send_message({ - "type": "private", - "to": "hamlet@example.com", - "content": "I come not, friends, to steal away your hearts." -}) - -# Print each message the user receives -# This is a blocking call that will run forever -client.call_on_each_message(lambda msg: sys.stdout.write(str(msg) + "\n")) - -# Print every event relevant to the user -# This is a blocking call that will run forever -# This will never be reached unless you comment out the previous line -client.call_on_each_event(lambda msg: sys.stdout.write(str(msg) + "\n")) -``` -
- -
You can use `zulip-send` -(available after you `pip install zulip`) to easily send Zulips from -the command-line, providing the message content via STDIN. - -#### Stream message - -```bash -zulip-send --stream Denmark --subject Castle \ - --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 -``` - -#### Private message - -```bash -zulip-send hamlet@example.com \ - --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 -``` - -#### Passing in the message on the command-line - -If you'd like, you can also provide the message on the command-line with the `-m` flag, as follows: - - -```bash -zulip-send --stream Denmark --subject Castle \ - -m "Something is rotten in the state of Denmark." \ - --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 -``` - -You can omit the `user` and `api-key` arguments if you have a `~/.zuliprc` file. - -See also the [full API endpoint documentation.](/api/endpoints). -
- -
-More examples and documentation can be found [here](https://github.com/zulip/zulip-js). -```js -const zulip = require('zulip'); - -const config = { - username: 'othello-bot@example.com', - apiKey: 'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5', - realm: '{{ api_url }}' -}; - -const client = zulip(config); - -// Send a message -client.messages.send({ - to: 'Denmark', - type: 'stream', - subject: 'Castle', - content: 'Something is rotten in the state of Denmark.' -}); - -// Send a private message -client.messages.send({ - to: 'hamlet@example.com', - type: 'private', - content: 'I come not, friends, to steal away your hearts.' -}); - -// Register queue to receive messages for user -client.queues.register({ - event_types: ['message'] -}).then((res) => { - // Retrieve events from a queue - // Blocking until there is an event (or the request times out) - client.events.retrieve({ - queue_id: res.queue_id, - last_event_id: -1, - dont_block: false - }).then(console.log); -}); -``` -
- -
- -
diff --git a/templates/zerver/api/sidebar.md b/templates/zerver/api/sidebar.md index edd84059df..7fce72812e 100644 --- a/templates/zerver/api/sidebar.md +++ b/templates/zerver/api/sidebar.md @@ -2,3 +2,4 @@ * [Installation instructions](/api-new/installation-instructions) * [API keys](/api-new/api-keys) +* [Usage](/api-new/usage) diff --git a/templates/zerver/api/usage.md b/templates/zerver/api/usage.md new file mode 100644 index 0000000000..7ba5f1a870 --- /dev/null +++ b/templates/zerver/api/usage.md @@ -0,0 +1,149 @@ +# Usage examples +
+ +
+ +
+#### Stream message + +``` +curl {{ api_url }}/v1/messages \ + -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ + -d "type=stream" \ + -d "to=Denmark" \ + -d "subject=Castle" \ + -d "content=Something is rotten in the state of Denmark." +``` + +#### Private message +``` +curl {{ api_url }}/v1/messages \ + -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ + -d "type=private" \ + -d "to=hamlet@example.com" \ + -d "content=I come not, friends, to steal away your hearts." +``` +
+ +
+```python +#!/usr/bin/env python + +import zulip +import sys + +# Keyword arguments 'email' and 'api_key' are not required if you are using ~/.zuliprc +client = zulip.Client(email="othello-bot@example.com", + api_key="a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5", + site="{{ api_url }}") + +# Send a stream message +client.send_message({ + "type": "stream", + "to": "Denmark", + "subject": "Castle", + "content": "Something is rotten in the state of Denmark." +}) +# Send a private message +client.send_message({ + "type": "private", + "to": "hamlet@example.com", + "content": "I come not, friends, to steal away your hearts." +}) + +# Print each message the user receives +# This is a blocking call that will run forever +client.call_on_each_message(lambda msg: sys.stdout.write(str(msg) + "\n")) + +# Print every event relevant to the user +# This is a blocking call that will run forever +# This will never be reached unless you comment out the previous line +client.call_on_each_event(lambda msg: sys.stdout.write(str(msg) + "\n")) +``` +
+ +
You can use `zulip-send` +(available after you `pip install zulip`) to easily send Zulips from +the command-line, providing the message content via STDIN. + +#### Stream message + +```bash +zulip-send --stream Denmark --subject Castle \ + --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 +``` + +#### Private message + +```bash +zulip-send hamlet@example.com \ + --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 +``` + +#### Passing in the message on the command-line + +If you'd like, you can also provide the message on the command-line with the `-m` flag, as follows: + + +```bash +zulip-send --stream Denmark --subject Castle \ + -m "Something is rotten in the state of Denmark." \ + --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 +``` + +You can omit the `user` and `api-key` arguments if you have a `~/.zuliprc` file. + +See also the [full API endpoint documentation.](/api/endpoints). +
+ +
+More examples and documentation can be found [here](https://github.com/zulip/zulip-js). +```js +const zulip = require('zulip'); + +const config = { + username: 'othello-bot@example.com', + apiKey: 'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5', + realm: '{{ api_url }}' +}; + +const client = zulip(config); + +// Send a message +client.messages.send({ + to: 'Denmark', + type: 'stream', + subject: 'Castle', + content: 'Something is rotten in the state of Denmark.' +}); + +// Send a private message +client.messages.send({ + to: 'hamlet@example.com', + type: 'private', + content: 'I come not, friends, to steal away your hearts.' +}); + +// Register queue to receive messages for user +client.queues.register({ + event_types: ['message'] +}).then((res) => { + // Retrieve events from a queue + // Blocking until there is an event (or the request times out) + client.events.retrieve({ + queue_id: res.queue_id, + last_event_id: -1, + dont_block: false + }).then(console.log); +}); +``` +
+ +
+ +
diff --git a/zerver/tests/test_docs.py b/zerver/tests/test_docs.py index 0718cc74cc..20f051245c 100644 --- a/zerver/tests/test_docs.py +++ b/zerver/tests/test_docs.py @@ -55,7 +55,8 @@ class DocPageTest(ZulipTestCase): self._test('/api/endpoints/', 'pre-built API bindings for') self._test('/api-new/', 'We hear you like APIs') self._test('/api-new/api-keys', 'you can use its email and API key') - self._test('/api-new/installation-instructions', 'Python Installation') + self._test('/api-new/installation-instructions', 'No download required!') + self._test('/api-new/usage', 'steal away your hearts') self._test('/team/', 'industry veterans') self._test('/history/', 'Cambridge, Massachusetts') # Test the i18n version of one of these pages.