karel/salt-gitea-formula
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: improve state docs

Browse Source
This commit is contained in:
jeanluc
2023-02-05 20:00:22 +01:00
parent c58b3ea081
commit 4a83af2a30
14 changed files with 87 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/README.rst
View File

@@ -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/<grain>/<value>.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 <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`_.
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.

1
docs/README.rst.tpl
View File

@@ -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/<grain>/<value>.yaml`` files for non-sensitive settings. The underlying logic is explained in `map.jinja`.

40
docs/states.rst
View File

@@ -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 <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`_.
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.

3
gitea/config/clean.sls
View File

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

4
gitea/config/init.sls
View File

@@ -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:

5
gitea/go/clean.sls
View File

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

5
gitea/go/init.sls
View File

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

6
gitea/init.sls
View File

@@ -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:

5
gitea/mods/rst/clean.sls
View File

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

8
gitea/mods/rst/init.sls
View File

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

4
gitea/package/clean.sls
View File

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

5
gitea/package/init.sls
View File

@@ -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:

2
gitea/service/clean.sls
View File

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

4
gitea/service/init.sls
View File

@@ -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: