ansible-doctor/ansibledoctor/doc_generator.py

181 lines
6.9 KiB
Python
Raw Normal View History

2019-10-07 06:52:00 +00:00
#!/usr/bin/env python3
2019-10-08 09:39:27 +00:00
"""Prepare output and write compiled jinja2 templates."""
2019-10-07 06:52:00 +00:00
import json
2019-10-07 06:52:00 +00:00
import os
import re
2019-10-08 09:30:31 +00:00
from functools import reduce
2019-10-08 09:39:27 +00:00
2019-10-07 06:52:00 +00:00
import jinja2.exceptions
import ruamel.yaml
import structlog
from jinja2 import Environment, FileSystemLoader
from jinja2.filters import pass_eval_context
2019-10-07 06:52:00 +00:00
from ansibledoctor.config import SingleConfig
from ansibledoctor.template import Template
from ansibledoctor.utils import FileUtils, sysexit_with_message
2019-10-07 06:52:00 +00:00
class Generator:
2020-04-05 21:16:53 +00:00
"""Generate documentation from jinja2 templates."""
2019-10-07 06:52:00 +00:00
def __init__(self, doc_parser):
self.log = structlog.get_logger()
self.config = SingleConfig()
self.template = Template(
self.config.config.get("template.name"),
self.config.config.get("template.src"),
)
2019-10-07 06:52:00 +00:00
self._parser = doc_parser
def _create_dir(self, directory):
if not self.config.config["dry_run"] and not os.path.isdir(directory):
try:
os.makedirs(directory, exist_ok=True)
self.log.info(f"Creating dir: {directory}")
except FileExistsError as e:
sysexit_with_message(e)
2019-10-07 06:52:00 +00:00
def _write_doc(self):
files_to_overwite = []
for tf in self.template.files:
2020-04-05 21:16:53 +00:00
doc_file = os.path.join(
self.config.config.get("renderer.dest"), os.path.splitext(tf)[0]
2020-04-05 21:16:53 +00:00
)
2019-10-07 06:52:00 +00:00
if os.path.isfile(doc_file):
files_to_overwite.append(doc_file)
header_file = self.config.config.get("renderer.include_header")
role_data = self._parser.get_data()
header_content = ""
if bool(header_file):
role_data["internal"]["append"] = True
try:
with open(header_file) as a:
header_content = a.read()
except FileNotFoundError as e:
sysexit_with_message("Can not open custom header file", path=header_file, error=e)
if (
len(files_to_overwite) > 0
and self.config.config.get("renderer.force_overwrite") is False
and not self.config.config["dry_run"]
):
files_to_overwite_string = "\n".join(files_to_overwite)
prompt = f"These files will be overwritten:\n{files_to_overwite_string}".replace(
"\n", "\n... "
)
try:
if not FileUtils.query_yes_no(f"{prompt}\nDo you want to continue?"):
sysexit_with_message("Aborted...")
except KeyboardInterrupt:
sysexit_with_message("Aborted...")
2019-10-07 06:52:00 +00:00
for tf in self.template.files:
2020-04-05 21:16:53 +00:00
doc_file = os.path.join(
self.config.config.get("renderer.dest"), os.path.splitext(tf)[0]
2020-04-05 21:16:53 +00:00
)
template = os.path.join(self.template.path, tf)
2019-10-07 06:52:00 +00:00
self.log.debug("Writing renderer output", path=doc_file, src=os.path.dirname(template))
2019-10-07 06:52:00 +00:00
# make sure the directory exists
self._create_dir(os.path.dirname(doc_file))
2019-10-07 06:52:00 +00:00
if os.path.exists(template) and os.path.isfile(template):
with open(template) as template:
2019-10-07 06:52:00 +00:00
data = template.read()
if data is not None:
try:
2020-04-05 21:28:39 +00:00
jenv = Environment( # nosec
loader=FileSystemLoader(self.template.path),
2020-04-05 21:16:53 +00:00
lstrip_blocks=True,
trim_blocks=True,
autoescape=jinja2.select_autoescape(),
2020-04-05 21:28:39 +00:00
)
2019-10-07 06:52:00 +00:00
jenv.filters["to_nice_yaml"] = self._to_nice_yaml
jenv.filters["to_code"] = self._to_code
2019-10-08 09:30:31 +00:00
jenv.filters["deep_get"] = self._deep_get
jenv.filters["safe_join"] = self._safe_join
# keep the old name of the function to not break custom templates.
jenv.filters["save_join"] = self._safe_join
template_options = self.config.config.get("template.options")
data = jenv.from_string(data).render(
role_data, role=role_data, options=template_options
)
2019-10-08 22:56:39 +00:00
if not self.config.config["dry_run"]:
with open(doc_file, "wb") as outfile:
outfile.write(header_content.encode("utf-8"))
outfile.write(data.encode("utf-8"))
2020-04-05 21:16:53 +00:00
except (
jinja2.exceptions.UndefinedError,
jinja2.exceptions.TemplateSyntaxError,
jinja2.exceptions.TemplateRuntimeError,
2020-04-05 21:16:53 +00:00
) as e:
sysexit_with_message(
"Jinja2 template error while loading file", path=tf, error=e
2020-04-05 21:16:53 +00:00
)
2019-10-07 06:52:00 +00:00
except UnicodeEncodeError as e:
sysexit_with_message("Failed to print special characters", error=e)
2019-10-07 06:52:00 +00:00
def _to_nice_yaml(self, a, indent=4, **kw):
2019-10-07 06:52:00 +00:00
"""Make verbose, human readable yaml."""
yaml = ruamel.yaml.YAML()
yaml.indent(mapping=indent, sequence=(indent * 2), offset=indent)
stream = ruamel.yaml.compat.StringIO()
yaml.dump(a, stream, **kw)
return stream.getvalue().rstrip()
def _to_code(self, a, to_multiline=False, tab_var=False, preserve_ms=False, lang="plain"):
"""Wrap a string in backticks."""
if a is None or a == "":
return ""
if (isinstance(a, list) and len(a) < 1) or (isinstance(a, dict) and not a):
return ""
if isinstance(a, list) and len(a) > 1 and preserve_ms:
return a
if isinstance(a, list) and len(a) == 1:
return f"`{self._tab_var(a[0], tab_var)}`"
if (isinstance(a, list)) and to_multiline:
return "```" + lang + "\n" + "\n".join(a) + "\n```"
return f"`{self._tab_var(a, tab_var)}`"
def _tab_var(self, a, tab_var):
"""Wrap a string in backticks."""
if not tab_var:
return a
return json.dumps(a)
def _deep_get(self, _, dictionary, keys):
2019-10-08 09:30:31 +00:00
default = None
2020-04-05 21:16:53 +00:00
return reduce(
lambda d, key: d.get(key, default) if isinstance(d, dict) else default,
keys.split("."),
dictionary,
2020-04-05 21:16:53 +00:00
)
2019-10-08 09:30:31 +00:00
@pass_eval_context
def _safe_join(self, eval_ctx, value, d=""):
if isinstance(value, str):
value = [value]
normalized = jinja2.filters.do_join(eval_ctx, value, d, attribute=None)
if self.config.config.renderer.autotrim:
for s in [r" +(\n|\t| )", r"(\n|\t) +"]:
normalized = re.sub(s, "\\1", normalized)
return jinja2.filters.do_mark_safe(normalized)
2019-10-07 06:52:00 +00:00
def render(self):
self._write_doc()