From 6759767b14c4f7ec5bf77c4d70d76d52236ec7c3 Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Wed, 7 Dec 2022 19:41:17 +0100 Subject: [PATCH] api-docs: Move include markdown macro files for API documentation. Moves files in `templates/zerver/help/include` that are used specifically for API documentation pages to be in a new directory: `templates/zerver/api/include`. Adds a boolean parameter to `render_markdown_path` to be used for help center documentation articles. Also moves the test file `empty.md` to the new directory since this is the default directory for these special include macros that are used in documentation pages. --- docs/documentation/api.md | 4 ++-- templates/zerver/{help => api}/include/api-admin-only.md | 0 templates/zerver/{help => api}/include/empty.md | 0 templates/zerver/{help => api}/include/rest-endpoints.md | 0 templates/zerver/documentation_main.html | 4 ++++ zerver/lib/templates.py | 7 ++++++- zerver/openapi/test_curl_examples.py | 2 +- 7 files changed, 13 insertions(+), 4 deletions(-) rename templates/zerver/{help => api}/include/api-admin-only.md (100%) rename templates/zerver/{help => api}/include/empty.md (100%) rename templates/zerver/{help => api}/include/rest-endpoints.md (100%) diff --git a/docs/documentation/api.md b/docs/documentation/api.md index 81aa313ed4..93e172fa43 100644 --- a/docs/documentation/api.md +++ b/docs/documentation/api.md @@ -57,7 +57,7 @@ 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/help/include/rest-endpoints.md`) in the broader + (`templates/zerver/api/include/rest-endpoints.md`) in the broader /api left sidebar (`templates/zerver/api/sidebar_index.md`). This first section is focused on explaining how the API documentation @@ -296,7 +296,7 @@ above. template, so only do this if there's a good reason. 1. Add the endpoint to the index in - `templates/zerver/help/include/rest-endpoints.md`. The URL should + `templates/zerver/api/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. diff --git a/templates/zerver/help/include/api-admin-only.md b/templates/zerver/api/include/api-admin-only.md similarity index 100% rename from templates/zerver/help/include/api-admin-only.md rename to templates/zerver/api/include/api-admin-only.md diff --git a/templates/zerver/help/include/empty.md b/templates/zerver/api/include/empty.md similarity index 100% rename from templates/zerver/help/include/empty.md rename to templates/zerver/api/include/empty.md diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/api/include/rest-endpoints.md similarity index 100% rename from templates/zerver/help/include/rest-endpoints.md rename to templates/zerver/api/include/rest-endpoints.md diff --git a/templates/zerver/documentation_main.html b/templates/zerver/documentation_main.html index 01294edd58..f6bd8cf2b7 100644 --- a/templates/zerver/documentation_main.html +++ b/templates/zerver/documentation_main.html @@ -17,6 +17,8 @@ {% if page_is_policy_center %} {{ render_markdown_path(sidebar_index, pure_markdown=True) }} + {% elif page_is_help_center %} + {{ render_markdown_path(sidebar_index, context=api_uri_context, help_center=True) }} {% else %} {{ render_markdown_path(sidebar_index, api_uri_context) }} {% endif %} @@ -35,6 +37,8 @@
{% if page_is_policy_center %} {{ render_markdown_path(article, pure_markdown=True) }} + {% elif page_is_help_center %} + {{ render_markdown_path(article, context=api_uri_context, help_center=True) }} {% else %} {{ render_markdown_path(article, api_uri_context) }} {% endif %} diff --git a/zerver/lib/templates.py b/zerver/lib/templates.py index 354f8079e3..5b20434704 100644 --- a/zerver/lib/templates.py +++ b/zerver/lib/templates.py @@ -87,6 +87,7 @@ def render_markdown_path( context: Optional[Dict[str, Any]] = None, pure_markdown: bool = False, integration_doc: bool = False, + help_center: bool = False, ) -> str: """Given a path to a Markdown file, return the rendered HTML. @@ -149,10 +150,14 @@ def render_markdown_path( md_macro_extension = zerver.lib.markdown.include.makeExtension( base_path="templates/zerver/integrations/include/" ) - else: + elif help_center: md_macro_extension = zerver.lib.markdown.include.makeExtension( base_path="templates/zerver/help/include/" ) + else: + md_macro_extension = zerver.lib.markdown.include.makeExtension( + base_path="templates/zerver/api/include/" + ) if not any(doc in markdown_file_path for doc in docs_without_macros): extensions = [md_macro_extension, *extensions] diff --git a/zerver/openapi/test_curl_examples.py b/zerver/openapi/test_curl_examples.py index 8184bf67e2..bdaf8ef3b4 100644 --- a/zerver/openapi/test_curl_examples.py +++ b/zerver/openapi/test_curl_examples.py @@ -39,7 +39,7 @@ def test_generated_curl_examples_for_success(client: Client) -> None: # should try to either avoid ordering dependencies or make them # very explicit. rest_endpoints_path = os.path.join( - settings.DEPLOY_ROOT, "templates/zerver/help/include/rest-endpoints.md" + settings.DEPLOY_ROOT, "templates/zerver/api/include/rest-endpoints.md" ) rest_endpoints_raw = open(rest_endpoints_path).read() ENDPOINT_REGEXP = re.compile(r"/api/\s*(.*?)\)")