mirror of
https://github.com/YunoHost/yunohost.git
synced 2024-09-03 20:06:10 +02:00
159 lines
4 KiB
Python
159 lines
4 KiB
Python
import ast
|
|
import datetime
|
|
import subprocess
|
|
|
|
version = open("../debian/changelog").readlines()[0].split()[1].strip("()")
|
|
today = datetime.datetime.now().strftime("%d/%m/%Y")
|
|
|
|
|
|
def get_current_commit():
|
|
p = subprocess.Popen(
|
|
"git rev-parse --verify HEAD",
|
|
shell=True,
|
|
stdout=subprocess.PIPE,
|
|
stderr=subprocess.STDOUT,
|
|
)
|
|
stdout, stderr = p.communicate()
|
|
|
|
current_commit = stdout.strip().decode("utf-8")
|
|
return current_commit
|
|
|
|
|
|
current_commit = get_current_commit()
|
|
|
|
|
|
print(
|
|
f"""---
|
|
title: Config Panels
|
|
template: docs
|
|
taxonomy:
|
|
category: docs
|
|
routes:
|
|
default: '/packaging_config_panels'
|
|
---
|
|
|
|
Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/{current_commit}/doc/generate_configpanel_doc.py) on {today} (YunoHost version {version})
|
|
|
|
## Glossary
|
|
|
|
You may encounter some named types which are used for simplicity.
|
|
|
|
- `Translation`: a translated property
|
|
- used for properties: `ask`, `help` and `Pattern.error`
|
|
- a `dict` with locales as keys and translations as values:
|
|
```toml
|
|
ask.en = "The text in english"
|
|
ask.fr = "Le texte en français"
|
|
```
|
|
It is not currently possible for translators to translate those string in weblate.
|
|
- a single `str` for a single english default string
|
|
```toml
|
|
help = "The text in english"
|
|
```
|
|
- `JSExpression`: a `str` JS expression to be evaluated to `true` or `false`:
|
|
- used for properties: `visible` and `enabled`
|
|
- operators availables: `==`, `!=`, `>`, `>=`, `<`, `<=`, `!`, `&&`, `||`, `+`, `-`, `*`, `/`, `%` and `match()`
|
|
- [examples available in the advanced section of Options](/packaging_apps_options#advanced-use-cases)
|
|
"""
|
|
)
|
|
|
|
|
|
fname = "../src/utils/configpanel.py"
|
|
content = open(fname).read()
|
|
|
|
# NB: This magic is because we want to be able to run this script outside of a YunoHost context,
|
|
# in which we cant really 'import' the file because it will trigger a bunch of moulinette/yunohost imports...
|
|
tree = ast.parse(content)
|
|
|
|
OptionClasses = reversed(
|
|
[
|
|
c
|
|
for c in tree.body
|
|
if isinstance(c, ast.ClassDef)
|
|
and c.name in {"SectionModel", "PanelModel", "ConfigPanelModel"}
|
|
]
|
|
)
|
|
|
|
for c in OptionClasses:
|
|
doc = ast.get_docstring(c)
|
|
print("")
|
|
print("----------------")
|
|
print(f"## {c.name.replace('Model', '')}")
|
|
print("")
|
|
print(doc)
|
|
print("")
|
|
|
|
|
|
print(
|
|
"""
|
|
## Full example
|
|
|
|
We supposed we have an upstream app with this simple config.yml file:
|
|
```yaml
|
|
title: 'My dummy apps'
|
|
theme: 'white'
|
|
max_rate: 10
|
|
max_age: 365
|
|
```
|
|
|
|
We could for example create a simple configuration panel for it like this one, by following the syntax `\[PANEL.SECTION.QUESTION\]`:
|
|
```toml
|
|
version = "1.0"
|
|
[main]
|
|
|
|
[main.main]
|
|
[main.main.title]
|
|
ask.en = "Title"
|
|
type = "string"
|
|
bind = ":__INSTALL_DIR__/config.yml"
|
|
|
|
[main.main.theme]
|
|
ask.en = "Theme"
|
|
type = "select"
|
|
choices = ["white", "dark"]
|
|
bind = ":__INSTALL_DIR__/config.yml"
|
|
|
|
[main.limits]
|
|
[main.limits.max_rate]
|
|
ask.en = "Maximum display rate"
|
|
type = "number"
|
|
bind = ":__INSTALL_DIR__/config.yml"
|
|
|
|
[main.limits.max_age]
|
|
ask.en = "Duration of a dummy"
|
|
type = "number"
|
|
bind = ":__INSTALL_DIR__/config.yml"
|
|
```
|
|
|
|
Here we have created one `main` panel, containing the `main` and `limits` sections, containing questions according to params name of our `config.yml` file. Thanks to the `bind` properties, all those questions are bind to their values in the `config.yml` file.
|
|
|
|
## Overwrite config panel mechanism
|
|
|
|
All main configuration helpers are overwritable, example:
|
|
|
|
```bash
|
|
ynh_app_config_apply() {
|
|
|
|
# Stop vpn client
|
|
touch /tmp/.ynh-vpnclient-stopped
|
|
systemctl stop ynh-vpnclient
|
|
|
|
_ynh_app_config_apply
|
|
|
|
# Start vpn client
|
|
systemctl start ynh-vpnclient
|
|
rm -f /tmp/.ynh-vpnclient-stopped
|
|
|
|
}
|
|
```
|
|
|
|
List of main configuration helpers
|
|
* ynh_app_config_get
|
|
* ynh_app_config_show
|
|
* ynh_app_config_validate
|
|
* ynh_app_config_apply
|
|
* ynh_app_config_run
|
|
|
|
More info on this could be found by reading [vpnclient_ynh config script](https://github.com/YunoHost-Apps/vpnclient_ynh/blob/master/scripts/config)
|
|
"""
|
|
)
|