🔧 Update tabs and admonitions with new syntax and new MkDocs features

[tiangolo]

🔧 Update tabs and admonitions with new syntax and new MkDocs features

Method

Tabs

To update the tabs, I ran this script, debugging iteratively, in an interactive window:

# update_tabs.py

import os
import re
from dataclasses import dataclass, field
from pathlib import Path

base_dir = Path(__file__).parent

@dataclass
class Tab:
    title: str
    content: list[str] = field(default_factory=list)

    def __str__(self) -> str:
        content = "\n".join(self.content).strip()
        return f"//// tab | {self.title}\n\n{content}\n\n////\n"


def generate_new_content(content: str) -> str:
    new_content_blocks = []
    open_tab: Tab | None = None
    lines = content.splitlines()
    for line in lines:
        if open_tab:
            if line.startswith("    "):
                open_tab.content.append(line[4:])
                continue
            elif line == "":
                open_tab.content.append(line)
                continue
            else:
                new_content_blocks.append(str(open_tab))
                open_tab = None
        if line.startswith("=== "):
            match = re.match(r'=== "(.*)"', line)
            assert match
            title = match.group(1)
            open_tab = Tab(title=title)
            continue
        new_content_blocks.append(line)
    if open_tab:
        new_content_blocks.append(str(open_tab))
    new_content = "\n".join(new_content_blocks)
    return new_content.strip() + "\n"


def update_md_files_tabs() -> None:
    os.chdir(base_dir)
    md_files = list(Path("docs").glob("**/*.md"))
    for md_file in md_files:
        content = md_file.read_text()
        new_content = generate_new_content(content)
        md_file.write_text(new_content)


if __name__ == "__main__":
    update_md_files_tabs()

Admonitions

To update the admonitions, I ran this script iteratively in an interactive window as well. The main difference is the strings to be matched and where to extract the data from:

# update_admonitions.py

import os
import re
from dataclasses import dataclass, field
from pathlib import Path

base_dir = Path(__file__).parent

@dataclass
class Admonition:
    type: str
    title: str = ""
    content: list[str] = field(default_factory=list)

    def __str__(self) -> str:
        content = "\n".join(self.content).strip()
        if self.title:
            return f"/// {self.type} | {self.title}\n\n{content}\n\n///\n"
        return f"/// {self.type}\n\n{content}\n\n///\n"


def generate_new_content(content: str) -> str:
    new_content_blocks = []
    open_admonition: Admonition | None = None
    lines = content.splitlines()
    for line in lines:
        if open_admonition:
            if line.startswith("    "):
                open_admonition.content.append(line[4:])
                continue
            elif line == "":
                open_admonition.content.append(line)
                continue
            else:
                new_content_blocks.append(str(open_admonition))
                open_admonition = None
        if line.startswith("!!! "):
            no_title_match = re.match(r'!!! (\S*)$', line)
            title_match = re.match(r'!!! (\S*) "(.*)"$', line)
            if no_title_match:
                type = no_title_match.group(1)
                open_admonition = Admonition(type=type)
                continue
            assert title_match
            type = title_match.group(1)
            title = title_match.group(2)
            open_admonition = Admonition(type=type, title=title)
            continue
        new_content_blocks.append(line)
    if open_admonition:
        new_content_blocks.append(str(open_admonition))
    new_content = "\n".join(new_content_blocks)
    return new_content.strip() + "\n"


def update_md_files_tabs() -> None:
    os.chdir(base_dir)
    md_files = list(Path("docs").glob("**/*.md"))
    for md_file in md_files:
        content = md_file.read_text()
        new_content = generate_new_content(content)
        md_file.write_text(new_content)


if __name__ == "__main__":
    update_md_files_tabs()

[github-actions]

📝 Docs preview for commit b0ba09a at: https://7f919614.typertiangolo.pages.dev