docs: improve state docs

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] %}

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:

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 %}

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 %}

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:

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 %}

gitea/mods/rst/init.sls

@@ -1,6 +1,14 @@
 # -*- coding: utf-8 -*-
 # vim: ft=sls
 
+{#-
+    Compiles `Chroma <https://github.com/alecthomas/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' %}

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] %}

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:

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] %}

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: