Additional Languages

docfx.json
api/
    toc.yml
    api-page-1.yml
    api-page-2.yml

{
  "build": {
    "content": [
      { "files": ["api/**/*.yml", "toc.yml", "index.md"] }
    ],
    "output": "_site",
    "template": ["default", "modern"]
  }
}

"""Convert the docstrings of a Python package into DocFX API Page YAML and a toc.yml.

Usage: python3 py2apipage.py <package-dir> <output-dir>
Only the standard library is used.
"""
import ast
import json
import re
import sys
from pathlib import Path

SECTIONS = ("Args", "Returns", "Raises", "Example")


def scalar(value):
    # JSON strings and numbers are valid YAML scalars.
    return json.dumps(value, ensure_ascii=False)


def emit(node, indent=0):
    """Emit lists of dicts and dicts as block-style YAML."""
    pad = " " * indent
    lines = []
    if isinstance(node, dict):
        for key, value in node.items():
            if isinstance(value, (dict, list)) and value:
                lines.append(f"{pad}{key}:")
                lines.extend(emit(value, indent + (0 if isinstance(value, list) else 2)))
            else:
                lines.append(f"{pad}{key}: {scalar(value)}")
    else:
        for item in node:
            if isinstance(item, dict):
                inner = emit(item, indent + 2)
                inner[0] = f"{pad}- " + inner[0].lstrip()
                lines.extend(inner)
            else:
                lines.append(f"{pad}- {scalar(item)}")
    return lines


def to_markdown(text):
    """Turn reStructuredText inline roles and double backticks into Markdown code spans."""
    text = re.sub(r":\w+:`~?([^`]+)`", r"`\1`", text)
    return re.sub(r"``([^`]+)``", r"`\1`", text)


def parse_docstring(doc):
    """Split a Google-style docstring into summary, description and sections."""
    doc = ast.get_docstring(doc, clean=True) if not isinstance(doc, str) else doc
    parts = {"summary": "", "description": "", "sections": {}}
    if not doc:
        return parts
    current = None
    free = []
    for line in doc.splitlines():
        header = line.rstrip(":")
        if line.endswith(":") and header in SECTIONS and not line.startswith(" "):
            current = header
            parts["sections"][current] = []
        elif current:
            parts["sections"][current].append(line)
        else:
            free.append(line)
    text = "\n".join(free).strip()
    summary, _, rest = text.partition("\n\n")
    parts["summary"] = to_markdown(summary.replace("\n", " "))
    parts["description"] = to_markdown(rest.strip())
    return parts


def name_value(lines):
    """Turn 'name: text' lines of an Args or Raises section into pairs."""
    pairs = []
    for line in lines:
        match = re.match(r"^\s{4}(\w+): (.*)$", line)
        if match:
            pairs.append([match.group(1), to_markdown(match.group(2))])
        elif line.strip() and pairs:
            pairs[-1][1] += " " + line.strip()
    return pairs


def dedent(lines):
    return "\n".join(line[4:] if line.startswith("    ") else line for line in lines).strip()


def signature(func):
    args = []
    defaults = [None] * (len(func.args.args) - len(func.args.defaults)) + list(func.args.defaults)
    for arg, default in zip(func.args.args, defaults):
        text = arg.arg
        if arg.annotation is not None:
            text += ": " + ast.unparse(arg.annotation)
        if default is not None:
            text += " = " + ast.unparse(default)
        args.append(text)
    result = f"def {func.name}({', '.join(args)})"
    if func.returns is not None:
        result += " -> " + ast.unparse(func.returns)
    return result


def function_blocks(func, level):
    doc = parse_docstring(func)
    sec = doc["sections"]
    blocks = [{f"api{level}": f"{func.name}()", "id": func.name}]
    blocks.append({"code": signature(func), "languageId": "python"})
    if doc["summary"]:
        blocks.append({"markdown": doc["summary"]})
    if doc["description"]:
        blocks.append({"markdown": doc["description"]})
    if "Args" in sec:
        blocks.append({f"h{level + 1}": "Parameters"})
        params = []
        for name, text in name_value(sec["Args"]):
            arg = next((a for a in func.args.args if a.arg == name), None)
            param = {"name": name}
            if arg is not None and arg.annotation is not None:
                param["type"] = ast.unparse(arg.annotation)
            param["description"] = text
            params.append(param)
        blocks.append({"parameters": params})
    if "Returns" in sec:
        blocks.append({f"h{level + 1}": "Returns"})
        blocks.append({"markdown": dedent(sec["Returns"])})
    if "Raises" in sec:
        blocks.append({f"h{level + 1}": "Exceptions"})
        blocks.append({"parameters": [{"name": n, "description": t} for n, t in name_value(sec["Raises"])]})
    if "Example" in sec:
        blocks.append({f"h{level + 1}": "Example"})
        blocks.append({"code": dedent(sec["Example"]), "languageId": "python"})
    return blocks


def class_page(cls, module):
    doc = parse_docstring(cls)
    is_enum = any(ast.unparse(b) == "Enum" for b in cls.bases)
    page_uid = f"{module}.{cls.name}"
    body = [{"h1": f"{cls.name} {'enum' if is_enum else 'class'}"}]
    body.append({"facts": [{"name": "Module", "value": [{"text": module, "url": f"{module}.html"}]},
                           {"name": "Bases", "value": ", ".join(ast.unparse(b) for b in cls.bases) or "object"}]})
    body.append({"code": f"class {cls.name}({', '.join(ast.unparse(b) for b in cls.bases)})", "languageId": "python"})
    if doc["summary"]:
        body.append({"markdown": doc["summary"]})
    members = [n for n in cls.body if isinstance(n, ast.Assign)]
    if is_enum and members:
        body.append({"h2": "Members"})
        body.append({"parameters": [
            {"name": m.targets[0].id, "type": "float", "default": ast.unparse(m.value)}
            for m in members]})
    for method in (n for n in cls.body if isinstance(n, ast.FunctionDef) and not n.name.startswith("_")):
        body.extend(function_blocks(method, 2))
    return page_uid, {"title": page_uid, "languageId": "python", "body": body}


def module_page(path, module):
    tree = ast.parse(path.read_text(encoding="utf-8"))
    summary = parse_docstring(ast.get_docstring(tree) or "")["summary"]
    pages, toc = {}, []
    body = [{"h1": f"{module} module"}, {"markdown": summary}]
    exported = []
    for node in tree.body:
        if isinstance(node, ast.ClassDef):
            uid, page = class_page(node, module)
            pages[uid] = page
            toc.append({"name": node.name, "href": f"{uid}.yml"})
            exported.append({"text": node.name, "url": f"{uid}.html"})
        elif isinstance(node, ast.FunctionDef) and not node.name.startswith("_"):
            uid = f"{module}.{node.name}"
            pages[uid] = {"title": uid, "languageId": "python", "body": function_blocks(node, 1)}
            toc.append({"name": node.name + "()", "href": f"{uid}.yml"})
            exported.append({"text": node.name + "()", "url": f"{uid}.html"})
    body.append({"h2": "Contents"})
    body.append({"list": exported})
    pages[module] = {"title": module, "languageId": "python", "body": body}
    return pages, toc


def main(package_dir, out_dir):
    package = Path(package_dir)
    out = Path(out_dir)
    out.mkdir(parents=True, exist_ok=True)
    root = package.name
    all_pages, items = {}, []
    for path in sorted(package.glob("*.py")):
        if path.name == "__init__.py":
            continue
        module = f"{root}.{path.stem}"
        pages, toc = module_page(path, module)
        all_pages.update(pages)
        items.append({"name": module, "href": f"{module}.yml", "items": toc})
    for uid, page in all_pages.items():
        text = "#YamlMime:ApiPage\n" + "\n".join(emit(page)) + "\n"
        (out / f"{uid}.yml").write_text(text, encoding="utf-8")
    toc_text = "### YamlMime:TableOfContent\n" + "\n".join(emit(items)) + "\n"
    (out / "toc.yml").write_text(toc_text, encoding="utf-8")
    print(f"wrote {len(all_pages)} pages and toc.yml to {out}")


if __name__ == "__main__":
    main(sys.argv[1], sys.argv[2])

- name: Home
  href: index.md
- name: Python API
  href: api/

python3 converter/py2apipage.py pocket_units api
docker run --rm -v "$PWD":/w -w /w mcr.microsoft.com/dotnet/sdk:10.0 bash -c \
  'dotnet tool install -g docfx --version 2.81.0 && export PATH=$PATH:/root/.dotnet/tools \
   && docfx build docfx.json'

Building 3 file(s) in ApiPageDocumentProcessor()...
Building 1 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>ValidateConceptualDocumentMetadata)...
Building 2 file(s) in TocDocumentProcessor(BuildTocDocument)...
Applying templates to 6 model(s)...
XRef map exported.

Build succeeded.

    0 warning(s)
    0 error(s)