Skip to content

armgit / zulip

Public Imported from GitHub
0

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

8.1 KB
Raw Blame
import time
from pathlib import Path
from typing import Any

import markdown
import markdown.extensions.admonition
import markdown.extensions.codehilite
import markdown.extensions.extra
import markdown.extensions.toc
import orjson
from django.conf import settings
from django.contrib.staticfiles.storage import staticfiles_storage
from django.template import Library, engines
from django.template.backends.jinja2 import Jinja2
from django.utils.safestring import mark_safe
from markupsafe import Markup

import zerver.lib.markdown.api_arguments_table_generator
import zerver.lib.markdown.api_return_values_table_generator
import zerver.lib.markdown.fenced_code
import zerver.lib.markdown.help_settings_links
import zerver.lib.markdown.include
import zerver.lib.markdown.nested_code_blocks
import zerver.lib.markdown.static
import zerver.lib.markdown.tabbed_sections
import zerver.openapi.markdown_extension
from zerver.lib.cache import dict_to_items_tuple, ignore_unhashable_lru_cache, items_tuple_to_dict
from zerver.openapi.merge_api_changelogs import (
    get_feature_level,
    get_unmerged_changelogs,
    merge_changelogs,
)

register = Library()


def and_n_others(values: list[str | Markup], limit: int) -> str | Markup:
    # A helper for the commonly appended "and N other(s)" string, with
    # the appropriate pluralization.
    return " and {} other{}".format(
        len(values) - limit,
        "" if len(values) == limit + 1 else "s",
    )


def get_updated_changelog() -> str | None:
    unmerged_changelogs = get_unmerged_changelogs(verbose=False)
    if not unmerged_changelogs:
        return None

    new_feature_level = get_feature_level(update_feature_level=False)
    return merge_changelogs(unmerged_changelogs, new_feature_level, False)


@register.filter(name="display_list", is_safe=True)
def display_list(values: list[str | Markup], display_limit: int) -> str | Markup:
    """
    Given a list of values, return a string nicely formatting those values,
    summarizing when you have more than `display_limit`. Eg, for a
    `display_limit` of 3 we get the following possible cases:

    Jessica
    Jessica and Waseem
    Jessica, Waseem, and Tim
    Jessica, Waseem, Tim, and 1 other
    Jessica, Waseem, Tim, and 2 others
    """
    sep = Markup(", ") if any(isinstance(value, Markup) for value in values) else ", "
    if len(values) == 1:
        # One value, show it.
        display_string = values[0]
    elif len(values) <= display_limit:
        # Fewer than `display_limit` values, show all of them.
        display_string = sep.join(value for value in values[:-1])
        display_string += " and " + values[-1]
    else:
        # More than `display_limit` values, only mention a few.
        display_string = sep.join(value for value in values[:display_limit])
        display_string += and_n_others(values, display_limit)

    return display_string


md_extensions: list[markdown.Extension] | None = None
md_macro_extension: markdown.Extension | None = None
# Prevent the automatic substitution of macros in these docs. If
# they contain a macro, it is always used literally for documenting
# the macro system.
docs_without_macros = [
    "incoming-webhooks-walkthrough.md",
]


# render_markdown_path is passed a context dictionary (unhashable), which
# results in the calls not being cached. To work around this, we convert the
# dict to a tuple of dict items to cache the results.
@dict_to_items_tuple
@ignore_unhashable_lru_cache(512)
@items_tuple_to_dict
@register.filter(name="render_markdown_path", is_safe=True)
def render_markdown_path(
    markdown_file_path: str,
    context: dict[str, Any] | None = None,
    integration_doc: bool = False,
    help_center: bool = False,
) -> str:
    """Given a path to a Markdown file, return the rendered HTML.

    Note that this assumes that any HTML in the Markdown file is
    trusted; it is intended to be used for documentation, not user
    data."""

    # We set this global hackishly
    from zerver.lib.markdown.help_settings_links import set_relative_settings_links

    relative_links = bool(context is not None and context.get("html_settings_links"))
    set_relative_settings_links(relative_links)

    global md_extensions, md_macro_extension
    if md_extensions is None:
        md_extensions = [
            markdown.extensions.extra.makeExtension(),
            markdown.extensions.toc.makeExtension(),
            markdown.extensions.admonition.makeExtension(),
            markdown.extensions.codehilite.makeExtension(
                linenums=False,
                guess_lang=False,
            ),
            zerver.lib.markdown.fenced_code.makeExtension(
                run_content_validators=bool(
                    context is not None and context.get("run_content_validators", False)
                ),
            ),
            zerver.lib.markdown.api_arguments_table_generator.makeExtension(),
            zerver.lib.markdown.api_return_values_table_generator.makeExtension(),
            zerver.lib.markdown.nested_code_blocks.makeExtension(),
            zerver.lib.markdown.tabbed_sections.makeExtension(),
            zerver.lib.markdown.help_settings_links.makeExtension(),
            zerver.lib.markdown.static.makeExtension(),
        ]
    if context is not None and "api_url" in context:
        # We need to generate the API code examples extension each
        # time so the `api_url` config parameter can be set dynamically.
        #
        # TODO: Convert this to something more efficient involving
        # passing the API URL as a direct parameter.
        extensions = [
            zerver.openapi.markdown_extension.makeExtension(
                api_url=context["api_url"],
            ),
            *md_extensions,
        ]
    else:
        extensions = md_extensions

    if integration_doc:
        md_macro_extension = zerver.lib.markdown.include.makeExtension(
            base_path="templates/zerver/integrations/include/"
        )
    elif help_center:
        md_macro_extension = zerver.lib.markdown.include.makeExtension(base_path="help/include/")
    else:
        md_macro_extension = zerver.lib.markdown.include.makeExtension(
            base_path="api_docs/include/"
        )
    if not any(doc in markdown_file_path for doc in docs_without_macros):
        extensions = [md_macro_extension, *extensions]

    md_engine = markdown.Markdown(extensions=extensions)
    md_engine.reset()

    jinja = engines["Jinja2"]
    assert isinstance(jinja, Jinja2)
    if markdown_file_path.startswith("/"):
        with open(markdown_file_path) as fp:
            markdown_string = fp.read()
    else:
        assert jinja.env.loader is not None
        markdown_string = jinja.env.loader.get_source(jinja.env, markdown_file_path)[0]

    if (
        settings.DEVELOPMENT
        and Path(markdown_file_path).resolve() == Path("api_docs/changelog.md").resolve()
    ):
        updated_changelog = get_updated_changelog()
        if updated_changelog is not None:
            markdown_string = updated_changelog

    API_ENDPOINT_NAME = context.get("API_ENDPOINT_NAME", "") if context is not None else ""
    markdown_string = markdown_string.replace("API_ENDPOINT_NAME", API_ENDPOINT_NAME)

    html = md_engine.convert(markdown_string)
    if context is None:
        return mark_safe(html)  # noqa: S308

    return mark_safe(jinja.from_string(html).render(context))  # noqa: S308


def webpack_entry(entrypoint: str) -> list[str]:
    while True:
        with open(settings.WEBPACK_STATS_FILE, "rb") as f:
            stats = orjson.loads(f.read())
        status = stats["status"]
        if not settings.DEBUG or status != "compile":
            break
        time.sleep(0.2)

    if status != "done":
        raise RuntimeError("Webpack compilation was not successful")

    try:
        files_from_entrypoints = [
            staticfiles_storage.url(settings.WEBPACK_BUNDLES + filename)
            for filename in stats["chunks"][entrypoint]
            if filename.endswith((".css", ".js")) and not filename.endswith(".hot-update.js")
        ]
    except KeyError:
        raise KeyError(
            f"'{entrypoint}' entrypoint could not be found. Please define it in web/webpack.assets.json."
        )

    return files_from_entrypoints