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

@@ -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.
 

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 @@
         <div class="content">
             {% 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 %}

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]
 

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*(.*?)\)")