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