canola.nvim/.github/generate.py

import os
import os.path
import re
from dataclasses import dataclass, field
from typing import List

from nvim_doc_tools import (
    LuaParam,
    Vimdoc,
    VimdocSection,
    generate_md_toc,
    indent,
    leftright,
    parse_functions,
    read_nvim_json,
    read_section,
    render_md_api,
    render_vimdoc_api,
    replace_section,
    wrap,
)
from nvim_doc_tools.vimdoc import format_vimdoc_params

HERE = os.path.dirname(__file__)
ROOT = os.path.abspath(os.path.join(HERE, os.path.pardir))
README = os.path.join(ROOT, "README.md")
DOC = os.path.join(ROOT, "doc")
VIMDOC = os.path.join(DOC, "oil.txt")


def add_md_link_path(path: str, lines: List[str]) -> List[str]:
    ret = []
    for line in lines:
        ret.append(re.sub(r"(\(#)", "(" + path + "#", line))
    return ret


def update_md_api():
    api_doc = os.path.join(DOC, "api.md")
    funcs = parse_functions(os.path.join(ROOT, "lua", "oil", "init.lua"))
    lines = ["\n"] + render_md_api(funcs, 2) + ["\n"]
    replace_section(
        api_doc,
        r"^<!-- API -->$",
        r"^<!-- /API -->$",
        lines,
    )
    toc = ["\n"] + generate_md_toc(api_doc, max_level=1) + ["\n"]
    replace_section(
        api_doc,
        r"^<!-- TOC -->$",
        r"^<!-- /TOC -->$",
        toc,
    )
    toc = add_md_link_path("doc/api.md", toc)
    replace_section(
        README,
        r"^<!-- API -->$",
        r"^<!-- /API -->$",
        toc,
    )


def update_readme_toc():
    toc = ["\n"] + generate_md_toc(README, max_level=1) + ["\n"]
    replace_section(
        README,
        r"^<!-- TOC -->$",
        r"^<!-- /TOC -->$",
        toc,
    )


def update_config_options():
    config_file = os.path.join(ROOT, "lua", "oil", "config.lua")
    opt_lines = ['\n```lua\nrequire("oil").setup({\n']
    opt_lines.extend(read_section(config_file, r"^\s*local default_config =", r"^}$"))
    replace_section(
        README,
        r"^## Options$",
        r"^}\)$",
        opt_lines,
    )


@dataclass
class ColumnDef:
    name: str
    adapters: str
    editable: bool
    summary: str
    params: List["LuaParam"] = field(default_factory=list)


HL = [
    LuaParam(
        "highlight",
        "string|fun(value: string): string",
        "Highlight group, or function that returns a highlight group",
    )
]
TIME = [
    LuaParam("format", "string", "Format string (see :help strftime)"),
]
COL_DEFS = [
    ColumnDef(
        "type",
        "*",
        False,
        "The type of the entry (file, directory, link, etc)",
        HL
        + [LuaParam("icons", "table<string, string>", "Mapping of entry type to icon")],
    ),
    ColumnDef(
        "icon",
        "*",
        False,
        "An icon for the entry's type (requires nvim-web-devicons)",
        HL
        + [
            LuaParam("default_file", "string", "Fallback icon for files when nvim-web-devicons returns nil"),
            LuaParam("directory", "string", "Icon for directories"),
            LuaParam("add_padding", "boolean", "Set to false to remove the extra whitespace after the icon"),
        ],
    ),
    ColumnDef("size", "files, ssh", False, "The size of the file", HL + []),
    ColumnDef(
        "permissions", "files, ssh", True, "Access permissions of the file", HL + []
    ),
    ColumnDef("ctime", "files", False, "Change timestamp of the file", HL + TIME + []),
    ColumnDef(
        "mtime", "files", False, "Last modified time of the file", HL + TIME + []
    ),
    ColumnDef("atime", "files", False, "Last access time of the file", HL + TIME + []),
    ColumnDef(
        "birthtime", "files", False, "The time the file was created", HL + TIME + []
    ),
]


def get_options_vimdoc() -> "VimdocSection":
    section = VimdocSection("options", "oil-options")
    config_file = os.path.join(ROOT, "lua", "oil", "config.lua")
    opt_lines = read_section(config_file, r"^local default_config =", r"^}$")
    lines = ["\n", ">\n", '    require("oil").setup({\n']
    lines.extend(indent(opt_lines, 4))
    lines.extend(["    })\n", "<\n"])
    section.body = lines
    return section


def get_highlights_vimdoc() -> "VimdocSection":
    section = VimdocSection("Highlights", "oil-highlights", ["\n"])
    highlights = read_nvim_json('require("oil")._get_highlights()')
    for hl in highlights:
        name = hl["name"]
        desc = hl.get("desc")
        if desc is None:
            continue
        section.body.append(leftright(name, f"*hl-{name}*"))
        section.body.extend(wrap(desc, 4))
        section.body.append("\n")
    return section


def get_actions_vimdoc() -> "VimdocSection":
    section = VimdocSection("Actions", "oil-actions", ["\n"])
    section.body.extend(
        wrap(
            "These are actions that can be used in the `keymaps` section of config options."
        )
    )
    section.body.append("\n")
    actions = read_nvim_json('require("oil.actions")._get_actions()')
    actions.sort(key=lambda a: a["name"])
    for action in actions:
        name = action["name"]
        desc = action["desc"]
        section.body.append(leftright(name, f"*actions.{name}*"))
        section.body.extend(wrap(desc, 4))
        section.body.append("\n")
    return section


def get_columns_vimdoc() -> "VimdocSection":
    section = VimdocSection("Columns", "oil-columns", ["\n"])
    section.body.extend(
        wrap(
            'Columns can be specified as a string to use default arguments (e.g. `"icon"`), or as a table to pass parameters (e.g. `{"size", highlight = "Special"}`)'
        )
    )
    section.body.append("\n")
    for col in COL_DEFS:
        section.body.append(leftright(col.name, f"*column-{col.name}*"))
        section.body.extend(wrap(f"Adapters: {col.adapters}", 4))
        if col.editable:
            section.body.extend(wrap(f"Editable: this column is read/write", 4))
        section.body.extend(wrap(col.summary, 4))
        section.body.append("\n")
        section.body.append("    Parameters:\n")
        section.body.extend(format_vimdoc_params(col.params, 6))
        section.body.append("\n")
    return section


def generate_vimdoc():
    doc = Vimdoc("oil.txt", "oil")
    funcs = parse_functions(os.path.join(ROOT, "lua", "oil", "init.lua"))
    doc.sections.extend(
        [
            get_options_vimdoc(),
            VimdocSection("API", "oil-api", render_vimdoc_api("oil", funcs)),
            get_columns_vimdoc(),
            get_actions_vimdoc(),
            get_highlights_vimdoc(),
        ]
    )

    with open(VIMDOC, "w", encoding="utf-8") as ofile:
        ofile.writelines(doc.render())


def main() -> None:
    """Update the README"""
    update_config_options()
    update_md_api()
    update_readme_toc()
    generate_vimdoc()