api docs: Move code examples farther up.

templates/zerver/api/add-subscriptions.md

@@ -4,10 +4,6 @@ Subscribe one or more users to one or more streams.
 
 `POST {{ api_url }}/v1/users/me/subcriptions`
 
-## Arguments
-
-{generate_api_arguments_table|arguments.json|add-subscriptions.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -107,6 +103,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+{generate_api_arguments_table|arguments.json|add-subscriptions.md}
+
 ## Response
 
 #### Return values

templates/zerver/api/create-user.md

@@ -6,10 +6,6 @@ Create a new user in a realm.
 
 `POST {{ api_url }}/v1/users`
 
-## Arguments
-
-{generate_api_arguments_table|arguments.json|create-user.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -81,6 +77,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+{generate_api_arguments_table|arguments.json|create-user.md}
+
 ## Response
 
 #### Example response

templates/zerver/api/delete-queue.md

@@ -4,10 +4,6 @@ Delete a previously registered queue.
 
 `DELETE {{ api_url }}/v1/events`
 
-## Arguments
-
-{generate_api_arguments_table|arguments.json|delete-queue.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -74,6 +70,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+{generate_api_arguments_table|arguments.json|delete-queue.md}
+
 ## Response
 
 #### Example response

templates/zerver/api/get-all-streams.md

@@ -4,12 +4,6 @@ Get all streams that the user has access to.
 
 `GET {{ api_url }}/v1/streams`
 
-## Arguments
-
-**Note**: The following arguments are all URL query parameters.
-
-{generate_api_arguments_table|arguments.json|get-all-streams.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -77,6 +71,12 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+**Note**: The following arguments are all URL query parameters.
+
+{generate_api_arguments_table|arguments.json|get-all-streams.md}
+
 ## Response
 
 #### Return values

templates/zerver/api/get-all-users.md

@@ -4,12 +4,6 @@ Retrieve all users in a realm.
 
 `GET {{ api_url }}/v1/users`
 
-## Arguments
-
-**Note**: The following arguments are all URL query parameters.
-
-{generate_api_arguments_table|arguments.json|get-all-users.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -81,6 +75,12 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+**Note**: The following arguments are all URL query parameters.
+
+{generate_api_arguments_table|arguments.json|get-all-users.md}
+
 ## Response
 
 #### Return values

templates/zerver/api/get-events-from-queue.md

@@ -6,20 +6,6 @@ This endpoint allows you to receive new events from an event queue that
 can be created by
 [requesting the `{{ api_url}}/v1/register` endpoint](/api/register-queue).
 
-## Arguments
-
-{generate_api_arguments_table|arguments.json|get-events-from-queue.md}
-
-**Note**: The arguments documented above are optional in the sense that
-even if you haven't registered a queue by explicitly requesting the
-`{{ api_url}}/v1/register` endpoint, you could pass the arguments for
-[the `{{ api_url}}/v1/register` endpoint](/api/register-queue) to this
-endpoint and a queue would be registered in the absence of a `queue_id`.
-
-You may also pass in the following keyword arguments to `call_on_each_event`:
-
-{generate_api_arguments_table|arguments.json|call_on_each_event}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -107,6 +93,20 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+{generate_api_arguments_table|arguments.json|get-events-from-queue.md}
+
+**Note**: The arguments documented above are optional in the sense that
+even if you haven't registered a queue by explicitly requesting the
+`{{ api_url}}/v1/register` endpoint, you could pass the arguments for
+[the `{{ api_url}}/v1/register` endpoint](/api/register-queue) to this
+endpoint and a queue would be registered in the absence of a `queue_id`.
+
+You may also pass in the following keyword arguments to `call_on_each_event`:
+
+{generate_api_arguments_table|arguments.json|call_on_each_event}
+
 ## Response
 
 #### Return values

templates/zerver/api/get-profile.md

@@ -4,10 +4,6 @@ Get the profile of the user/bot that requests this endpoint.
 
 `GET {{ api_url }}/v1/users/me`
 
-## Arguments
-
-This endpoint takes no arguments.
-
 ## Usage examples
 
 <div class="code-section" markdown="1">
@@ -66,6 +62,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+This endpoint takes no arguments.
+
 ## Response
 
 #### Return values

templates/zerver/api/get-stream-id.md

@@ -4,12 +4,6 @@ Get the unique ID of a given stream.
 
 `GET {{ api_url }}/v1/get_stream_id`
 
-## Arguments
-
-**Note**: The following arguments are all URL query parameters.
-
-{generate_api_arguments_table|arguments.json|get-stream-id.md}
-
 ## Usage examples
 
 <div class="code-section" markdown="1">
@@ -64,6 +58,12 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+**Note**: The following arguments are all URL query parameters.
+
+{generate_api_arguments_table|arguments.json|get-stream-id.md}
+
 ## Response
 
 #### Return values

templates/zerver/api/get-subscribed-streams.md

@@ -4,10 +4,6 @@ Get all streams that the user is subscribed to.
 
 `GET {{ api_url }}/v1/users/me/subscriptions`
 
-## Arguments
-
-This request takes no arguments.
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -64,6 +60,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+This request takes no arguments.
+
 ## Response
 
 #### Return values

templates/zerver/api/private-message.md

@@ -4,10 +4,6 @@ Send a private message to a user or multiple users.
 
 `POST {{ api_url }}/v1/messages`
 
-## Arguments
-
-{generate_api_arguments_table|arguments.json|private-message.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -90,6 +86,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+{generate_api_arguments_table|arguments.json|private-message.md}
+
 ## Response
 
 #### Return values

templates/zerver/api/register-queue.md

@@ -10,10 +10,6 @@ from this endpoint can be used in a subsequent call to the
 
 `POST {{ api_url }}/v1/register`
 
-## Arguments
-
-{generate_api_arguments_table|arguments.json|register-queue.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -80,6 +76,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+{generate_api_arguments_table|arguments.json|register-queue.md}
+
 ## Response
 
 #### Return values

templates/zerver/api/remove-subscriptions.md

@@ -4,10 +4,6 @@ Unsubscribe yourself or other users from one or more streams.
 
 `DELETE {{ api_url }}/v1/users/me/subcriptions`
 
-## Arguments
-
-{generate_api_arguments_table|arguments.json|remove-subscriptions.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -93,6 +89,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+{generate_api_arguments_table|arguments.json|remove-subscriptions.md}
+
 #### Return values
 
 * `removed`: A list of the names of streams which were unsubscribed from as

templates/zerver/api/render-message.md

@@ -4,10 +4,6 @@ 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">
@@ -66,6 +62,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+{generate_api_arguments_table|arguments.json|render-message.md}
+
 ## Response
 
 #### Return values

templates/zerver/api/stream-message.md

@@ -4,10 +4,6 @@ Send a message to a stream.
 
 `POST {{ api_url }}/v1/messages`
 
-## Arguments
-
-{generate_api_arguments_table|arguments.json|stream-message.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -105,6 +101,10 @@ zulip(config).then((client) => {
 
 </div>
 
+## Arguments
+
+{generate_api_arguments_table|arguments.json|stream-message.md}
+
 ## Response
 
 #### Return values

templates/zerver/api/update-message.md

@@ -7,18 +7,6 @@ Edit/update the content or topic of a message.
 `<msg_id>` in the above URL should be replaced with the ID of the
 message you wish you update.
 
-## Permissions
-
-You only have permission to edit a message if:
-
-1. You sent it, **OR**:
-2. This is a topic-only edit for a (no topic) message, **OR**:
-3. This is a topic-only edit and you are an admin.
-
-## Arguments
-
-{generate_api_arguments_table|arguments.json|update-message.md}
-
 ## Usage examples
 <div class="code-section" markdown="1">
 <ul class="nav">
@@ -83,6 +71,18 @@ zulip(config).then((client) => {
 
 </div>
 
+## Permissions
+
+You only have permission to edit a message if:
+
+1. You sent it, **OR**:
+2. This is a topic-only edit for a (no topic) message, **OR**:
+3. This is a topic-only edit and you are an admin.
+
+## Arguments
+
+{generate_api_arguments_table|arguments.json|update-message.md}
+
 ## Response
 
 #### Example response