From c58b3ea081988d519376fbb15336514efbf58ec9 Mon Sep 17 00:00:00 2001 From: jeanluc Date: Sun, 5 Feb 2023 18:55:53 +0100 Subject: [PATCH] feat: Update template --- .cruft.json | 2 +- .gitlab-ci.yml | 1 - .pre-commit-config.yaml | 10 +- .rubocop.yml | 1 - .salt-lint | 5 - .travis.yml | 1 - .yamllint | 1 - bin/render_readme | 8 + bin/slsdoc | 471 +++++++++++++++--------- docs/README.rst | 88 +++-- docs/README.rst.tpl | 150 ++++++++ docs/states.rst | 83 ++++- gitea/_mapdata/init.sls | 1 - gitea/clean.sls | 13 +- gitea/config/clean.sls | 8 +- gitea/config/file.sls | 9 +- gitea/config/init.sls | 6 +- gitea/init.sls | 9 +- gitea/libmapstack.jinja | 1 - gitea/libmatchers.jinja | 1 - gitea/libsaltcli.jinja | 1 - gitea/map.jinja | 1 - gitea/package/clean.sls | 6 +- gitea/package/init.sls | 5 +- gitea/parameters/defaults.yaml | 1 - gitea/parameters/os_family/Arch.yaml | 1 - gitea/parameters/os_family/Debian.yaml | 1 - gitea/parameters/os_family/FreeBSD.yaml | 1 - gitea/parameters/os_family/Gentoo.yaml | 1 - gitea/parameters/os_family/MacOS.yaml | 1 - gitea/parameters/os_family/OpenBSD.yaml | 1 - gitea/parameters/os_family/RedHat.yaml | 1 - gitea/parameters/os_family/Suse.yaml | 1 - gitea/parameters/osarch/386.yaml | 1 - gitea/parameters/osarch/amd64.yaml | 1 - gitea/parameters/osarch/arm64.yaml | 1 - gitea/parameters/osarch/armv6l.yaml | 1 - gitea/parameters/osarch/armv7l.yaml | 1 - gitea/parameters/osarch/ppc64le.yaml | 1 - gitea/parameters/osarch/s390x.yaml | 1 - gitea/parameters/osarch/x86_64.yaml | 1 - gitea/service/clean.sls | 7 +- gitea/service/init.sls | 6 +- gitea/service/running.sls | 3 +- kitchen.yml | 1 - pillar.example | 1 - pyproject.toml | 14 + test/integration/share/inspec.yml | 1 - test/salt/pillar/default.sls | 1 - test/salt/pillar/define_roles.sls | 1 - test/salt/pillar/gentoo.sls | 1 - test/salt/pillar/top.sls | 1 - test/salt/pillar/upstart.sls | 1 - 53 files changed, 672 insertions(+), 265 deletions(-) create mode 100755 bin/render_readme create mode 100644 docs/README.rst.tpl diff --git a/.cruft.json b/.cruft.json index 2b4c5e5..a8c4706 100644 --- a/.cruft.json +++ b/.cruft.json @@ -1,6 +1,6 @@ { "template": "https://github.com/lkubb/salt-template-formula", - "commit": "09d23d7be4069023a5dd2201c3db5b82049391a1", + "commit": "ec0d8da5021bc9320ca1270e582ab9ac604f2ad7", "checkout": null, "context": { "cookiecutter": { diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 56e1e30..ce6bf8b 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- ############################################################################### diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0557744..c4cd831 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- # See https://pre-commit.com for more information @@ -67,6 +66,15 @@ repos: require_serial: true always_run: true pass_filenames: false + - repo: local + hooks: + - id: render_readme + name: Render available states in README.rst.tpl + entry: ./bin/render_readme + language: system + require_serial: true + always_run: true + pass_filenames: false - repo: https://github.com/myint/rstcheck rev: 3f929574 hooks: diff --git a/.rubocop.yml b/.rubocop.yml index bf4d107..3172b00 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- # General overrides used across formulas in the org diff --git a/.salt-lint b/.salt-lint index 3715677..77703a9 100644 --- a/.salt-lint +++ b/.salt-lint @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- exclude_paths: [] @@ -6,9 +5,5 @@ rules: {} skip_list: # Using `salt-lint` for linting other files as well, such as Jinja macros/templates - 205 # Use ".sls" as a Salt State file extension - # Skipping `207` and `208` because `210` is sufficient, at least for the time-being - # I.e. Allows 3-digit unquoted codes to still be used, such as `644` and `755` - - 207 # File modes should always be encapsulated in quotation marks - - 208 # File modes should always contain a leading zero tags: [] verbosity: 1 diff --git a/.travis.yml b/.travis.yml index 834ff23..a531481 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- ################################################################################ diff --git a/.yamllint b/.yamllint index 716baaf..ab41f76 100644 --- a/.yamllint +++ b/.yamllint @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- # Extend the `default` configuration provided by `yamllint` diff --git a/bin/render_readme b/bin/render_readme new file mode 100755 index 0000000..0793671 --- /dev/null +++ b/bin/render_readme @@ -0,0 +1,8 @@ +#!/usr/bin/env sh + +# This inserts the rendered state docs into the readme. +# Avoids issues with rendering the final readme on Gitea etc. +sed '//{ + s///g + r docs/states.rst +}' docs/README.rst.tpl > docs/README.rst diff --git a/bin/slsdoc b/bin/slsdoc index e63e7fa..946950f 100755 --- a/bin/slsdoc +++ b/bin/slsdoc @@ -1,23 +1,86 @@ #!/usr/bin/env python3 -""" +''' This script renders Jinja comments found at the beginning -of `.sls` files. +of `.sls` files as state documentation. -Since this was written for the salt tool suite, -it should be placed in a sibling directory -of a directory named tool_ containing -the actual states to be able autodiscover them. +The code is horrible, but I'm too lazy to rewrite it properly +because it works for my use cases. There will likely be a lot of bugs. -Of course, it can be used by other formulae by manually -providing the root path and I might publish this at some -point as a python module or at least in a separate repo -to be used by pre-commit. It would need to be configurable -without editing the source code for that. @TODO +Full configuration in ``pyproject.toml`` with defaults: + +[tool.slsdoc] + # Choose which renderer to use. `single` or `depth` +renderer = "single" + # Also list states without documentation +include_empty = false + # Path prefixes to ignore, relative to formula root +ignore = ["_mapdata"] + # Given a directory with `package.init`, `package.install` + # and `package.clean`, only dump init and clean. +avoid_init_dup = True + # By default, states are ordered alphabetically, but init + # always comes first and all clean states are separated. + # This overrides the purely alphabetical order for the roots. +sort_list = ["init", "clean", "package", "config", "service"] + +[tool.slsdoc.single_renderer] + # Include init.sls files in state list +init = true + # Include .init suffix in when init is true +init_suffix = false + # Include clean.sls files in state list +clean = true + # When rendering with prefix `settings.something`, + # write `else` instead of `settings.something.else` +cut_prefix = false + # Write `salt.package` instead of `package` when formula root == `salt` +include_formula_root = true + # Default .rst main header, when not defined in root init.sls +default_header = "Available States" + # Header, overrides everything +header = "" + # Description, overrides everything +description = "" + # Default description, when init.sls is empty +default_description = """ +.. contents:: + :local: """ + # Always append default description, regardless of + # presence in init.sls +always_include_default_description = false + # Character to use to underline main headings +main_heading_char = "=" + # Character to use to underline sub headings +sub_heading_char = "^" +""" + # File to write to +target = "docs/states.rst" + +[tool.slsdoc.depth_renderer] + # maxdepth for generated index.rst files (toctree) +index_maxdepth = 4 + # Directory to write to +target = "docs/states" + +[tool.slsdoc.depth_renderer.single_opts] + # Include init.sls files in state list +init = false + # Include .init suffix in when init is true +init_suffix = false + # Include clean.sls files in state list +clean = false + # When rendering with prefix `settings.something`, + # write `else` instead of `settings.something.else` +cut_prefix = true + # Write `salt.package` instead of `package` when formula root == `salt` +include_formula_root = false +''' from pathlib import Path +import toml from jinja2 import Environment from jinja2.exceptions import TemplateSyntaxError @@ -31,27 +94,38 @@ class State: Object representing a documented state. """ - def __init__(self, path, comment): + def __init__(self, path, comment, formula_root): + if not isinstance(path, Path): + path = Path(path) self.path = path - self.comment = comment + self.comment = str(comment) + self.formula_root = formula_root - def tostateid(self, include_init=True, relative_to=""): + def to_state_id(self, include_init=True, relative_to="", split=False, formula_root=False): ret = self.path.with_suffix("") - if not include_init and "init" == ret.parts[-1]: + if not include_init and ret.parts[-1] == "init": ret = ret.parent if relative_to: relative_to = Path(relative_to.replace(".", "/")) ret = ret.relative_to(relative_to) + elif formula_root: + ret = Path(self.formula_root) / ret - return str(ret).replace("/", ".") + ret = str(ret).replace("/", ".") + if not split: + return ret + return tuple(ret.split(".")) - def isinit(self): - return "init.sls" == self.path.parts[-1] + def is_init(self): + return self.path.parts[-1] == "init.sls" - def isclean(self): - return "clean.sls" == self.path.parts[-1] + def is_clean(self): + return self.path.parts[-1] == "clean.sls" + + def __str__(self): + return self.to_state_id() class StateRegistry: @@ -66,16 +140,36 @@ class StateRegistry: by some of the downstream classes. """ - def __init__(self, reg=None, states=None, prefixes=None): - if reg is None: - reg = {} - if states is None: - states = [] - if prefixes is None: - prefixes = [] - self.reg = reg - self.states = states - self.prefixes = prefixes + def __init__(self, reg=None, states=None, prefixes=None, default_sort_fn=None, avoid_init_dup=True, sort_list=None): + # nested dict + self.reg = reg or {} + # flat dict with ptr to reg + self.states = states or {} + # flat dict with ptr to reg + self.prefixes = prefixes or {} + self.default_sort_fn = default_sort_fn or self._default_sort + # 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")) + + def _default_sort(self, a): + """ + Sort prefixes package > config > service, rest alphabetically. + Init always comes first. Clean states are separated. + """ + sort_key = () + if a[0] in self.sort_list: + sort_key += (str(self.sort_list.index(a[0])),) + else: + sort_key += (str(len(self.sort_list)),) + if a[-1] == "init": + sort_key += a[:-1] + elif a[-1] == "clean": + sort_key = ("zzzzzzzzz",) + sort_key + a[:-1] + else: + sort_key += a + return sort_key def lookup(self, state, tree=False): """ @@ -85,6 +179,7 @@ class StateRegistry: ptr = self.reg if isinstance(state, str): state = state.split(".") + state = list(state) try: while state: @@ -99,43 +194,53 @@ class StateRegistry: elif "init" in ptr: return ptr["init"] - raise ValueError("State could not be found.") + raise ValueError("State could not be found. Most likely, this is a prefix.") def register(self, state): - state_id = state.tostateid() - self.states.append(state_id) - - parts = state_id.split(".") + try: + state_id = state.to_state_id(split=True) + except AttributeError as err: + raise ValueError("`state` argument must be an instance of `State`") from err ptr = self.reg - prefix = "" + prefix = [] + parts = list(state_id) - while len(parts) > 1: + while len(parts): cur = parts.pop(0) - prefix = (prefix + "." + cur) if prefix else cur + prefix = prefix + [cur] + if not parts: + ptr[cur] = state + break # make sure subdicts are initialized - if cur not in ptr: + elif cur not in ptr: ptr[cur] = {} - self.prefixes.append(prefix) + self.prefixes[tuple(prefix)] = ptr[cur] ptr = ptr[cur] - - ptr[parts.pop(0)] = state - - self.prefixes.sort() - self.states.sort() + self.states[state_id] = ptr[cur] def unregister(self, state): - state_id = state.tostateid() - self.states.remove(state_id) + try: + state_id = state.to_state_id(split=True) + except AttributeError as err: + raise ValueError("`state` argument must be an instance of `State`") from err + try: + self.states.pop(state_id) + except KeyError as err: + raise RuntimeError(f"Specified state {state} was not registered") from err - if state_id.find("."): - path, key = state_id.rsplit(".", maxsplit=1) - parent = self.lookup(path, tree=True) - else: - parent = self.reg - key = state_id + parts = list(state_id) + first_run = True - del parent[key] + while parts: + key = parts.pop() + parent = self.lookup(parts, tree=True) + if first_run: + del parent[key] + elif not len(parent[key]): + self.prefixes.pop(tuple(parts + [key])) + del parent[key] + first_run = False def depth(self, prefix=""): """ @@ -155,14 +260,22 @@ class StateRegistry: def count(self): return len(self.states) - def dump(self, prefix=""): + def dump(self, prefix=None, sort_fn=None): """ - Returns all states sorted alphabetically, optionally - from a prefix onwards. + Returns all states sorted, optionally beginning from a prefix only. """ - for s in self.states: - if not prefix or s.startswith(prefix): - yield self.lookup(s) + prefix = prefix or () + 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 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 + parent = self.lookup(state_id[:-1], tree=True) + if len(parent) == 3 and "init" in parent and "clean" in parent: + continue + yield self.states[state_id] class Renderer: @@ -170,16 +283,26 @@ class Renderer: Base class for Renderer objects. """ - opts = {} + _default_opts = { + "default_description": """\ +The following states are found in {where}: - def __init__(self, target="docs", opts=None): - if opts is not None: - self.opts = self.opts | opts - - if isinstance(target, str): - target = Path(target) - self.target = base_dir / target +.. contents:: + :local: +""", + "always_include_default_description": False, + "default_header": "Available States", + "main_heading_char": "=", + "sub_heading_char": "-", + } + def __init__(self, target="docs", prefix=None, basedir=base_dir, opts=None): + self.opts = self._default_opts | (opts or {}) + self.target = basedir / target + if isinstance(prefix, str): + prefix = tuple(prefix.split(".")) + self.prefix = prefix or () + self.basedir = basedir self._ensurepath(self.target) def render(self, states): @@ -197,25 +320,25 @@ class Renderer: ) self.f.write(text + "\n" * ncount) - def _write_heading(self, text, uline="-"): + def _write_heading(self, text, uline=None): """ Convenience method to write a subheading """ self._write(text) - self._write(uline * len(text)) + self._write((uline or self.opts["sub_heading_char"]) * len(text)) - def _write_main_heading(self, text, uline="="): + def _write_main_heading(self, text, uline=None): """ Convenience method to write the main heading """ self.f.write(text + "\n") - self.f.write(uline * len(text) + "\n\n") + self.f.write((uline or self.opts["main_heading_char"]) * len(text) + "\n\n") def _write_main_description(self, text): """ Convenience method to write the main description """ - self.f.write(text + "\n\n") + self.f.write(text + "\n") def _get_main_heading(self, states): """ @@ -227,17 +350,19 @@ class Renderer: capitalized last part of it. 4. "Available States" """ - if main := states.lookup(self.prefix + ".init"): + if header := self.opts.get("header"): + return header + if (main := states.lookup(self.prefix + ("init",))) and main.comment: lines = main.comment.splitlines() header = lines.pop(0) # make sure the header does not get printed twice main.comment = "\n".join(lines).strip("\n") return header - if main := self.opts.get("header"): - return main if self.prefix: - return self.prefix.split(".")[-1].title() - return "Available States" + return self.prefix[-1].title() + if header := self.opts.get("default_header"): + return header + return self.opts["default_header"] def _get_main_description(self, states): """ @@ -248,16 +373,19 @@ class Renderer: 2. If a description was specified in opts, return that. 3. general description """ - if main := states.lookup(self.prefix + ".init"): - comment = main.comment - # make sure the comment does not get printed twice - states.unregister(main) - return comment - if main := self.opts.get("description"): - return main - return "The following states are found in {}:".format( - self.prefix if self.prefix else "this formula" - ) + def get_default_desc(): + return self.opts["default_description"].format( + where=".".join(self.prefix) if self.prefix else "this formula" + ) + + if desc := self.opts.get("description"): + return desc + if main := states.lookup(self.prefix + ("init",)): + desc = main.comment + if self.opts.get("always_include_default_description"): + desc += "\n" + get_default_desc() + return desc + return get_default_desc() def _write_header(self, states): """ @@ -282,32 +410,33 @@ class SingleRenderer(Renderer): If there is a documented top-layer init.sls, the first line of its comment will become the main heading of the file, the stripped - rest will be rendered directly below before any nested states. + rest will be rendered directly below before any nested states as + the main description. + + Should have been a Jinja template @TODO """ - opts = { + default_opts = { # include init.sls files "init": True, # include .init suffix "init_suffix": False, # include clean.sls files - "clean": False, + "clean": True, # when rendering with prefix `settings.something`, # write `else` instead of `settings.something.else` "cut_prefix": False, + "include_formula_root": True, } - def __init__(self, target="docs/states.rst", prefix="", opts=None): - self.prefix = prefix - + 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, self.opts | opts or {}) + super().__init__(target=target, prefix=prefix, basedir=basedir, opts=self.default_opts | kwargs) def render(self, states): - relative_to = self.prefix if self.opts["cut_prefix"] else "" + relative_to = "/".join(self.prefix) if self.opts["cut_prefix"] else "" with open(self.target, "w") as f: self.f = f @@ -315,12 +444,15 @@ class SingleRenderer(Renderer): self._write_header(states) for state in states.dump(self.prefix): - if not self.opts["clean"] and state.isclean(): + if not self.opts["init"] and state.is_init(): continue - if not self.opts["init"] and state.isinit(): + 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"]) + if state_id == ".": continue self._write_heading( - state.tostateid(self.opts["init_suffix"], relative_to) + state.to_state_id(self.opts["init_suffix"], relative_to, formula_root=self.opts["include_formula_root"]) ) self._write(state.comment, 3) @@ -354,36 +486,39 @@ class DepthRenderer(Renderer): - read_receipts doc """ - opts = { + default_opts = { # maxdepth for generated index.rst files "index_maxdepth": 4, - # also any options are passed through to the - # delegate renderer, by default SingleRenderer + "single_opts": { + "init": True, + "init_suffix": False, + "clean": False, + "cut_prefix": True, + "include_formula_root": False, + } } - def __init__(self, max_depth=1, target="docs/states", delegate_cls=None, opts=None): - if delegate_cls is None: - delegate_cls = SingleRenderer - + 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 - - super().__init__(target, self.opts | opts or {}) + self.delegate = delegate_cls or SingleRenderer + super().__init__(target=target, basedir=basedir, opts=self.default_opts | (kwargs or {})) def render(self, states): found = [] indices = {} - cur_top = "" + cur_top = () - # find at which prefix length the maxdepth is fulfilled + # Find at which prefix length the maxdepth is fulfilled for prefix in states.prefixes: - # filtering out more specific = shallower dicts - # this requires the list to be sorted! + # Filtering out more specific = shallower dicts + # This requires the list to be sorted! + # This also goes not too well with rendering clean states + # by default since they will be separate. if cur_top: - if prefix.startswith(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 @@ -398,7 +533,7 @@ class DepthRenderer(Renderer): for prefix in found: ptr = indices - prefix = prefix.split(".") + prefix = list(prefix) while prefix: cur = prefix.pop(0) @@ -421,38 +556,34 @@ class DepthRenderer(Renderer): def _render_single(self, states, prefix): target = self._get_target(prefix) - renderer = self.delegate(target=target, prefix=prefix, opts=self.opts) + renderer = self.delegate(target=target, prefix=prefix, **self.opts["single_opts"]) renderer.render(states) - def _render_index(self, states, indices, prefix=""): + def _render_index(self, states, indices, prefix=None): + prefix = prefix or () target = self._get_target(prefix) / Path("index.rst") - self._ensurepath(target) with open(target, "w") as f: self.f = f self.prefix = prefix self._write_header(states) - self.prefix = "" - f.write( - """ + self.prefix = () + f.write(f""" .. toctree:: - :maxdepth: {} + :maxdepth: {self.opts['index_maxdepth']} :caption: Contents: -""".format( - self.opts.get("index_maxdepth", 4) - ) - ) - for s in indices["_index"]: +""") + for s in sorted(indices["_index"]): f.write(" " + s + "\n") - for sub in indices: - if "_index" == sub: + for sub in sorted(indices): + if sub == "_index": continue if "_index" in indices[sub]: - new_prefix = prefix + "." + sub if prefix else sub + new_prefix = prefix + (sub,) self._render_index(states, indices[sub], new_prefix) def _get_target(self, prefix): - target_prefix = Path(prefix.replace(".", "/")) + target_prefix = Path("/".join(prefix)) target = self.target / target_prefix self._ensurepath(target) return target @@ -470,23 +601,19 @@ class SaltAutodoc: SKIP_FILE = "@internal" - def __init__(self, base=None, renderer=None, registry=None, env=None): + def __init__(self, base=None, renderer=None, registry=None, env=None, include_empty=False, ignore=None): """ base: base path containing Salt states to autodocument renderer: renderer to use for rendering """ if base is None: - base = list(base_dir.glob("tool_*"))[0] + base = list(base_dir.glob("*/init.sls"))[0].parent self.base = base - if renderer is None: - renderer = SingleRenderer() - self.renderer = renderer - if env is None: - env = Environment() - self.env = env - if registry is None: - registry = StateRegistry() - self.registry = registry + self.renderer = renderer or SingleRenderer() + self.env = env or Environment() + self.registry = registry or StateRegistry() + self.include_empty = include_empty + self.ignore = ignore or [] def run(self, src=""): """ @@ -495,32 +622,24 @@ class SaltAutodoc: 3. in that case, save it to the registry 4. pass the registry to the renderer """ - states = {} - for file in self.glob(src): + if str(file.relative_to(self.base)).startswith(tuple(self.ignore)): + continue with open(file, "r") as f: text = "".join(f.readlines()) try: comment = self.find_comment(text) except TemplateSyntaxError as e: raise RuntimeError( - "There was an error parsing the Jinja syntax in file '{}':\n\n{}".format( - file, str(e) - ) + f"There was an error parsing the Jinja syntax in file '{file}':\n\n{e}" ) - if comment and not comment.startswith(self.SKIP_FILE): - path = self.path2saltpath(file) - self.registry.register(State(path, comment)) + 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)) self.renderer.render(self.registry) - def path2saltpath(self, path): - """ - Returns a Path object relative to the base directory. - """ - return path.relative_to(self.base) - def glob(self, src): """ Returns Path objects pointing to Salt states provided by this formula. @@ -534,11 +653,15 @@ class SaltAutodoc: """ lexed = list(self.env.lex(text)) try: - i, t, content = lexed[1] + i = 0 + t = "" + while i < 5 and t != "comment": + _, t, content = lexed[i] + i += 1 except IndexError: - i = t = content = "" + t = content = "" - if "comment" == t: + if t == "comment": return self.parse(content) return "" @@ -554,18 +677,16 @@ class SaltAutodoc: if __name__ == "__main__": - options = { - "init": True, - "init_suffix": False, - "clean": False, - "cut_prefix": False, - "index_maxdepth": 4, - } + options = toml.loads((base_dir / "pyproject.toml").read_text()).get("tool", {}).get("slsdoc", {}) + renderer = options.get("renderer", "single") - # by default, - # - render all documented states to a single file - # - skip clean.sls descriptions - # - do not include .init suffix on state ID - r = SingleRenderer(target="docs/states.rst", opts=options) - a = SaltAutodoc(base=base_dir / "gitea", renderer=r) - a.run() + if renderer == "single": + rend = SingleRenderer(**options.get("single_renderer", {})) + elif renderer == "depth": + rend = DepthRenderer(**options.get("depth_renderer", {})) + 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"])) + doc.run() diff --git a/docs/README.rst b/docs/README.rst index 1b83f4c..2c7b6d2 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -73,64 +73,92 @@ Configuration ------------- An example pillar is provided, please see `pillar.example`. Note that you do not need to specify everything by pillar. Often, it's much easier and less resource-heavy to use the ``parameters//.yaml`` files for non-sensitive settings. The underlying logic is explained in `map.jinja`. + Available states ---------------- +The following states are found in this formula: + .. contents:: :local: -``gitea`` -^^^^^^^^^ -*Meta-state (This is a state that includes other states)*. +gitea +^^^^^ +*Meta-state*. This installs the gitea package, -manages the gitea configuration file and then -starts the associated gitea service. +manages the gitea configuration file +and then starts the associated gitea service. -``gitea.package`` -^^^^^^^^^^^^^^^^^ +gitea.package +^^^^^^^^^^^^^ This state will install the gitea package only. -``gitea.config`` -^^^^^^^^^^^^^^^^ -This state will configure the gitea service and has a dependency on ``gitea.install`` -via include list. +gitea.config +^^^^^^^^^^^^ +This state will configure the gitea service +and has a dependency on ``gitea.install`` via include list. -``gitea.service`` -^^^^^^^^^^^^^^^^^ -This state will start the gitea service and has a dependency on ``gitea.config`` -via include list. +gitea.service +^^^^^^^^^^^^^ +This state will start the gitea service +and has a dependency on ``gitea.config`` via include list. -``gitea.clean`` -^^^^^^^^^^^^^^^ -*Meta-state (This is a state that includes other states)*. +gitea.go +^^^^^^^^ -This state will undo everything performed in the ``gitea`` meta-state in reverse order, i.e. + + +gitea.mods.rst +^^^^^^^^^^^^^^ + + + +gitea.clean +^^^^^^^^^^^ +*Meta-state*. + +This state will undo everything performed in the ``gitea`` meta-state +in reverse order, i.e. stops the service, -removes the configuration file and -then uninstalls the package. Some paths are left to avoid accidental data loss (namely ``GITEA_WORKDIR``, ``APP_DATA_PATH`` and the gitea user home). +removes the configuration file and then +uninstalls the package. +Some paths are left to avoid accidental data loss +(namely ``GITEA_WORKDIR``, ``APP_DATA_PATH`` and the gitea user home). -``gitea.service.clean`` -^^^^^^^^^^^^^^^^^^^^^^^ -This state will stop the gitea service and disable it at boot time. +gitea.package.clean +^^^^^^^^^^^^^^^^^^^ +This state will remove the gitea package and has a depency on +``gitea.config.clean`` via include list. -``gitea.config.clean`` -^^^^^^^^^^^^^^^^^^^^^^ +gitea.config.clean +^^^^^^^^^^^^^^^^^^ This state will remove the configuration of the gitea service and has a dependency on ``gitea.service.clean`` via include list. -``gitea.package.clean`` -^^^^^^^^^^^^^^^^^^^^^^^ -This state will remove the gitea package and has a depency on -``gitea.config.clean`` via include list. +gitea.service.clean +^^^^^^^^^^^^^^^^^^^ +This state will stop the gitea service and disable it at boot time. + + +gitea.go.clean +^^^^^^^^^^^^^^ + + + +gitea.mods.rst.clean +^^^^^^^^^^^^^^^^^^^^ + + + Contributing to this repo ------------------------- diff --git a/docs/README.rst.tpl b/docs/README.rst.tpl new file mode 100644 index 0000000..93f691f --- /dev/null +++ b/docs/README.rst.tpl @@ -0,0 +1,150 @@ +.. _readme: + +Gitea Formula +============= + +|img_sr| |img_pc| + +.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg + :alt: Semantic Release + :scale: 100% + :target: https://github.com/semantic-release/semantic-release +.. |img_pc| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white + :alt: pre-commit + :scale: 100% + :target: https://github.com/pre-commit/pre-commit + +Manage Gitea with Salt. + +.. contents:: **Table of Contents** + :depth: 1 + +General notes +------------- + +See the full `SaltStack Formulas installation and usage instructions +`_. + +If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section +`_. + +If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``, +which contains the currently released version. This formula is versioned according to `Semantic Versioning `_. + +See `Formula Versioning Section `_ for more details. + +If you need (non-default) configuration, please refer to: + +- `how to configure the formula with map.jinja `_ +- the ``pillar.example`` file +- the `Special notes`_ section + +Special notes +------------- +* This installs from the `official binary source `_. +* The formula is currently Linux/systemd-centric. It should be relatively easy to provide the correct parameters and service file for other platforms though. +* Since the formula skips the web installer, you will need to provide at least the database configuration. +* You can optionally specify the secrets, but they can be autogenerated by Salt as well. In that case, they will be saved in a separate file inside your config dir. +* All the paths are modifiable, find them in ``lookup:paths``. You should not need to set the corresponding values in your config, they are added automatically. +* If Gitea requires mounts for some of the paths, you can specify them in ``service:requires_mount`` as a list. +* If Gitea requires a local service unit (e.g. Redis server), specify it/them in ``service:wants`` as a list. This formula will do its best to automatically add a locally running database service to this list. + +RST mod +^^^^^^^ +This formula provides basic support for installing an external ``rst`` renderer. This especially makes Gitea display ``README.rst`` files similar to as it does for ``README.md``. + +The installation is not included by default, you will have to specifically target ``gitea.mods.rst`` to the minion. Furthermore, you will have to setup the external renderer in your ``app.ini`` similar to: + +.. code-block:: yaml + + markup.restructuredtext: + enabled: true + file_extensions: '.rst' + render_command: timeout 30s /usr/local/bin/grst + is_input_file: true + markup.sanitizer.restructuredtext: + element: pre + allow_attr: class + regexp: '' + +The mod compiles ``chroma`` (the syntax highlighting library that is used by Gitea) from source and installs a Python script that renders RST files, which currently relies on ``chroma`` and the ``docutils`` python package. The parameters can be modified in ``gitea:lookup:mod_rst``. I currently use this to patch ``*.sls``, ``*.jinja`` and ``*.j2`` highlighting into ``chroma``. + +Configuration +------------- +An example pillar is provided, please see `pillar.example`. Note that you do not need to specify everything by pillar. Often, it's much easier and less resource-heavy to use the ``parameters//.yaml`` files for non-sensitive settings. The underlying logic is explained in `map.jinja`. + + + +Contributing to this repo +------------------------- + +Commit messages +^^^^^^^^^^^^^^^ + +**Commit message formatting is significant!** + +Please see `How to contribute `_ for more details. + +pre-commit +^^^^^^^^^^ + +`pre-commit `_ is configured for this formula, which you may optionally use to ease the steps involved in submitting your changes. +First install the ``pre-commit`` package manager using the appropriate `method `_, then run ``bin/install-hooks`` and +now ``pre-commit`` will run automatically on each ``git commit``. :: + + $ bin/install-hooks + pre-commit installed at .git/hooks/pre-commit + pre-commit installed at .git/hooks/commit-msg + +State documentation +~~~~~~~~~~~~~~~~~~~ +There is a script that semi-autodocuments available states: ``bin/slsdoc``. + +If a ``.sls`` file begins with a Jinja comment, it will dump that into the docs. It can be configured differently depending on the formula. See the script source code for details currently. + +This means if you feel a state should be documented, make sure to write a comment explaining it. + +Testing +------- + +Linux testing is done with ``kitchen-salt``. + +Requirements +^^^^^^^^^^^^ + +* Ruby +* Docker + +.. code-block:: bash + + $ gem install bundler + $ bundle install + $ bin/kitchen test [platform] + +Where ``[platform]`` is the platform name defined in ``kitchen.yml``, +e.g. ``debian-9-2019-2-py3``. + +``bin/kitchen converge`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Creates the docker instance and runs the ``gitea`` main state, ready for testing. + +``bin/kitchen verify`` +^^^^^^^^^^^^^^^^^^^^^^ + +Runs the ``inspec`` tests on the actual instance. + +``bin/kitchen destroy`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Removes the docker instance. + +``bin/kitchen test`` +^^^^^^^^^^^^^^^^^^^^ + +Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``. + +``bin/kitchen login`` +^^^^^^^^^^^^^^^^^^^^^ + +Gives you SSH access to the instance for manual testing. diff --git a/docs/states.rst b/docs/states.rst index 33750de..6686f34 100644 --- a/docs/states.rst +++ b/docs/states.rst @@ -1,6 +1,85 @@ -Available States -================ +Available states +---------------- The following states are found in this formula: +.. contents:: + :local: + + +gitea +^^^^^ +*Meta-state*. + +This installs the gitea package, +manages the gitea configuration file +and then starts the associated gitea service. + + +gitea.package +^^^^^^^^^^^^^ +This state will install the gitea package only. + + +gitea.config +^^^^^^^^^^^^ +This state will configure the gitea service +and has a dependency on ``gitea.install`` via include list. + + +gitea.service +^^^^^^^^^^^^^ +This state will start the gitea service +and has a dependency on ``gitea.config`` via include list. + + +gitea.go +^^^^^^^^ + + + +gitea.mods.rst +^^^^^^^^^^^^^^ + + + +gitea.clean +^^^^^^^^^^^ +*Meta-state*. + +This state will undo everything performed in the ``gitea`` meta-state +in reverse order, i.e. +stops the service, +removes the configuration file and then +uninstalls the package. +Some paths are left to avoid accidental data loss +(namely ``GITEA_WORKDIR``, ``APP_DATA_PATH`` and the gitea user home). + + +gitea.package.clean +^^^^^^^^^^^^^^^^^^^ +This state will remove the gitea package and has a depency on +``gitea.config.clean`` via include list. + + +gitea.config.clean +^^^^^^^^^^^^^^^^^^ +This state will remove the configuration of the gitea service and has a +dependency on ``gitea.service.clean`` via include list. + + +gitea.service.clean +^^^^^^^^^^^^^^^^^^^ +This state will stop the gitea service and disable it at boot time. + + +gitea.go.clean +^^^^^^^^^^^^^^ + + + +gitea.mods.rst.clean +^^^^^^^^^^^^^^^^^^^^ + + diff --git a/gitea/_mapdata/init.sls b/gitea/_mapdata/init.sls index 6529e39..6efd5a0 100644 --- a/gitea/_mapdata/init.sls +++ b/gitea/_mapdata/init.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=sls --- {%- set tplroot = tpldir.split("/")[0] %} diff --git a/gitea/clean.sls b/gitea/clean.sls index 2cefe7d..3ef2cde 100644 --- a/gitea/clean.sls +++ b/gitea/clean.sls @@ -1,6 +1,17 @@ -# -*- coding: utf-8 -*- # vim: ft=sls +{#- + *Meta-state*. + + This state will undo everything performed in the ``gitea`` meta-state + in reverse order, i.e. + stops the service, + removes the configuration file and then + uninstalls the package. + Some paths are left to avoid accidental data loss + (namely ``GITEA_WORKDIR``, ``APP_DATA_PATH`` and the gitea user home). +#} + include: - .service.clean - .config.clean diff --git a/gitea/config/clean.sls b/gitea/config/clean.sls index 608c8bf..318eac6 100644 --- a/gitea/config/clean.sls +++ b/gitea/config/clean.sls @@ -1,6 +1,10 @@ -# -*- coding: utf-8 -*- # vim: ft=sls +{#- + This state will remove the configuration of the gitea service and has a + dependency on ``gitea.service.clean`` via include list. +#} + {%- set tplroot = tpldir.split('/')[0] %} {%- set sls_service_clean = tplroot ~ '.service.clean' %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} @@ -8,7 +12,7 @@ include: - {{ sls_service_clean }} -gitea-config-clean-file-absent: +Gitea configuration is absent: file.absent: - names: - {{ gitea.lookup.paths.conf | path_join("app.ini") }} diff --git a/gitea/config/file.sls b/gitea/config/file.sls index 852367c..3972f64 100644 --- a/gitea/config/file.sls +++ b/gitea/config/file.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=sls {%- set tplroot = tpldir.split('/')[0] %} @@ -23,11 +22,11 @@ Gitea internal token file is generated: - sls: {{ sls_package_install }} {%- endif %} -Gitea config is setup: +Gitea configuration is managed: file.managed: - - name: {{ gitea.lookup.paths.conf | path_join('app.ini') }} - - source: {{ files_switch(['app.ini.j2'], - lookup='Gitea config is setup' + - name: {{ gitea.lookup.paths.conf | path_join("app.ini") }} + - source: {{ files_switch(["app.ini", "app.ini.j2"], + lookup="Gitea configuration is managed" ) }} - template: jinja diff --git a/gitea/config/init.sls b/gitea/config/init.sls index 465ddfe..733d6ff 100644 --- a/gitea/config/init.sls +++ b/gitea/config/init.sls @@ -1,5 +1,9 @@ -# -*- coding: utf-8 -*- # vim: ft=sls +{#- + This state will configure the gitea service + and has a dependency on ``gitea.install`` via include list. +#} + include: - .file diff --git a/gitea/init.sls b/gitea/init.sls index 858a8e6..db69d03 100644 --- a/gitea/init.sls +++ b/gitea/init.sls @@ -1,6 +1,13 @@ -# -*- coding: utf-8 -*- # vim: ft=sls +{#- + *Meta-state*. + + This installs the gitea package, + manages the gitea configuration file + and then starts the associated gitea service. +#} + include: - .package - .config diff --git a/gitea/libmapstack.jinja b/gitea/libmapstack.jinja index 8f54ef3..4f1b41e 100644 --- a/gitea/libmapstack.jinja +++ b/gitea/libmapstack.jinja @@ -1,4 +1,3 @@ -{#- -*- coding: utf-8 -*- #} {#- vim: ft=jinja #} {#- Get the `tplroot` from `tpldir` #} diff --git a/gitea/libmatchers.jinja b/gitea/libmatchers.jinja index 10ff8bd..35602a3 100644 --- a/gitea/libmatchers.jinja +++ b/gitea/libmatchers.jinja @@ -1,4 +1,3 @@ -{#- -*- coding: utf-8 -*- #} {#- vim: ft=jinja #} {#- Get the `tplroot` from `tpldir` #} diff --git a/gitea/libsaltcli.jinja b/gitea/libsaltcli.jinja index c473723..901a56f 100644 --- a/gitea/libsaltcli.jinja +++ b/gitea/libsaltcli.jinja @@ -1,4 +1,3 @@ -{#- -*- coding: utf-8 -*- #} {#- vim: ft=jinja #} {#- Get the relevant values from the `opts` dict #} diff --git a/gitea/map.jinja b/gitea/map.jinja index 4a5f925..c3d8b2c 100644 --- a/gitea/map.jinja +++ b/gitea/map.jinja @@ -1,4 +1,3 @@ -{#- -*- coding: utf-8 -*- #} {#- vim: ft=jinja #} {#- Get the `tplroot` from `tpldir` #} diff --git a/gitea/package/clean.sls b/gitea/package/clean.sls index d79007d..84b18c7 100644 --- a/gitea/package/clean.sls +++ b/gitea/package/clean.sls @@ -1,6 +1,10 @@ -# -*- coding: utf-8 -*- # vim: ft=sls +{#- + This state will remove the gitea package and has a depency on + ``gitea.config.clean`` via include list. +#} + {%- set tplroot = tpldir.split('/')[0] %} {%- set sls_config_clean = tplroot ~ '.config.clean' %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} diff --git a/gitea/package/init.sls b/gitea/package/init.sls index d3e5518..0210bb8 100644 --- a/gitea/package/init.sls +++ b/gitea/package/init.sls @@ -1,5 +1,8 @@ -# -*- coding: utf-8 -*- # vim: ft=sls +{#- + This state will install the gitea package only. +#} + include: - .install diff --git a/gitea/parameters/defaults.yaml b/gitea/parameters/defaults.yaml index ce2a3bb..d2c5dd3 100644 --- a/gitea/parameters/defaults.yaml +++ b/gitea/parameters/defaults.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set default values. diff --git a/gitea/parameters/os_family/Arch.yaml b/gitea/parameters/os_family/Arch.yaml index a8d4fc8..fab6d2d 100644 --- a/gitea/parameters/os_family/Arch.yaml +++ b/gitea/parameters/os_family/Arch.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/os_family/Debian.yaml b/gitea/parameters/os_family/Debian.yaml index 874a8a2..38a9b93 100644 --- a/gitea/parameters/os_family/Debian.yaml +++ b/gitea/parameters/os_family/Debian.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/os_family/FreeBSD.yaml b/gitea/parameters/os_family/FreeBSD.yaml index 24f0afd..544d76d 100644 --- a/gitea/parameters/os_family/FreeBSD.yaml +++ b/gitea/parameters/os_family/FreeBSD.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/os_family/Gentoo.yaml b/gitea/parameters/os_family/Gentoo.yaml index cf5a88a..33bca8e 100644 --- a/gitea/parameters/os_family/Gentoo.yaml +++ b/gitea/parameters/os_family/Gentoo.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/os_family/MacOS.yaml b/gitea/parameters/os_family/MacOS.yaml index 694ce8d..ce807cd 100644 --- a/gitea/parameters/os_family/MacOS.yaml +++ b/gitea/parameters/os_family/MacOS.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/os_family/OpenBSD.yaml b/gitea/parameters/os_family/OpenBSD.yaml index de373a8..12378b3 100644 --- a/gitea/parameters/os_family/OpenBSD.yaml +++ b/gitea/parameters/os_family/OpenBSD.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/os_family/RedHat.yaml b/gitea/parameters/os_family/RedHat.yaml index 48c4619..e1c1e55 100644 --- a/gitea/parameters/os_family/RedHat.yaml +++ b/gitea/parameters/os_family/RedHat.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/os_family/Suse.yaml b/gitea/parameters/os_family/Suse.yaml index e60f082..c05e4bb 100644 --- a/gitea/parameters/os_family/Suse.yaml +++ b/gitea/parameters/os_family/Suse.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/osarch/386.yaml b/gitea/parameters/osarch/386.yaml index 14baad3..0cf55ab 100644 --- a/gitea/parameters/osarch/386.yaml +++ b/gitea/parameters/osarch/386.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/osarch/amd64.yaml b/gitea/parameters/osarch/amd64.yaml index f404461..93379e1 100644 --- a/gitea/parameters/osarch/amd64.yaml +++ b/gitea/parameters/osarch/amd64.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/osarch/arm64.yaml b/gitea/parameters/osarch/arm64.yaml index 9779ce0..e040a9d 100644 --- a/gitea/parameters/osarch/arm64.yaml +++ b/gitea/parameters/osarch/arm64.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/osarch/armv6l.yaml b/gitea/parameters/osarch/armv6l.yaml index 6243f4f..7bff705 100644 --- a/gitea/parameters/osarch/armv6l.yaml +++ b/gitea/parameters/osarch/armv6l.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/osarch/armv7l.yaml b/gitea/parameters/osarch/armv7l.yaml index 5cf5529..1baaed9 100644 --- a/gitea/parameters/osarch/armv7l.yaml +++ b/gitea/parameters/osarch/armv7l.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/osarch/ppc64le.yaml b/gitea/parameters/osarch/ppc64le.yaml index c95f819..f07951d 100644 --- a/gitea/parameters/osarch/ppc64le.yaml +++ b/gitea/parameters/osarch/ppc64le.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/osarch/s390x.yaml b/gitea/parameters/osarch/s390x.yaml index 450a5c0..13cc6e3 100644 --- a/gitea/parameters/osarch/s390x.yaml +++ b/gitea/parameters/osarch/s390x.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/parameters/osarch/x86_64.yaml b/gitea/parameters/osarch/x86_64.yaml index 1a9411d..3d880ae 100644 --- a/gitea/parameters/osarch/x86_64.yaml +++ b/gitea/parameters/osarch/x86_64.yaml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # # Set values specific to: diff --git a/gitea/service/clean.sls b/gitea/service/clean.sls index 7fc0476..3904674 100644 --- a/gitea/service/clean.sls +++ b/gitea/service/clean.sls @@ -1,10 +1,13 @@ -# -*- coding: utf-8 -*- # vim: ft=sls +{#- + This state will stop the gitea service and disable it at boot time. +#} + {%- set tplroot = tpldir.split('/')[0] %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} -gitea-service-clean-service-dead: +Gitea is dead: service.dead: - name: {{ gitea.lookup.service.name }} - enable: False diff --git a/gitea/service/init.sls b/gitea/service/init.sls index 6fe4d1a..7147072 100644 --- a/gitea/service/init.sls +++ b/gitea/service/init.sls @@ -1,5 +1,9 @@ -# -*- coding: utf-8 -*- # vim: ft=sls +{#- + This state will start the gitea service + and has a dependency on ``gitea.config`` via include list. +#} + include: - .running diff --git a/gitea/service/running.sls b/gitea/service/running.sls index 12426f6..43e0123 100644 --- a/gitea/service/running.sls +++ b/gitea/service/running.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=sls {%- set tplroot = tpldir.split('/')[0] %} @@ -8,7 +7,7 @@ include: - {{ sls_config_file }} -gitea-service-running-service-running: +Gitea is running: service.running: - name: {{ gitea.lookup.service.name }} - enable: True diff --git a/kitchen.yml b/kitchen.yml index 23f89d6..3c6ee4b 100644 --- a/kitchen.yml +++ b/kitchen.yml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- # For help on this file's format, see https://kitchen.ci/ diff --git a/pillar.example b/pillar.example index 90731bd..6886117 100644 --- a/pillar.example +++ b/pillar.example @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml # yamllint disable rule:comments-indentation --- diff --git a/pyproject.toml b/pyproject.toml index 76f2017..bafc516 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,6 +15,20 @@ sphinx-rtd-theme = "^1.0.0" # fulltoc has an issue with recent Sphinx versions ('easily' fixable in the source code though) # sphinxcontrib-fulltoc = "^1.2.0" +[tool.slsdoc] +include_empty = true + +[tool.slsdoc.single_renderer] +header = "Available states" +description = """\ +The following states are found in this formula: + +.. contents:: + :local: +""" +main_heading_char = "-" +sub_heading_char = "^" + [build-system] requires = ["poetry-core>=1.0.0"] build-backend = "poetry.core.masonry.api" diff --git a/test/integration/share/inspec.yml b/test/integration/share/inspec.yml index 28a97b9..7ef7a6f 100644 --- a/test/integration/share/inspec.yml +++ b/test/integration/share/inspec.yml @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- name: share diff --git a/test/salt/pillar/default.sls b/test/salt/pillar/default.sls index d18e531..9f32446 100644 --- a/test/salt/pillar/default.sls +++ b/test/salt/pillar/default.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- gitea: diff --git a/test/salt/pillar/define_roles.sls b/test/salt/pillar/define_roles.sls index bfd8b69..72d632f 100644 --- a/test/salt/pillar/define_roles.sls +++ b/test/salt/pillar/define_roles.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- # libtofs.jinja must work with tofs.files_switch looked up list diff --git a/test/salt/pillar/gentoo.sls b/test/salt/pillar/gentoo.sls index 066506e..676241b 100644 --- a/test/salt/pillar/gentoo.sls +++ b/test/salt/pillar/gentoo.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- portage: diff --git a/test/salt/pillar/top.sls b/test/salt/pillar/top.sls index 62d6c62..b40f260 100644 --- a/test/salt/pillar/top.sls +++ b/test/salt/pillar/top.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- base: diff --git a/test/salt/pillar/upstart.sls b/test/salt/pillar/upstart.sls index d18e531..9f32446 100644 --- a/test/salt/pillar/upstart.sls +++ b/test/salt/pillar/upstart.sls @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # vim: ft=yaml --- gitea: