def generate_markdown()

in scripts/generate_api_docs.py [0:0]

• 49 lines of code
• 12 McCabe index (conditional complexity)

def generate_markdown(article_name: str, symbol_name: str, entity: Any) -> str:
    """
    TODO: Method that inputs an object, extracts signature/docstring,
    and formats as markdown
    TODO: Method that build index markdown for overview files
    The overview for the entire API is a special case
    """

    if symbol_name == "":
        header = """---
id: overview
sidebar_label: "Overview"
slug: "/api"
---

:::info

These API stubs are generated from Python via a custom script and will filled
out in the future.

:::

"""
        return header

    # Regular modules/functions
    item = {
        "id": article_name,
        "sidebar_label": "Overview" if ismodule(entity) else symbol_name.split(".")[-1],
        "slug": f"/api/{article_name}",
        "ref": entity,
    }

    header = f"""---
id: {item['id']}
sidebar_label: {item['sidebar_label']}
---"""

    # Convert symbol to MDX

    # Imports for custom styling components
    markdown = [
        """import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faAngleDoubleRight } from '@fortawesome/free-solid-svg-icons'
import PythonClass from "@theme/PythonClass";
import PythonFunction from "@theme/PythonFunction";
import PythonMethod from "@theme/PythonMethod";
import PythonModule from "@theme/PythonModule";
import PythonNavbar from "@theme/PythonNavbar";
"""
    ]

    # Make URL
    entity_file = (
        entity.__file__ if ismodule(entity) else inspect.getmodule(entity).__file__
    )
    url = (
        config["settings"]["github"]
        + "flowtorch/"
        + entity_file[(len(main_path) + 1) :].replace("\\", "/")
    )

    # Make navigation bar
    markdown.append(f"<PythonNavbar url='{url}'>\n")
    navigation = []
    symbol_splits = symbol_name.split(".")
    for idx in range(len(symbol_splits)):
        partial_symbol_name = ".".join(symbol_splits[0 : (idx + 1)])
        if idx == len(symbol_splits) - 1:
            navigation.append(f"*{symbol_splits[idx]}*")
        elif partial_symbol_name in symbol_to_article:
            navigation.append(
                f"[{symbol_splits[idx]}](/api/{symbol_to_article[partial_symbol_name]})"
            )
        else:
            navigation.append(f"{symbol_splits[idx]}")

    markdown.append(
        ' <FontAwesomeIcon icon={faAngleDoubleRight} size="sm" /> '.join(navigation)
    )
    markdown.append("\n</PythonNavbar>\n")

    # Handle known symbol types
    if isclass(entity):
        markdown.append(generate_class_markdown(symbol_name, entity))
        return "\n".join([header] + markdown)

    elif ismodule(entity):
        markdown.append(generate_module_markdown(symbol_name, entity))
        return "\n".join([header] + markdown)

    # Signature for function
    elif isfunction(entity):
        markdown.append(generate_function_markdown(symbol_name, entity))
        return "\n".join([header] + markdown)

    # Unknown symbol type
    else:
        raise ValueError(f"Symbol {symbol_name} has unknown type {type(symbol_object)}")