From dbacc00f0f4a4e854d255014b584c58dcdf83d4d Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Tue, 31 Jan 2023 12:11:45 +0100 Subject: [PATCH] api-docs: Move markdown files to top level directory. - Updates `.prettierignore` for the new directory. - Updates any reference to the API documentation directory for markdown files to be `api_docs/` instead of `zerver/api/`. - Removes a reference link from `docs/documentation/api.md` that hasn't referenced anything in the text since commit 0542c60. - Update rendering of API documentation for new directory. --- .prettierignore | 1 + .../api => api_docs}/api-doc-template.md | 0 .../zerver/api => api_docs}/api-keys.md | 0 .../zerver/api => api_docs}/changelog.md | 0 .../api => api_docs}/client-libraries.md | 0 .../configuring-python-bindings.md | 0 .../api => api_docs}/construct-narrow.md | 0 .../zerver/api => api_docs}/create-stream.md | 0 .../zerver/api => api_docs}/deploying-bots.md | 0 .../include/api-admin-only.md | 0 .../zerver/api => api_docs}/include/empty.md | 0 .../include/rest-endpoints.md | 0 .../incoming-webhooks-overview.md | 0 .../incoming-webhooks-walkthrough.md | 0 {templates/zerver/api => api_docs}/index.md | 0 .../installation-instructions.md | 0 .../api => api_docs}/integrations-overview.md | 0 .../api => api_docs}/mark-all-as-read.md | 0 {templates/zerver/api => api_docs}/missing.md | 0 .../non-webhook-integrations.md | 0 .../api => api_docs}/outgoing-webhooks.md | 0 .../api => api_docs}/real-time-events.md | 0 .../api => api_docs}/rest-error-handling.md | 0 {templates/zerver/api => api_docs}/rest.md | 0 .../api => api_docs}/roles-and-permissions.md | 0 .../zerver/api => api_docs}/running-bots.md | 0 .../zerver/api => api_docs}/send-message.md | 0 .../zerver/api => api_docs}/sidebar_index.md | 0 .../zerver/api => api_docs}/writing-bots.md | 0 docs/documentation/api.md | 23 +++-- docs/tutorials/new-feature-tutorial.md | 6 +- templates/zerver/documentation_main.html | 4 +- tools/linter_lib/custom_check.py | 2 +- tools/release | 4 +- version.py | 4 +- zerver/lib/templates.py | 2 +- zerver/openapi/test_curl_examples.py | 6 +- zerver/views/documentation.py | 84 +++++++++---------- zproject/urls.py | 4 +- 39 files changed, 69 insertions(+), 71 deletions(-) rename {templates/zerver/api => api_docs}/api-doc-template.md (100%) rename {templates/zerver/api => api_docs}/api-keys.md (100%) rename {templates/zerver/api => api_docs}/changelog.md (100%) rename {templates/zerver/api => api_docs}/client-libraries.md (100%) rename {templates/zerver/api => api_docs}/configuring-python-bindings.md (100%) rename {templates/zerver/api => api_docs}/construct-narrow.md (100%) rename {templates/zerver/api => api_docs}/create-stream.md (100%) rename {templates/zerver/api => api_docs}/deploying-bots.md (100%) rename {templates/zerver/api => api_docs}/include/api-admin-only.md (100%) rename {templates/zerver/api => api_docs}/include/empty.md (100%) rename {templates/zerver/api => api_docs}/include/rest-endpoints.md (100%) rename {templates/zerver/api => api_docs}/incoming-webhooks-overview.md (100%) rename {templates/zerver/api => api_docs}/incoming-webhooks-walkthrough.md (100%) rename {templates/zerver/api => api_docs}/index.md (100%) rename {templates/zerver/api => api_docs}/installation-instructions.md (100%) rename {templates/zerver/api => api_docs}/integrations-overview.md (100%) rename {templates/zerver/api => api_docs}/mark-all-as-read.md (100%) rename {templates/zerver/api => api_docs}/missing.md (100%) rename {templates/zerver/api => api_docs}/non-webhook-integrations.md (100%) rename {templates/zerver/api => api_docs}/outgoing-webhooks.md (100%) rename {templates/zerver/api => api_docs}/real-time-events.md (100%) rename {templates/zerver/api => api_docs}/rest-error-handling.md (100%) rename {templates/zerver/api => api_docs}/rest.md (100%) rename {templates/zerver/api => api_docs}/roles-and-permissions.md (100%) rename {templates/zerver/api => api_docs}/running-bots.md (100%) rename {templates/zerver/api => api_docs}/send-message.md (100%) rename {templates/zerver/api => api_docs}/sidebar_index.md (100%) rename {templates/zerver/api => api_docs}/writing-bots.md (100%) diff --git a/.prettierignore b/.prettierignore index 0457e60a3e..641a993f58 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1,4 @@ +/api_docs/**/*.md /corporate/tests/stripe_fixtures /help/**/*.md /locale diff --git a/templates/zerver/api/api-doc-template.md b/api_docs/api-doc-template.md similarity index 100% rename from templates/zerver/api/api-doc-template.md rename to api_docs/api-doc-template.md diff --git a/templates/zerver/api/api-keys.md b/api_docs/api-keys.md similarity index 100% rename from templates/zerver/api/api-keys.md rename to api_docs/api-keys.md diff --git a/templates/zerver/api/changelog.md b/api_docs/changelog.md similarity index 100% rename from templates/zerver/api/changelog.md rename to api_docs/changelog.md diff --git a/templates/zerver/api/client-libraries.md b/api_docs/client-libraries.md similarity index 100% rename from templates/zerver/api/client-libraries.md rename to api_docs/client-libraries.md diff --git a/templates/zerver/api/configuring-python-bindings.md b/api_docs/configuring-python-bindings.md similarity index 100% rename from templates/zerver/api/configuring-python-bindings.md rename to api_docs/configuring-python-bindings.md diff --git a/templates/zerver/api/construct-narrow.md b/api_docs/construct-narrow.md similarity index 100% rename from templates/zerver/api/construct-narrow.md rename to api_docs/construct-narrow.md diff --git a/templates/zerver/api/create-stream.md b/api_docs/create-stream.md similarity index 100% rename from templates/zerver/api/create-stream.md rename to api_docs/create-stream.md diff --git a/templates/zerver/api/deploying-bots.md b/api_docs/deploying-bots.md similarity index 100% rename from templates/zerver/api/deploying-bots.md rename to api_docs/deploying-bots.md diff --git a/templates/zerver/api/include/api-admin-only.md b/api_docs/include/api-admin-only.md similarity index 100% rename from templates/zerver/api/include/api-admin-only.md rename to api_docs/include/api-admin-only.md diff --git a/templates/zerver/api/include/empty.md b/api_docs/include/empty.md similarity index 100% rename from templates/zerver/api/include/empty.md rename to api_docs/include/empty.md diff --git a/templates/zerver/api/include/rest-endpoints.md b/api_docs/include/rest-endpoints.md similarity index 100% rename from templates/zerver/api/include/rest-endpoints.md rename to api_docs/include/rest-endpoints.md diff --git a/templates/zerver/api/incoming-webhooks-overview.md b/api_docs/incoming-webhooks-overview.md similarity index 100% rename from templates/zerver/api/incoming-webhooks-overview.md rename to api_docs/incoming-webhooks-overview.md diff --git a/templates/zerver/api/incoming-webhooks-walkthrough.md b/api_docs/incoming-webhooks-walkthrough.md similarity index 100% rename from templates/zerver/api/incoming-webhooks-walkthrough.md rename to api_docs/incoming-webhooks-walkthrough.md diff --git a/templates/zerver/api/index.md b/api_docs/index.md similarity index 100% rename from templates/zerver/api/index.md rename to api_docs/index.md diff --git a/templates/zerver/api/installation-instructions.md b/api_docs/installation-instructions.md similarity index 100% rename from templates/zerver/api/installation-instructions.md rename to api_docs/installation-instructions.md diff --git a/templates/zerver/api/integrations-overview.md b/api_docs/integrations-overview.md similarity index 100% rename from templates/zerver/api/integrations-overview.md rename to api_docs/integrations-overview.md diff --git a/templates/zerver/api/mark-all-as-read.md b/api_docs/mark-all-as-read.md similarity index 100% rename from templates/zerver/api/mark-all-as-read.md rename to api_docs/mark-all-as-read.md diff --git a/templates/zerver/api/missing.md b/api_docs/missing.md similarity index 100% rename from templates/zerver/api/missing.md rename to api_docs/missing.md diff --git a/templates/zerver/api/non-webhook-integrations.md b/api_docs/non-webhook-integrations.md similarity index 100% rename from templates/zerver/api/non-webhook-integrations.md rename to api_docs/non-webhook-integrations.md diff --git a/templates/zerver/api/outgoing-webhooks.md b/api_docs/outgoing-webhooks.md similarity index 100% rename from templates/zerver/api/outgoing-webhooks.md rename to api_docs/outgoing-webhooks.md diff --git a/templates/zerver/api/real-time-events.md b/api_docs/real-time-events.md similarity index 100% rename from templates/zerver/api/real-time-events.md rename to api_docs/real-time-events.md diff --git a/templates/zerver/api/rest-error-handling.md b/api_docs/rest-error-handling.md similarity index 100% rename from templates/zerver/api/rest-error-handling.md rename to api_docs/rest-error-handling.md diff --git a/templates/zerver/api/rest.md b/api_docs/rest.md similarity index 100% rename from templates/zerver/api/rest.md rename to api_docs/rest.md diff --git a/templates/zerver/api/roles-and-permissions.md b/api_docs/roles-and-permissions.md similarity index 100% rename from templates/zerver/api/roles-and-permissions.md rename to api_docs/roles-and-permissions.md diff --git a/templates/zerver/api/running-bots.md b/api_docs/running-bots.md similarity index 100% rename from templates/zerver/api/running-bots.md rename to api_docs/running-bots.md diff --git a/templates/zerver/api/send-message.md b/api_docs/send-message.md similarity index 100% rename from templates/zerver/api/send-message.md rename to api_docs/send-message.md diff --git a/templates/zerver/api/sidebar_index.md b/api_docs/sidebar_index.md similarity index 100% rename from templates/zerver/api/sidebar_index.md rename to api_docs/sidebar_index.md diff --git a/templates/zerver/api/writing-bots.md b/api_docs/writing-bots.md similarity index 100% rename from templates/zerver/api/writing-bots.md rename to api_docs/writing-bots.md diff --git a/docs/documentation/api.md b/docs/documentation/api.md index 29bf51071e..f4f7878817 100644 --- a/docs/documentation/api.md +++ b/docs/documentation/api.md @@ -33,11 +33,10 @@ Our API documentation is defined by a few sets of files: our [help center docs](helpcenter.md), with some special extensions for rendering nice code blocks and example responses. Most API endpoints share a common template, - `templates/zerver/api/api-doc-template.md`, which renders the + `api_docs/api-doc-template.md`, which renders the OpenAPI description of the API endpoint. A handful of endpoints that require special content, as well as pages that document general API - details rather than specific endpoints, live at - `templates/zerver/api/*.md`. + details rather than specific endpoints, live at `api_docs/*.md`. - We have an extensive set of tests designed to validate that the data in the OpenAPI file matching the implementation. Specifically, `zerver/tests/test_openapi.py` compares every endpoint's accepted @@ -57,8 +56,8 @@ Our API documentation is defined by a few sets of files: - The cURL examples are generated and tested using `zerver/openapi/curl_param_value_generators.py`. - The REST API index - (`templates/zerver/api/include/rest-endpoints.md`) in the broader - /api left sidebar (`templates/zerver/api/sidebar_index.md`). + (`api_docs/include/rest-endpoints.md`) in the broader + /api left sidebar (`api_docs/sidebar_index.md`). This first section is focused on explaining how the API documentation system is put together; when actually documenting an endpoint, you'll @@ -67,7 +66,7 @@ want to also read the [Step by step guide](#step-by-step-guide). ## How it works To understand how this documentation system works, start by reading an -existing doc file (`templates/zerver/api/render-message.md` is a good +existing doc file (`api_docs/render-message.md` is a good example; accessible live [here](https://zulip.com/api/render-message) or in the development environment at `http://localhost:9991/api/render-message`). @@ -180,7 +179,7 @@ wherever that string appears in the API documentation. We have a separate Markdown extension to document the parameters that an API endpoint supports. You'll see this in files like -`templates/zerver/api/render-message.md` via the following Markdown +`api_docs/render-message.md` via the following Markdown directive (implemented in `zerver/lib/markdown/api_arguments_table_generator.py`): @@ -290,13 +289,13 @@ above. 1. Finally, if the API docs page of the endpoint doesn't follow the common API docs template in - `templates/zerver/api/api-docs-template.md`, then add its custom - Markdown file under `templates/zerver/api/`. However, it is a goal + `api_docs/api-docs-template.md`, then add its custom + Markdown file under `api_docs/`. However, it is a goal to minimize the number of files that diverse from the common template, so only do this if there's a good reason. 1. Add the endpoint to the index in - `templates/zerver/api/include/rest-endpoints.md`. The URL should + `api_docs/include/rest-endpoints.md`. The URL should match the `operationId` for the endpoint, and the link text should match the title of the endpoint from the OpenAPI `summary` field. @@ -307,14 +306,12 @@ above. make sure that copy-pasting the code in your examples works, and post an example of the output in the pull request. -1. Document the new API in `templates/zerver/api/changelog.md` and +1. Document the new API in `api_docs/changelog.md` and bump the `API_FEATURE_LEVEL` in `version.py`. Also, make sure to add a `**Changes**` entry in the description of the new API/event in `zerver/openapi/zulip.yaml`, which mentions the API feature level at which they were added. -[javascript-examples]: https://github.com/zulip/zulip-js/tree/main/examples - ## Why a custom system? Given that our documentation is written in large part using the diff --git a/docs/tutorials/new-feature-tutorial.md b/docs/tutorials/new-feature-tutorial.md index 56ef7aa2c4..d52379ece4 100644 --- a/docs/tutorials/new-feature-tutorial.md +++ b/docs/tutorials/new-feature-tutorial.md @@ -67,7 +67,7 @@ organization in Zulip). The following files are involved in the process: **Documentation** - `zerver/openapi/zulip.yaml`: OpenAPI definitions for the Zulip REST API. -- `templates/zerver/api/changelog.md`: documentation listing all changes to the Zulip Server API. +- `api_docs/changelog.md`: documentation listing all changes to the Zulip Server API. - `help/...`: end user facing documentation (Help Center) for the application. ### Adding a field to the database @@ -164,7 +164,7 @@ provides more detailed information about writing and editing feature **API documentation:** A new feature will probably impact the REST API documentation as well, which will mean updating `zerver/openapi/zulip.yaml` -and modifying `templates/zerver/api/changelog.md` for a new feature +and modifying `api_docs/changelog.md` for a new feature level. [Documenting REST API endpoints](../documentation/api.md) explains Zulip's API documentation system and provides a step by step guide to adding or updating documentation for an API endpoint. @@ -714,7 +714,7 @@ documentation is to read more about Zulip's and [OpenAPI configuration](../documentation/openapi.md). In particular, if there is an API change, **make sure** you document -your new feature in `templates/zerver/api/changelog.md` and bump the +your new feature in `api_docs/changelog.md` and bump the `API_FEATURE_LEVEL` in `version.py`. The API feature level allows the developers of mobile clients and other tools using the Zulip API to programmatically determine whether the Zulip server they are diff --git a/templates/zerver/documentation_main.html b/templates/zerver/documentation_main.html index 20d5fa1515..be5a678156 100644 --- a/templates/zerver/documentation_main.html +++ b/templates/zerver/documentation_main.html @@ -20,7 +20,7 @@ {% elif page_is_help_center %} {{ render_markdown_path(sidebar_index, pure_markdown=True) }} {% else %} - {{ render_markdown_path(sidebar_index, api_uri_context) }} + {{ render_markdown_path(sidebar_index, context=api_uri_context, pure_markdown=True) }} {% endif %} {% if not page_is_policy_center %} @@ -40,7 +40,7 @@ {% elif page_is_help_center %} {{ render_markdown_path(article, context=api_uri_context, help_center=True, pure_markdown=True) }} {% else %} - {{ render_markdown_path(article, api_uri_context) }} + {{ render_markdown_path(article, context=api_uri_context, pure_markdown=True) }} {% endif %}