autofix_docs.py

"""Autofix documentation files content from Python classes.

Run on the dev machine with "invoke doc", and commit on GitHub.
This also runs as a local pre-commit hook.

The ``include`` directive is not working on Read the Docs.
It doesn't recognise the "styles" dir anywhere (on the root, under "docs", under "_static"...).
Not even changing ``html_static_path`` on ``conf.py`` worked.
"""

from __future__ import annotations

import sys
from collections import defaultdict
from importlib import import_module
from pathlib import Path
from subprocess import check_output  # nosec
from textwrap import dedent, indent

import attr
import click
from slugify import slugify

from nitpick.constants import (
    CONFIG_FILES,
    DOT,
    EDITOR_CONFIG,
    PYTHON_PYLINTRC,
    PYTHON_SETUP_CFG,
    READ_THE_DOCS_URL,
    EmojiEnum,
)
from nitpick.core import Nitpick
from nitpick.style import BuiltinStyle, builtin_styles, repo_root

RST_DIVIDER_FROM_HERE = ".. auto-generated-from-here"
RST_DIVIDER_START = ".. auto-generated-start-{}"
RST_DIVIDER_END = ".. auto-generated-end-{}"

MD_DIVIDER_START = "<!-- auto-generated-start-{} -->"
MD_DIVIDER_END = "<!-- auto-generated-end-{} -->"

DOCS_DIR: Path = Path(__file__).parent.absolute()
CLI_MAPPING = [
    ("", "Main options", ""),
    (
        "fix",
        "Modify files directly",
        """
        At the end of execution, this command displays:

        - the number of fixed violations;
        - the number of violations that have to be changed manually.
        """,
    ),
    ("check", "Don't modify, just print the differences", ""),
    ("ls", "List configures files", ""),
    ("init", "Initialise a configuration file", ""),
]


@attr.frozen()
class FileType:
    """A file type handled by Nitpick."""

    text: str
    url: str
    check: bool | int
    autofix: bool | int

    def __post_init__(self):
        """Warn about text that might render incorrectly."""
        if "`" in self.text:
            msg = f"Remove all backticks from the text: {self.text}"
            raise RuntimeError(msg)

    def __lt__(self, other: FileType) -> bool:
        """Sort instances.

        From the `docs <https://docs.python.org/3/howto/sorting.html#odd-and-ends>`_:

        > It is easy to add a standard sort order to a class by defining an __lt__() method
        """
        return self.sort_key < other.sort_key

    @property
    def sort_key(self) -> str:
        """Sort key of this element."""
        return ("0" if self.text.startswith("Any") else "1") + self.text.casefold().replace(DOT, "")

    @property
    def text_with_url(self) -> str:
        """Text with URL in reStructuredText."""
        return f"`{self.text} <{self.url}>`_" if self.url else self.text

    def _pretty(self, attribute: str) -> str:
        value = getattr(self, attribute)
        if value is True:
            return EmojiEnum.GREEN_CHECK.value
        if value is False:
            return EmojiEnum.X_RED_CROSS.value
        if value == 0:
            return EmojiEnum.QUESTION_MARK.value
        return f"`#{value} <https://github.com/andreoliwa/nitpick/issues/{value}>`_ {EmojiEnum.CONSTRUCTION.value}"

    @property
    def check_str(self) -> str:
        """The check flag, as a string."""
        return self._pretty("check")

    @property
    def autofix_str(self) -> str:
        """The autofix flag, as a string."""
        return self._pretty("autofix")

    @property
    def row(self) -> tuple[str, str, str]:
        """Tuple for a table row."""
        return self.text_with_url, self.check_str, self.autofix_str


IMPLEMENTED_FILE_TYPES: set[FileType] = {
    FileType("Any INI file", f"{READ_THE_DOCS_URL}plugins.html#ini-files", True, True),
    FileType("Any JSON file", f"{READ_THE_DOCS_URL}plugins.html#json-files", True, True),
    FileType("Any plain text file", f"{READ_THE_DOCS_URL}plugins.html#text-files", True, False),
    FileType("Any TOML file", f"{READ_THE_DOCS_URL}plugins.html#toml-files", True, True),
    FileType("Any YAML file", f"{READ_THE_DOCS_URL}plugins.html#yaml-files", True, True),
    FileType(EDITOR_CONFIG, f"{READ_THE_DOCS_URL}library.html#any", True, True),
    FileType(PYTHON_PYLINTRC, f"{READ_THE_DOCS_URL}plugins.html#ini-files", True, True),
    FileType(PYTHON_SETUP_CFG, f"{READ_THE_DOCS_URL}plugins.html#ini-files", True, True),
}
PLANNED_FILE_TYPES: set[FileType] = {
    FileType("Any Markdown file", "", 280, 0),
    FileType("Any Terraform file", "", 318, 0),
    FileType(".dockerignore", "", 8, 8),
    FileType(".gitignore", "", 8, 8),
    FileType("Dockerfile", "", 272, 272),
    FileType("Jenkinsfile", "", 278, 0),
    FileType("Makefile", "", 277, 0),
}

nit = Nitpick.singleton().init()


class DocFile:  # pylint: disable=too-few-public-methods
    """A document file (REST or Markdown)."""

    def __init__(self, filename: str) -> None:
        self.file: Path = (DOCS_DIR / filename).resolve(True)
        if self.file.suffix == ".md":
            self.divider_start = MD_DIVIDER_START
            self.divider_end = MD_DIVIDER_END
            self.divider_from_here = MD_DIVIDER_START
        else:
            self.divider_start = RST_DIVIDER_START
            self.divider_end = RST_DIVIDER_END
            self.divider_from_here = RST_DIVIDER_FROM_HERE

    def write(self, lines: list[str], divider: str | None = None) -> int:
        """Write content to the file."""
        old_content = self.file.read_text()
        if divider:
            start_marker = self.divider_start.format(divider)
            end_marker = self.divider_end.format(divider)
            start_position = old_content.index(start_marker) + len(start_marker) + 1
            end_position = old_content.index(end_marker) - 1
        else:
            start_position = old_content.index(self.divider_from_here) + len(self.divider_from_here) + 1
            end_position = 0

        new_content = old_content[:start_position]
        new_content += "\n".join(lines)
        if end_position:
            new_content += old_content[end_position:]
        new_content = new_content.strip() + "\n"

        divider_message = f" (divider: {divider})" if divider else ""
        if old_content != new_content:
            self.file.write_text(new_content)
            click.secho(f"File {self.file}{divider_message} generated", fg="yellow")
            return 1

        click.secho(f"File {self.file}{divider_message} hasn't changed", fg="green")
        return 0


def write_plugins() -> int:
    """Write plugins.rst with the docstrings from :py:class:`nitpick.plugins.base.NitpickPlugin` classes."""
    template = """
        .. _{link}:

        {header}
        {dashes}

        {description}
    """
    clean_template = dedent(template).strip()
    blocks = []

    # Sort order: classes with fixed file names first, then alphabetically by class name
    for plugin_class in sorted(
        nit.project.plugin_manager.hook.plugin_class(),  # pylint: disable=no-member
        key=lambda c: "0" if c.filename else "1" + c.__name__,
    ):
        header = plugin_class.filename
        if not header:
            module = import_module(plugin_class.__module__)
            header = (module.__doc__ or "").strip(" .")

        blocks.append("")
        blocks.append(
            clean_template.format(
                link=slugify(plugin_class.__name__),
                header=header,
                dashes="-" * len(header),
                description=dedent(f"    {plugin_class.__doc__}").strip(),
            )
        )
    return DocFile("plugins.rst").write(blocks)


def write_cli() -> int:
    """Write CLI docs."""
    template = """
        .. _cli_cmd{anchor}:

        {header}
        {dashes}
        {long}

        .. code-block::

        {help}
    """
    clean_template = dedent(template).strip()
    blocks = []

    for command, short, long in CLI_MAPPING:
        anchor = f"_{command}" if command else ""
        header = f"``{command}``: {short}" if command else short
        blocks.append("")
        parts = ["nitpick"]
        if command:
            parts.append(command)
        parts.append("--help")
        print(" ".join(parts))
        output = check_output(parts).decode().strip()  # noqa: S603
        blocks.append(
            clean_template.format(
                anchor=anchor, header=header, dashes="-" * len(header), long=dedent(long), help=indent(output, "    ")
            )
        )

    return DocFile("cli.rst").write(blocks)


def write_config() -> int:
    """Write config file names."""
    blocks = [f"{index + 1}. ``{config_file}``" for index, config_file in enumerate(CONFIG_FILES)]
    blocks.insert(0, "")
    blocks.append("")
    return DocFile("configuration.rst").write(blocks, divider="config-file")


def rst_table(header: tuple[str, ...], rows: list[tuple[str, ...]]) -> list[str]:
    """Create a ReST table from header and rows."""
    blocks = [".. list-table::\n   :header-rows: 1\n"]
    num_columns = len(header)
    for row in [header, *rows]:
        template = ("*" + " - {}\n " * num_columns).rstrip()
        blocks.append(indent(template.format(*row), "   "))
    return blocks


def write_readme(file_types: set[FileType], divider: str) -> int:
    """Write the README."""
    # TODO: chore: quickstart.rst has some parts of README.rst as a copy/paste/change
    rows: list[tuple[str, ...]] = [file_type.row for file_type in sorted(file_types)]

    lines = rst_table(("File type", "``nitpick check``", "``nitpick fix``"), rows)
    return DocFile("../README.rst").write(lines, divider)


@attr.frozen(kw_only=True)
class StyleLibraryRow:  # pylint: disable=too-few-public-methods
    """Row in the style library."""

    style: str
    name: str


def _build_library(gitref: bool = True) -> list[str]:
    # pylint: disable=no-member
    library: dict[str, list[tuple]] = defaultdict(list)
    pre, post = (":gitref:", "") if gitref else ("", "_")
    for path in sorted(builtin_styles()):  # type: Path
        style = BuiltinStyle.from_path(path)

        # When run with tox (invoke ci-build), the path starts with "site-packages"
        path_from_repo_root = path.relative_to(repo_root()).as_posix()
        clean_root = path_from_repo_root.replace("site-packages/", "src/")

        row = StyleLibraryRow(
            style=f"{pre}`{style.formatted} <{clean_root}>`{post}",
            name=f"`{style.name} <{style.url}>`_" if style.url else style.name,
        )
        library[style.identify_tag].append(attr.astuple(row))

    lines = []
    for tag, rows in library.items():
        lines.extend(["", tag, "~" * len(tag), ""])
        lines.extend(
            rst_table(
                (
                    "Style URL",
                    "Description",
                ),
                rows,
            )
        )
    return lines


def write_style_library(divider: str) -> int:
    """Write the style library table."""
    lines = _build_library(gitref=False)
    rv = DocFile("../README.rst").write(lines, divider)

    lines = _build_library()
    rv += DocFile("library.rst").write(lines)
    return rv


if __name__ == "__main__":
    sys.exit(
        write_readme(IMPLEMENTED_FILE_TYPES, "implemented")
        + write_readme(PLANNED_FILE_TYPES, "planned")
        + write_style_library("style-library")
        + write_config()
        + write_plugins()
        + write_cli()
    )