From b31bdf23ca243dd75bc9bc730232011c0f9221de Mon Sep 17 00:00:00 2001
From: Eeshan Garg <jerryguitarist@gmail.com>
Date: Fri, 29 Dec 2017 22:27:12 -0330
Subject: [PATCH] api docs: Document the POST /api/v1/messages/render endpoint.

Note that currently, there is no way to interface with this
endpoint using zulip-js.
---
 templates/zerver/api/arguments.json    |  8 +++
 templates/zerver/api/render-message.md | 80 ++++++++++++++++++++++++++
 templates/zerver/api/sidebar.md        |  1 +
 3 files changed, 89 insertions(+)
 create mode 100644 templates/zerver/api/render-message.md

diff --git a/templates/zerver/api/arguments.json b/templates/zerver/api/arguments.json
index 0675206918..89a468940d 100644
--- a/templates/zerver/api/arguments.json
+++ b/templates/zerver/api/arguments.json
@@ -78,5 +78,13 @@
             "required":"Required",
             "example":"Denmark"
         }
+    ],
+    "render-message.md":[
+        {
+            "argument":"content",
+            "description":"The content of the message.",
+            "required":"Required",
+            "example":"**foo**"
+        }
     ]
 }
diff --git a/templates/zerver/api/render-message.md b/templates/zerver/api/render-message.md
new file mode 100644
index 0000000000..a0990ea2a2
--- /dev/null
+++ b/templates/zerver/api/render-message.md
@@ -0,0 +1,80 @@
+# Render message
+
+Render a message to HTML.
+
+`POST {{ api_url }}/v1/messages/render`
+
+## Arguments
+
+{generate_api_arguments_table|arguments.json|render-message.md}
+
+## Usage examples
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="curl">curl</li>
+<li data-language="python">Python</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl {{ api_url }}/v1/messages/render \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+    -d "content=**foo**"
+
+```
+</div>
+
+<div data-language="python" markdown="1">
+```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 }}")
+
+# Render a message
+print(client.render_message({"content": "**foo**"}))
+```
+</div>
+
+</div>
+
+</div>
+
+## Response
+
+#### Return values
+
+* `rendered`: The rendered HTML.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+```
+{
+    'result':'success',
+    'msg':'',
+    'rendered':'<p><strong>foo</strong></p>'
+}
+```
+
+A typical JSON response for when the required argument `content`
+is not supplied:
+
+```
+{
+    'code':'REQUEST_VARIABLE_MISSING',
+    'result':'error',
+    'msg':"Missing 'content' argument",
+    'var_name':'content'
+}
+```
+
+{!invalid-api-key-json-response.md!}
diff --git a/templates/zerver/api/sidebar.md b/templates/zerver/api/sidebar.md
index 4a8bc00c08..452f56eb2a 100644
--- a/templates/zerver/api/sidebar.md
+++ b/templates/zerver/api/sidebar.md
@@ -7,6 +7,7 @@
 
 * [Stream message](/api/stream-message)
 * [Private message](/api/private-message)
+* [Render message](/api/render-message)
 
 #### Streams