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``. 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 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`. 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*. *Meta-state*.
This installs the gitea package, This installs Gitea,
manages the gitea configuration file manages its configuration
and then starts the associated gitea service. and then starts the ``gitea`` service.
gitea.package 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 gitea.config
^^^^^^^^^^^^ ^^^^^^^^^^^^
This state will configure the gitea service Manages Gitea configuration.
and has a dependency on ``gitea.install`` via include list. Has a dependency on `gitea.package`_.
gitea.service gitea.service
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
This state will start the gitea service Starts the Gitea service and enables it at boot time.
and has a dependency on ``gitea.config`` via include list. Has a dependency on `gitea.config`_.
gitea.go gitea.go
^^^^^^^^ ^^^^^^^^
Creates a build user and downloads Go.
Required for building Chroma.
gitea.mods.rst 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 gitea.clean
@@ -134,29 +143,29 @@ Some paths are left to avoid accidental data loss
gitea.package.clean gitea.package.clean
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
This state will remove the gitea package and has a depency on Removes Gitea.
``gitea.config.clean`` via include list. Has a dependency on `gitea.config.clean`_.
gitea.config.clean gitea.config.clean
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
This state will remove the configuration of the gitea service and has a Removes Gitea configuration. Has a dependency on `gitea.service.clean`_.
dependency on ``gitea.service.clean`` via include list.
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 gitea.go.clean
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Removes the build user and Go installation.
gitea.mods.rst.clean 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``. 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 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`. 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*. *Meta-state*.
This installs the gitea package, This installs Gitea,
manages the gitea configuration file manages its configuration
and then starts the associated gitea service. and then starts the ``gitea`` service.
gitea.package 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 gitea.config
^^^^^^^^^^^^ ^^^^^^^^^^^^
This state will configure the gitea service Manages Gitea configuration.
and has a dependency on ``gitea.install`` via include list. Has a dependency on `gitea.package`_.
gitea.service gitea.service
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
This state will start the gitea service Starts the Gitea service and enables it at boot time.
and has a dependency on ``gitea.config`` via include list. Has a dependency on `gitea.config`_.
gitea.go gitea.go
^^^^^^^^ ^^^^^^^^
Creates a build user and downloads Go.
Required for building Chroma.
gitea.mods.rst 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 gitea.clean
@@ -58,28 +66,28 @@ Some paths are left to avoid accidental data loss
gitea.package.clean gitea.package.clean
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
This state will remove the gitea package and has a depency on Removes Gitea.
``gitea.config.clean`` via include list. Has a dependency on `gitea.config.clean`_.
gitea.config.clean gitea.config.clean
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
This state will remove the configuration of the gitea service and has a Removes Gitea configuration. Has a dependency on `gitea.service.clean`_.
dependency on ``gitea.service.clean`` via include list.
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 gitea.go.clean
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Removes the build user and Go installation.
gitea.mods.rst.clean 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 # vim: ft=sls
{#- {#-
This state will remove the configuration of the gitea service and has a Removes Gitea configuration. Has a dependency on `gitea.service.clean`_.
dependency on ``gitea.service.clean`` via include list.
#} #}
{%- set tplroot = tpldir.split('/')[0] %} {%- set tplroot = tpldir.split('/')[0] %}

4
gitea/config/init.sls
View File

@@ -1,8 +1,8 @@
# vim: ft=sls # vim: ft=sls
{#- {#-
This state will configure the gitea service Manages Gitea configuration.
and has a dependency on ``gitea.install`` via include list. Has a dependency on `gitea.package`_.
#} #}
include: include:

5
gitea/go/clean.sls
View File

@@ -1,6 +1,9 @@
# -*- coding: utf-8 -*-
# vim: ft=sls # vim: ft=sls
{#-
Removes the build user and Go installation.
#}
{%- set tplroot = tpldir.split('/')[0] %} {%- set tplroot = tpldir.split('/')[0] %}
{%- set sls_config_file = tplroot ~ '.config.file' %} {%- set sls_config_file = tplroot ~ '.config.file' %}
{%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %}

5
gitea/go/init.sls
View File

@@ -1,6 +1,11 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# vim: ft=sls # vim: ft=sls
{#-
Creates a build user and downloads Go.
Required for building Chroma.
#}
{%- set tplroot = tpldir.split('/')[0] %} {%- set tplroot = tpldir.split('/')[0] %}
{%- set sls_config_file = tplroot ~ '.config.file' %} {%- set sls_config_file = tplroot ~ '.config.file' %}
{%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} {%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %}

6
gitea/init.sls
View File

@@ -3,9 +3,9 @@
{#- {#-
*Meta-state*. *Meta-state*.
This installs the gitea package, This installs Gitea,
manages the gitea configuration file manages its configuration
and then starts the associated gitea service. and then starts the ``gitea`` service.
#} #}
include: include:

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

@@ -1,6 +1,11 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# vim: ft=sls # vim: ft=sls
{#-
Removes the built ``chroma`` binary, the build path and the
``grst`` script.
#}
{%- set tplroot = tpldir.split('/')[0] %} {%- set tplroot = tpldir.split('/')[0] %}
{%- set sls_config_file = tplroot ~ '.config.file' %} {%- set sls_config_file = tplroot ~ '.config.file' %}
{%- from tplroot ~ "/map.jinja" import mapdata as gitea with context %} {%- 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 -*- # -*- coding: utf-8 -*-
# vim: ft=sls # 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 tplroot = tpldir.split('/')[0] %}
{%- set sls_config_file = tplroot ~ '.config.file' %} {%- set sls_config_file = tplroot ~ '.config.file' %}
{%- set sls_go_install = tplroot ~ '.go' %} {%- set sls_go_install = tplroot ~ '.go' %}

4
gitea/package/clean.sls
View File

@@ -1,8 +1,8 @@
# vim: ft=sls # vim: ft=sls
{#- {#-
This state will remove the gitea package and has a depency on Removes Gitea.
``gitea.config.clean`` via include list. Has a dependency on `gitea.config.clean`_.
#} #}
{%- set tplroot = tpldir.split('/')[0] %} {%- set tplroot = tpldir.split('/')[0] %}

5
gitea/package/init.sls
View File

@@ -1,7 +1,10 @@
# vim: ft=sls # 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: include:

2
gitea/service/clean.sls
View File

@@ -1,7 +1,7 @@
# vim: ft=sls # 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] %} {%- set tplroot = tpldir.split('/')[0] %}

4
gitea/service/init.sls
View File

@@ -1,8 +1,8 @@
# vim: ft=sls # vim: ft=sls
{#- {#-
This state will start the gitea service Starts the Gitea service and enables it at boot time.
and has a dependency on ``gitea.config`` via include list. Has a dependency on `gitea.config`_.
#} #}
include: include: