From 1af36c6f21ccb8b4d99bb16af6d42b0d69e15484 Mon Sep 17 00:00:00 2001 From: jeanluc Date: Tue, 11 Apr 2023 09:52:38 +0200 Subject: [PATCH] chore: Update template --- .cruft.json | 6 +- .github/workflows/commitlint.yml | 1 - .pre-commit-config.yaml | 2 +- bin/slsdoc | 162 ++++++++++++++++++++++------ docs/map.jinja.rst | 1 - gitea/config/clean.sls | 4 +- gitea/config/file.sls | 4 +- gitea/go/clean.sls | 4 +- gitea/go/init.sls | 5 +- gitea/mods/rst/clean.sls | 5 +- gitea/mods/rst/init.sls | 11 +- gitea/package/clean.sls | 8 +- gitea/package/install.sls | 13 ++- gitea/post-map.jinja | 1 - gitea/service/clean.sls | 4 +- gitea/service/running.sls | 6 +- pillar.example | 2 +- test/integration/default/inspec.yml | 1 - 18 files changed, 164 insertions(+), 76 deletions(-) diff --git a/.cruft.json b/.cruft.json index 8f31f36..e23ab79 100644 --- a/.cruft.json +++ b/.cruft.json @@ -1,6 +1,6 @@ { "template": "https://github.com/lkubb/salt-template-formula", - "commit": "c33be7342f32db2e215f929e5a51a690ed445c11", + "commit": "a63c03d95375f235c2d4a6159a26ae48d4fdc40b", "checkout": null, "context": { "cookiecutter": { @@ -25,7 +25,7 @@ "subcomponent": "", "subcomponent_config": "", "git_username": "lkubb", - "_lookup": { + "lookup": { "paths": { "bin": "/opt/gitea", "conf": "/etc/gitea", @@ -75,7 +75,7 @@ "path": "/usr/local/bin/grst" } }, - "_settings": { + "settings": { "version": "latest", "service": { "requires_mount": [], diff --git a/.github/workflows/commitlint.yml b/.github/workflows/commitlint.yml index 42a5375..c722d15 100644 --- a/.github/workflows/commitlint.yml +++ b/.github/workflows/commitlint.yml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- name: Commitlint diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c4cd831..76a5ed0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -52,7 +52,7 @@ repos: always_run: true pass_filenames: false - repo: https://github.com/warpnet/salt-lint - rev: v0.8.0 + rev: v0.9.2 hooks: - id: salt-lint name: Check Salt files using salt-lint diff --git a/bin/slsdoc b/bin/slsdoc index 4ed7e78..45998cb 100755 --- a/bin/slsdoc +++ b/bin/slsdoc @@ -102,7 +102,26 @@ class State: self.comment = str(comment) self.formula_root = formula_root - def to_state_id(self, include_init=True, relative_to="", split=False, formula_root=False): + def to_state_id( + self, include_init=True, relative_to="", split=False, formula_root=False + ): + """ + Return this state's state ID. + + include_init + If False, remove ``.init`` suffix. Defaults to True. + + relative_to + Render the state ID relative to another state or file. + + split + Return a tuple of parts instead of a string. + + formula_root + If not using relative_to, include the formula's root + directory in the state ID (the actually correct one). + Defaults to False (for compatibility reasons). + """ ret = self.path.with_suffix("") if not include_init and ret.parts[-1] == "init": @@ -120,9 +139,15 @@ class State: return tuple(ret.split(".")) def is_init(self): + """ + Checks whether this is an ``.init`` state. + """ return self.path.parts[-1] == "init.sls" def is_clean(self): + """ + Checks whether this is a ``.clean`` state. + """ return self.path.parts[-1] == "clean.sls" def __str__(self): @@ -141,9 +166,17 @@ class StateRegistry: by some of the downstream classes. """ - def __init__(self, reg=None, states=None, prefixes=None, default_sort_fn=None, avoid_init_dup=True, sort_list=None): + def __init__( + self, + data=None, + states=None, + prefixes=None, + default_sort_fn=None, + avoid_init_dup=True, + sort_list=None, + ): # nested dict - self.reg = reg or {} + self.reg = data or {} # flat dict with ptr to reg self.states = states or {} # flat dict with ptr to reg @@ -152,7 +185,9 @@ class StateRegistry: # ensure no prefix lists the root self.prefixes[()] = self.reg self.avoid_init_dup = avoid_init_dup - self.sort_list = tuple(sort_list or ("init", "clean", "package", "config", "service")) + self.sort_list = tuple( + sort_list or ("init", "clean", "package", "config", "service") + ) def _default_sort(self, a): """ @@ -192,12 +227,15 @@ class StateRegistry: if isinstance(ptr, State) or tree: return ptr # map init.sls same way as salt does - elif "init" in ptr: + if "init" in ptr: return ptr["init"] raise ValueError("State could not be found. Most likely, this is a prefix.") def register(self, state): + """ + Register a state object. + """ try: state_id = state.to_state_id(split=True) except AttributeError as err: @@ -214,13 +252,16 @@ class StateRegistry: ptr[cur] = state break # make sure subdicts are initialized - elif cur not in ptr: + if cur not in ptr: ptr[cur] = {} self.prefixes[tuple(prefix)] = ptr[cur] ptr = ptr[cur] self.states[state_id] = ptr[cur] def unregister(self, state): + """ + Unregister a state object. + """ try: state_id = state.to_state_id(split=True) except AttributeError as err: @@ -259,6 +300,9 @@ class StateRegistry: return 0 def count(self): + """ + Return the number of registered states. + """ return len(self.states) def dump(self, prefix=None, sort_fn=None): @@ -269,7 +313,7 @@ class StateRegistry: if isinstance(prefix, str): prefix = tuple(prefix.split(".")) for state_id in sorted(self.states, key=sort_fn or self.default_sort_fn): - if state_id[:len(prefix)] == prefix: + if state_id[: len(prefix)] == prefix: if self.avoid_init_dup and state_id[-1] not in ["init", "clean"]: # given package.init, package.install and package.clean, # only dump init and clean @@ -318,7 +362,8 @@ The following states are found in {where}: """ if not hasattr(self, "f"): raise ValueError( - "Sorry, you need to set self.f to a file pointer before calling self._write methods." + "Sorry, you need to set self.f to a file pointer " + "before calling self._write methods." ) self.f.write(text + "\n" * ncount) @@ -373,10 +418,12 @@ The following states are found in {where}: Returns a string to be used as the main description (after the main header). Looks up in the following order: 1. If there is a documented root init.sls, return everything but its first line. - If it was found, unregister it to not render it twice (bad form again, maybe consider was_rendered on State) + If it was found, unregister it to not render it twice + (bad form again, maybe consider was_rendered on State) 2. If a description was specified in opts, return that. 3. general description """ + def get_default_desc(): return self.opts["default_description"].format( where=".".join(self.prefix) if self.prefix else "this formula" @@ -433,11 +480,18 @@ class SingleRenderer(Renderer): "include_formula_root": True, } - def __init__(self, target="docs/states.rst", prefix=None, basedir=base_dir, **kwargs): + def __init__( + self, target="docs/states.rst", prefix=None, basedir=base_dir, **kwargs + ): if isinstance(target, str): target = Path(target) target = target.with_suffix(".rst") - super().__init__(target=target, prefix=prefix, basedir=basedir, opts=self.default_opts | kwargs) + super().__init__( + target=target, + prefix=prefix, + basedir=basedir, + opts=self.default_opts | kwargs, + ) def render(self, states): relative_to = "/".join(self.prefix) if self.opts["cut_prefix"] else "" @@ -452,11 +506,19 @@ class SingleRenderer(Renderer): continue if not self.opts["clean"] and state.is_clean(): continue - state_id = state.to_state_id(self.opts["init_suffix"], relative_to, formula_root=self.opts["include_formula_root"]) + state_id = state.to_state_id( + self.opts["init_suffix"], + relative_to, + formula_root=self.opts["include_formula_root"], + ) if state_id == ".": continue self._write_heading( - state.to_state_id(self.opts["init_suffix"], relative_to, formula_root=self.opts["include_formula_root"]) + state.to_state_id( + self.opts["init_suffix"], + relative_to, + formula_root=self.opts["include_formula_root"], + ) ) self._write(state.comment, 3) @@ -499,13 +561,22 @@ class DepthRenderer(Renderer): "clean": False, "cut_prefix": True, "include_formula_root": False, - } + }, } - def __init__(self, max_depth=1, target="docs/states", delegate_cls=None, basedir=base_dir, **kwargs): + def __init__( + self, + max_depth=1, + target="docs/states", + delegate_cls=None, + basedir=base_dir, + **kwargs, + ): self.max_depth = max_depth self.delegate = delegate_cls or SingleRenderer - super().__init__(target=target, basedir=basedir, opts=self.default_opts | (kwargs or {})) + super().__init__( + target=target, basedir=basedir, opts=self.default_opts | (kwargs or {}) + ) def render(self, states): found = [] @@ -519,10 +590,9 @@ class DepthRenderer(Renderer): # This also goes not too well with rendering clean states # by default since they will be separate. if cur_top: - if prefix[:len(cur_top)] == cur_top: + if prefix[: len(cur_top)] == cur_top: continue - else: - cur_top = () + cur_top = () if states.depth(prefix) <= self.max_depth: found.append(prefix) cur_top = prefix @@ -560,8 +630,10 @@ class DepthRenderer(Renderer): def _render_single(self, states, prefix): target = self._get_target(prefix) - renderer = self.delegate(target=target, prefix=prefix, **self.opts["single_opts"]) - renderer.render(states) + rendr = self.delegate( + target=target, prefix=prefix, **self.opts["single_opts"] + ) + rendr.render(states) def _render_index(self, states, indices, prefix=None): prefix = prefix or () @@ -571,12 +643,14 @@ class DepthRenderer(Renderer): self.prefix = prefix self._write_header(states) self.prefix = () - f.write(f""" + f.write( + f""" .. toctree:: :maxdepth: {self.opts['index_maxdepth']} :caption: Contents: -""") +""" + ) for s in sorted(indices["_index"]): f.write(" " + s + "\n") for sub in sorted(indices): @@ -605,7 +679,15 @@ class SaltAutodoc: SKIP_FILE = "@internal" - def __init__(self, base=None, renderer=None, registry=None, env=None, include_empty=False, ignore=None): + def __init__( + self, + base=None, + rendr=None, + registry=None, + env=None, + include_empty=False, + ignore=None, + ): """ base: base path containing Salt states to autodocument renderer: renderer to use for rendering @@ -613,7 +695,7 @@ class SaltAutodoc: if base is None: base = list(base_dir.glob("*/init.sls"))[0].parent self.base = base - self.renderer = renderer or SingleRenderer() + self.renderer = rendr or SingleRenderer() self.env = env or Environment() self.registry = registry or StateRegistry() self.include_empty = include_empty @@ -633,12 +715,14 @@ class SaltAutodoc: text = "".join(f.readlines()) try: comment = self.find_comment(text) - except TemplateSyntaxError as e: + except TemplateSyntaxError as err: raise RuntimeError( - f"There was an error parsing the Jinja syntax in file '{file}':\n\n{e}" - ) + f"There was an error parsing the Jinja syntax in file '{file}':\n\n{err}" + ) from err - if (comment or self.include_empty) and not comment.startswith(self.SKIP_FILE): + if (comment or self.include_empty) and not comment.startswith( + self.SKIP_FILE + ): path = file.relative_to(self.base) self.registry.register(State(path, comment, self.base.name)) @@ -676,12 +760,16 @@ class SaltAutodoc: docutils.prepare_docstring. """ # return d.prepare_docstring(comment) - ws = min([len(x) - len(x.lstrip()) for x in comment.splitlines() if len(x) > 0]) + ws = min(len(x) - len(x.lstrip()) for x in comment.splitlines() if len(x) > 0) return "\n".join([x[ws:] for x in comment.splitlines()]).strip("\n") if __name__ == "__main__": - options = toml.loads((base_dir / "pyproject.toml").read_text()).get("tool", {}).get("slsdoc", {}) + options = ( + toml.loads((base_dir / "pyproject.toml").read_text()) + .get("tool", {}) + .get("slsdoc", {}) + ) renderer = options.get("renderer", "single") if renderer == "single": @@ -691,6 +779,14 @@ if __name__ == "__main__": else: raise ValueError(f"Invalid value for renderer: {renderer}") - registry = StateRegistry(avoid_init_dup=options.get("avoid_init_dup", True), sort_list=options.get("sort_list")) - doc = SaltAutodoc(renderer=rend, registry=registry, include_empty=options.get("include_empty", False), ignore=options.get("ignore", ["_mapdata"])) + reg = StateRegistry( + avoid_init_dup=options.get("avoid_init_dup", True), + sort_list=options.get("sort_list"), + ) + doc = SaltAutodoc( + rendr=rend, + registry=reg, + include_empty=options.get("include_empty", False), + ignore=options.get("ignore", ["_mapdata"]), + ) doc.run() diff --git a/docs/map.jinja.rst b/docs/map.jinja.rst index 3d07843..72f8754 100644 --- a/docs/map.jinja.rst +++ b/docs/map.jinja.rst @@ -474,7 +474,6 @@ Here is an example based on `template-formula/gitea/config/file.sls`_: .. code-block:: sls - # -*- coding: utf-8 -*- # vim: ft=sls {#- Get the `tplroot` from `tpldir` #} diff --git a/gitea/config/clean.sls b/gitea/config/clean.sls index bf471f8..e88788e 100644 --- a/gitea/config/clean.sls +++ b/gitea/config/clean.sls @@ -4,8 +4,8 @@ Removes Gitea configuration. Has a dependency on `gitea.service.clean`_. #} -{%- set tplroot = tpldir.split('/')[0] %} -{%- set sls_service_clean = tplroot ~ '.service.clean' %} +{%- set tplroot = tpldir.split("/")[0] %} +{%- set sls_service_clean = tplroot ~ ".service.clean" %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} include: diff --git a/gitea/config/file.sls b/gitea/config/file.sls index 3972f64..f302780 100644 --- a/gitea/config/file.sls +++ b/gitea/config/file.sls @@ -1,7 +1,7 @@ # vim: ft=sls -{%- set tplroot = tpldir.split('/')[0] %} -{%- set sls_package_install = tplroot ~ '.package.install' %} +{%- set tplroot = tpldir.split("/")[0] %} +{%- set sls_package_install = tplroot ~ ".package.install" %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} {%- from tplroot ~ "/libtofs.jinja" import files_switch with context %} diff --git a/gitea/go/clean.sls b/gitea/go/clean.sls index 7718577..56ba04f 100644 --- a/gitea/go/clean.sls +++ b/gitea/go/clean.sls @@ -4,8 +4,8 @@ Removes the build user and Go installation. #} -{%- set tplroot = tpldir.split('/')[0] %} -{%- set sls_config_file = tplroot ~ '.config.file' %} +{%- set tplroot = tpldir.split("/")[0] %} +{%- set sls_config_file = tplroot ~ ".config.file" %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} Go is absent for build user: diff --git a/gitea/go/init.sls b/gitea/go/init.sls index cfbca07..503292d 100644 --- a/gitea/go/init.sls +++ b/gitea/go/init.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=sls {#- @@ -6,8 +5,8 @@ Required for building Chroma. #} -{%- set tplroot = tpldir.split('/')[0] %} -{%- set sls_config_file = tplroot ~ '.config.file' %} +{%- set tplroot = tpldir.split("/")[0] %} +{%- set sls_config_file = tplroot ~ ".config.file" %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} Gitea build user is present: diff --git a/gitea/mods/rst/clean.sls b/gitea/mods/rst/clean.sls index 69728d9..b0b8789 100644 --- a/gitea/mods/rst/clean.sls +++ b/gitea/mods/rst/clean.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=sls {#- @@ -6,8 +5,8 @@ ``grst`` script. #} -{%- set tplroot = tpldir.split('/')[0] %} -{%- set sls_config_file = tplroot ~ '.config.file' %} +{%- set tplroot = tpldir.split("/")[0] %} +{%- set sls_config_file = tplroot ~ ".config.file" %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} {%- from tplroot ~ "/libtofs.jinja" import files_switch with context %} diff --git a/gitea/mods/rst/init.sls b/gitea/mods/rst/init.sls index 21b1cac..76d82b6 100644 --- a/gitea/mods/rst/init.sls +++ b/gitea/mods/rst/init.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=sls {#- @@ -9,9 +8,9 @@ Has a dependency on `gitea.go`_. #} -{%- set tplroot = tpldir.split('/')[0] %} -{%- set sls_config_file = tplroot ~ '.config.file' %} -{%- set sls_go_install = tplroot ~ '.go' %} +{%- set tplroot = tpldir.split("/")[0] %} +{%- set sls_config_file = tplroot ~ ".config.file" %} +{%- set sls_go_install = tplroot ~ ".go" %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} {%- from tplroot ~ "/libtofs.jinja" import files_switch with context %} @@ -60,9 +59,9 @@ Chroma is installed: RST external renderer is installed: file.managed: - name: {{ gitea.lookup.mod_rst.path }} - - source: {{ files_switch(['grst'], + - source: {{ files_switch(["grst"], use_subpath=True, - lookup='RST external renderer is installed' + lookup="RST external renderer is installed" ) }} - mode: '0755' diff --git a/gitea/package/clean.sls b/gitea/package/clean.sls index 053a0bb..7ad9ca2 100644 --- a/gitea/package/clean.sls +++ b/gitea/package/clean.sls @@ -5,8 +5,8 @@ Has a dependency on `gitea.config.clean`_. #} -{%- set tplroot = tpldir.split('/')[0] %} -{%- set sls_config_clean = tplroot ~ '.config.clean' %} +{%- set tplroot = tpldir.split("/")[0] %} +{%- set sls_config_clean = tplroot ~ ".config.clean" %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} include: @@ -17,8 +17,8 @@ Gitea package files are absent: file.absent: - names: - {{ gitea.lookup.service.unit.format(name=gitea.lookup.service.name) }} - - {{ gitea.lookup.paths.bin | path_join('gitea') }} -{%- for p in ['conf', 'custom', 'log'] %} + - {{ gitea.lookup.paths.bin | path_join("gitea") }} +{%- for p in ["conf", "custom", "log"] %} - {{ gitea.lookup.paths[p] }} {%- endfor %} # to make sure this can be installed again (onchanges req in package.installed) diff --git a/gitea/package/install.sls b/gitea/package/install.sls index 26254b6..0884109 100644 --- a/gitea/package/install.sls +++ b/gitea/package/install.sls @@ -1,7 +1,6 @@ -# -*- coding: utf-8 -*- # vim: ft=sls -{%- set tplroot = tpldir.split('/')[0] %} +{%- set tplroot = tpldir.split("/")[0] %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} {%- from tplroot ~ "/libtofs.jinja" import files_switch with context %} @@ -112,7 +111,7 @@ Gitea binary is absent if verification failed: Gitea directories are setup: file.directory: - names: -{%- for p in ['conf', 'work', 'custom', 'data', 'log', 'repos'] %} +{%- for p in ["conf", "work", "custom", "data", "log", "repos"] %} - {{ gitea.lookup.paths[p] }} {%- endfor %} - makedirs: true @@ -123,7 +122,7 @@ Gitea directories are setup: Gitea binary is installed: file.copy: - - name: {{ gitea.lookup.paths.bin | path_join('gitea') }} + - name: {{ gitea.lookup.paths.bin | path_join("gitea") }} - source: /tmp/gitea-{{ gitea.version }} # in case the version changed, overwrite previous binary - force: true @@ -141,15 +140,15 @@ Gitea service unit is available: file.managed: - name: {{ gitea.lookup.service.unit.format(name=gitea.lookup.service.name) }} - source: {{ files_switch( - ['gitea.service.j2'], - lookup='Gitea service unit is available', + ["gitea.service.j2"], + lookup="Gitea service unit is available", ) }} - template: jinja - mode: '0644' - user: root - group: {{ gitea.lookup.rootgroup }} - makedirs: true - - context: {{ {'gitea': gitea} | json }} + - context: {{ {"gitea": gitea} | json }} - require: - Gitea binary is installed {%- if 'systemctl' | which %} diff --git a/gitea/post-map.jinja b/gitea/post-map.jinja index 031bb61..bca0a0a 100644 --- a/gitea/post-map.jinja +++ b/gitea/post-map.jinja @@ -1,4 +1,3 @@ -{#- -*- coding: utf-8 -*- #} {#- vim: ft=jinja #} {#- If latest was specified, query the official download server for the latest version. -#} diff --git a/gitea/service/clean.sls b/gitea/service/clean.sls index 3fc4421..640b94c 100644 --- a/gitea/service/clean.sls +++ b/gitea/service/clean.sls @@ -4,10 +4,10 @@ Stops the gitea service and disables it at boot time. #} -{%- set tplroot = tpldir.split('/')[0] %} +{%- set tplroot = tpldir.split("/")[0] %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} Gitea is dead: service.dead: - name: {{ gitea.lookup.service.name }} - - enable: False + - enable: false diff --git a/gitea/service/running.sls b/gitea/service/running.sls index 43e0123..cbf0baa 100644 --- a/gitea/service/running.sls +++ b/gitea/service/running.sls @@ -1,7 +1,7 @@ # vim: ft=sls -{%- set tplroot = tpldir.split('/')[0] %} -{%- set sls_config_file = tplroot ~ '.config.file' %} +{%- set tplroot = tpldir.split("/")[0] %} +{%- set sls_config_file = tplroot ~ ".config.file" %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} include: @@ -10,7 +10,7 @@ include: Gitea is running: service.running: - name: {{ gitea.lookup.service.name }} - - enable: True + - enable: true - watch: - sls: {{ sls_config_file }} - Gitea binary is installed diff --git a/pillar.example b/pillar.example index 6886117..fe28700 100644 --- a/pillar.example +++ b/pillar.example @@ -139,6 +139,6 @@ gitea: # The entries under `source_files` are prepended to the default source files # given for the state source_files: - gitea-config-file-file-managed: + Gitea configuration is managed: - 'app_alt.ini' - 'app_alt.ini.jinja' diff --git a/test/integration/default/inspec.yml b/test/integration/default/inspec.yml index 93e94bc..0ebd430 100644 --- a/test/integration/default/inspec.yml +++ b/test/integration/default/inspec.yml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- name: default