From 4a83af2a3044bca99aa76f750397f2d38c22d330 Mon Sep 17 00:00:00 2001 From: jeanluc Date: Sun, 5 Feb 2023 20:00:22 +0100 Subject: [PATCH] docs: improve state docs --- docs/README.rst | 41 ++++++++++++++++++++++++---------------- docs/README.rst.tpl | 1 + docs/states.rst | 40 +++++++++++++++++++++++---------------- gitea/config/clean.sls | 3 +-- gitea/config/init.sls | 4 ++-- gitea/go/clean.sls | 5 ++++- gitea/go/init.sls | 5 +++++ gitea/init.sls | 6 +++--- gitea/mods/rst/clean.sls | 5 +++++ gitea/mods/rst/init.sls | 8 ++++++++ gitea/package/clean.sls | 4 ++-- gitea/package/init.sls | 5 ++++- gitea/service/clean.sls | 2 +- gitea/service/init.sls | 4 ++-- 14 files changed, 87 insertions(+), 46 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index 2c7b6d2..f177137 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -69,6 +69,7 @@ The installation is not included by default, you will have to specifically targe 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`. @@ -87,36 +88,44 @@ gitea ^^^^^ *Meta-state*. -This installs the gitea package, -manages the gitea configuration file -and then starts the associated gitea service. +This installs Gitea, +manages its configuration +and then starts the ``gitea`` service. gitea.package ^^^^^^^^^^^^^ -This state will install the gitea package only. +Installs Gitea only. + +Releases are downloaded from the official server by default +and their signatures verified. gitea.config ^^^^^^^^^^^^ -This state will configure the gitea service -and has a dependency on ``gitea.install`` via include list. +Manages Gitea configuration. +Has a dependency on `gitea.package`_. gitea.service ^^^^^^^^^^^^^ -This state will start the gitea service -and has a dependency on ``gitea.config`` via include list. +Starts the Gitea service and enables it at boot time. +Has a dependency on `gitea.config`_. gitea.go ^^^^^^^^ - +Creates a build user and downloads Go. +Required for building Chroma. gitea.mods.rst ^^^^^^^^^^^^^^ +Compiles `Chroma `_ from source +and installs a Python script that can be setup as an external renderer +for ``*.rst`` files. +Has a dependency on `gitea.go`_. gitea.clean @@ -134,29 +143,29 @@ Some paths are left to avoid accidental data loss gitea.package.clean ^^^^^^^^^^^^^^^^^^^ -This state will remove the gitea package and has a depency on -``gitea.config.clean`` via include list. +Removes Gitea. +Has a dependency on `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. +Removes Gitea configuration. Has a dependency on `gitea.service.clean`_. gitea.service.clean ^^^^^^^^^^^^^^^^^^^ -This state will stop the gitea service and disable it at boot time. +Stops the gitea service and disables it at boot time. gitea.go.clean ^^^^^^^^^^^^^^ - +Removes the build user and Go installation. gitea.mods.rst.clean ^^^^^^^^^^^^^^^^^^^^ - +Removes the built ``chroma`` binary, the build path and the +``grst`` script. diff --git a/docs/README.rst.tpl b/docs/README.rst.tpl index 93f691f..a183d53 100644 --- a/docs/README.rst.tpl +++ b/docs/README.rst.tpl @@ -69,6 +69,7 @@ The installation is not included by default, you will have to specifically targe 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`. diff --git a/docs/states.rst b/docs/states.rst index 6686f34..ba46f40 100644 --- a/docs/states.rst +++ b/docs/states.rst @@ -11,36 +11,44 @@ gitea ^^^^^ *Meta-state*. -This installs the gitea package, -manages the gitea configuration file -and then starts the associated gitea service. +This installs Gitea, +manages its configuration +and then starts the ``gitea`` service. gitea.package ^^^^^^^^^^^^^ -This state will install the gitea package only. +Installs Gitea only. + +Releases are downloaded from the official server by default +and their signatures verified. gitea.config ^^^^^^^^^^^^ -This state will configure the gitea service -and has a dependency on ``gitea.install`` via include list. +Manages Gitea configuration. +Has a dependency on `gitea.package`_. gitea.service ^^^^^^^^^^^^^ -This state will start the gitea service -and has a dependency on ``gitea.config`` via include list. +Starts the Gitea service and enables it at boot time. +Has a dependency on `gitea.config`_. gitea.go ^^^^^^^^ - +Creates a build user and downloads Go. +Required for building Chroma. gitea.mods.rst ^^^^^^^^^^^^^^ +Compiles `Chroma `_ from source +and installs a Python script that can be setup as an external renderer +for ``*.rst`` files. +Has a dependency on `gitea.go`_. gitea.clean @@ -58,28 +66,28 @@ Some paths are left to avoid accidental data loss gitea.package.clean ^^^^^^^^^^^^^^^^^^^ -This state will remove the gitea package and has a depency on -``gitea.config.clean`` via include list. +Removes Gitea. +Has a dependency on `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. +Removes Gitea configuration. Has a dependency on `gitea.service.clean`_. gitea.service.clean ^^^^^^^^^^^^^^^^^^^ -This state will stop the gitea service and disable it at boot time. +Stops the gitea service and disables it at boot time. gitea.go.clean ^^^^^^^^^^^^^^ - +Removes the build user and Go installation. gitea.mods.rst.clean ^^^^^^^^^^^^^^^^^^^^ - +Removes the built ``chroma`` binary, the build path and the +``grst`` script. diff --git a/gitea/config/clean.sls b/gitea/config/clean.sls index 318eac6..bf471f8 100644 --- a/gitea/config/clean.sls +++ b/gitea/config/clean.sls @@ -1,8 +1,7 @@ # vim: ft=sls {#- - This state will remove the configuration of the gitea service and has a - dependency on ``gitea.service.clean`` via include list. + Removes Gitea configuration. Has a dependency on `gitea.service.clean`_. #} {%- set tplroot = tpldir.split('/')[0] %} diff --git a/gitea/config/init.sls b/gitea/config/init.sls index 733d6ff..d238fea 100644 --- a/gitea/config/init.sls +++ b/gitea/config/init.sls @@ -1,8 +1,8 @@ # vim: ft=sls {#- - This state will configure the gitea service - and has a dependency on ``gitea.install`` via include list. + Manages Gitea configuration. + Has a dependency on `gitea.package`_. #} include: diff --git a/gitea/go/clean.sls b/gitea/go/clean.sls index 6c548b3..7718577 100644 --- a/gitea/go/clean.sls +++ b/gitea/go/clean.sls @@ -1,6 +1,9 @@ -# -*- coding: utf-8 -*- # vim: ft=sls +{#- + Removes the build user and Go installation. +#} + {%- set tplroot = tpldir.split('/')[0] %} {%- set sls_config_file = tplroot ~ '.config.file' %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} diff --git a/gitea/go/init.sls b/gitea/go/init.sls index 57abe4c..cfbca07 100644 --- a/gitea/go/init.sls +++ b/gitea/go/init.sls @@ -1,6 +1,11 @@ # -*- coding: utf-8 -*- # vim: ft=sls +{#- + Creates a build user and downloads Go. + Required for building Chroma. +#} + {%- set tplroot = tpldir.split('/')[0] %} {%- set sls_config_file = tplroot ~ '.config.file' %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} diff --git a/gitea/init.sls b/gitea/init.sls index db69d03..114eebe 100644 --- a/gitea/init.sls +++ b/gitea/init.sls @@ -3,9 +3,9 @@ {#- *Meta-state*. - This installs the gitea package, - manages the gitea configuration file - and then starts the associated gitea service. + This installs Gitea, + manages its configuration + and then starts the ``gitea`` service. #} include: diff --git a/gitea/mods/rst/clean.sls b/gitea/mods/rst/clean.sls index 9d38bbe..69728d9 100644 --- a/gitea/mods/rst/clean.sls +++ b/gitea/mods/rst/clean.sls @@ -1,6 +1,11 @@ # -*- coding: utf-8 -*- # vim: ft=sls +{#- + Removes the built ``chroma`` binary, the build path and the + ``grst`` script. +#} + {%- set tplroot = tpldir.split('/')[0] %} {%- set sls_config_file = tplroot ~ '.config.file' %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} diff --git a/gitea/mods/rst/init.sls b/gitea/mods/rst/init.sls index 1ba0ed9..21b1cac 100644 --- a/gitea/mods/rst/init.sls +++ b/gitea/mods/rst/init.sls @@ -1,6 +1,14 @@ # -*- coding: utf-8 -*- # vim: ft=sls +{#- + Compiles `Chroma `_ from source + and installs a Python script that can be setup as an external renderer + for ``*.rst`` files. + + Has a dependency on `gitea.go`_. +#} + {%- set tplroot = tpldir.split('/')[0] %} {%- set sls_config_file = tplroot ~ '.config.file' %} {%- set sls_go_install = tplroot ~ '.go' %} diff --git a/gitea/package/clean.sls b/gitea/package/clean.sls index 84b18c7..053a0bb 100644 --- a/gitea/package/clean.sls +++ b/gitea/package/clean.sls @@ -1,8 +1,8 @@ # vim: ft=sls {#- - This state will remove the gitea package and has a depency on - ``gitea.config.clean`` via include list. + Removes Gitea. + Has a dependency on `gitea.config.clean`_. #} {%- set tplroot = tpldir.split('/')[0] %} diff --git a/gitea/package/init.sls b/gitea/package/init.sls index 0210bb8..efe7b57 100644 --- a/gitea/package/init.sls +++ b/gitea/package/init.sls @@ -1,7 +1,10 @@ # vim: ft=sls {#- - This state will install the gitea package only. + Installs Gitea only. + + Releases are downloaded from the official server by default + and their signatures verified. #} include: diff --git a/gitea/service/clean.sls b/gitea/service/clean.sls index 3904674..3fc4421 100644 --- a/gitea/service/clean.sls +++ b/gitea/service/clean.sls @@ -1,7 +1,7 @@ # vim: ft=sls {#- - This state will stop the gitea service and disable it at boot time. + Stops the gitea service and disables it at boot time. #} {%- set tplroot = tpldir.split('/')[0] %} diff --git a/gitea/service/init.sls b/gitea/service/init.sls index 7147072..bba0bd0 100644 --- a/gitea/service/init.sls +++ b/gitea/service/init.sls @@ -1,8 +1,8 @@ # vim: ft=sls {#- - This state will start the gitea service - and has a dependency on ``gitea.config`` via include list. + Starts the Gitea service and enables it at boot time. + Has a dependency on `gitea.config`_. #} include: