1"""Utils to generate rule table .rst documentation."""
2import logging
3from typing import Iterable
4
5from rich import box
6from rich.console import render_group
7from rich.markdown import Markdown
8from rich.table import Table
9
10from ansiblelint.rules import RulesCollection
11
12DOC_HEADER = """
13.. _lint_default_rules:
14
15Default Rules
16=============
17
18.. contents::
19   :local:
20
21Below you can see the list of default rules Ansible Lint use to evaluate playbooks and roles:
22
23"""
24
25_logger = logging.getLogger(__name__)
26
27
28def rules_as_str(rules: RulesCollection) -> str:
29    """Return rules as string."""
30    return str(rules)
31
32
33def rules_as_rst(rules: RulesCollection) -> str:
34    """Return RST documentation for a list of rules."""
35    r = DOC_HEADER
36
37    for d in rules:
38
39        title = f"{d.id}"
40
41        description = d.description
42        if d.link:
43            description += " `(more) <%s>`__" % d.link
44
45        r += f"\n\n.. _{d.id}:\n\n{title}\n{'*' * len(title)}\n\n{d.shortdesc}\n\n{description}"
46
47    return r
48
49
50@render_group()
51def rules_as_rich(rules: RulesCollection) -> Iterable[Table]:
52    """Print documentation for a list of rules, returns empty string."""
53    width = max(16, *[len(rule.id) for rule in rules])
54    for rule in rules:
55        table = Table(show_header=True, header_style="title", box=box.MINIMAL)
56        table.add_column(rule.id, style="dim", width=width)
57        table.add_column(Markdown(rule.shortdesc))
58        description = rule.description
59        if rule.link:
60            description += " [(more)](%s)" % rule.link
61        table.add_row("description", Markdown(description))
62        if rule.version_added:
63            table.add_row("version_added", rule.version_added)
64        if rule.tags:
65            table.add_row("tags", ", ".join(rule.tags))
66        if rule.severity:
67            table.add_row("severity", rule.severity)
68        yield table
69