Merge pull request YunoHost#2571 from YunoHost/move_scripts

Move here doc generator scripts from the yunohost repository

Author: Salamandar

.gitignore

@@ -7,3 +7,4 @@
 !/docker-compose.yml
 !/dev/plugins
 !/markdownlint-rules-grav-pages
+!/scripts

tests/dead_links.py renamed to scripts/dead_links.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2024 YunoHost Contributors
+#
+# This file is part of YunoHost (see https://yunohost.org)
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+import argparse
+import ast
+import datetime
+import subprocess
+from pathlib import Path
+
+from jinja2 import Template
+
+
+TEMPLATE_FILE = Path(__file__).resolve().parent / "forms_doc_template.md.j2"
+
+def get_current_commit(docdir: Path) -> str:
+    p = subprocess.Popen(
+        ["git", "rev-parse", "--verify", "HEAD"],
+        cwd=docdir,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    stdout, stderr = p.communicate()
+
+    current_commit = stdout.strip().decode("utf-8")
+    return current_commit
+
+
+def get_changelog_version(srcdir: Path) -> str:
+    changelog_file = srcdir / "debian" / "changelog"
+    version = changelog_file.open("r").readline().split()[1].strip("()")
+    return version
+
+
+##############################################################################
+
+
+def dict_key_first(dict: dict, key) -> dict:
+    value = dict.pop(key)
+    return {key: value, **dict}
+
+
+def list_config_panel(srcdir: Path) -> dict[str, str]:
+    configpanel_file = srcdir / "src" / "utils" / "configpanel.py"
+
+    # 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(configpanel_file.read_text())
+
+    classes: dict[str, str] = {}
+
+    for cl in reversed(tree.body):
+        if isinstance(cl, ast.ClassDef):
+            if cl.name in ["SectionModel", "PanelModel", "ConfigPanelModel"]:
+                docstring = ast.get_docstring(cl)
+                assert isinstance(docstring, str)
+                classes[cl.name.replace("Model", "")] = docstring
+
+    return classes
+
+
+def list_form_options(srcdir: Path) -> dict[str, str]:
+    configpanel_file = srcdir / "src" / "utils" / "form.py"
+
+    # 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(configpanel_file.read_text())
+
+    options: dict[str, str] = {}
+
+    for cl in tree.body:
+        if not isinstance(cl, ast.ClassDef):
+            continue
+        if not cl.name.endswith("Option"):
+            continue
+        if not isinstance(cl.body[0], ast.Expr):
+            continue
+
+        assert isinstance(cl.body[1], ast.AnnAssign)
+        assert isinstance(cl.body[1].target, ast.Name)
+        assert isinstance(cl.bases[0], ast.Name)
+
+        # Determine the title of the section
+        if cl.name == "BaseOption":
+            name = "Common properties"
+
+        elif cl.name == "BaseInputOption":
+            name = "Common inputs properties"
+
+        else:
+            assert cl.body[1].target.id == "type"
+            assert isinstance(cl.body[1].value, ast.Attribute)
+            option_type = cl.body[1].value.attr
+
+            if option_type == "display_text":
+                # display_text is kind of legacy x_x
+                continue
+
+            name = f"`{option_type}`"
+
+            if cl.bases:
+                base_type = cl.bases[0].id.replace("Option", "")
+                base_type = base_type.replace("Base", "").lower()
+                name += f" ({base_type})"
+
+        docstring = ast.get_docstring(cl)
+        if docstring:
+            options[name] = docstring
+
+    # Dirty hack to have "Common properties" as first and "Common inputs properties" as 2nd in list
+    options = dict_key_first(options, "Common inputs properties")
+    options = dict_key_first(options, "Common properties")
+    return options
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--input", "-i", type=Path, required=True, help="Input yunohost source directory")
+    parser.add_argument("--output", "-o", type=Path, required=True)
+    args = parser.parse_args()
+
+    config_panel = list_config_panel(args.input)
+    options = list_form_options(args.input)
+    version = get_changelog_version(args.input)
+    commit = get_current_commit(Path(__file__).parent)
+
+    template = Template(TEMPLATE_FILE.read_text())
+    template.globals["now"] = datetime.datetime.utcnow
+
+    result = template.render(
+        configpanel=config_panel,
+        options=options,
+        date=datetime.datetime.now().strftime("%d/%m/%Y"),
+        version=version,
+        current_commit=commit,
+    )
+
+    args.output.write_text(result)
+
+
+if __name__ == "__main__":
+    main()

scripts/forms_doc_generate.py

@@ -0,0 +1,79 @@
+---
+title: Technical details for config panel structure and form option types
+template: docs
+taxonomy:
+    category: docs
+routes:
+  default: '/dev/forms'
+---
+
+Doc auto-generated by [this script](https://github.com/YunoHost/doc/blob/{{ current_commit }}/scripts/forms_doc_generate.py) on {{date}} (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()`
+- `Binding`: bind a value to a file/property/variable/getter/setter/validator
+  - save the value in `settings.yaml` when not defined
+  - nothing at all with `"null"`
+  - a custom getter/setter/validator with `"null"` + a function starting with `get__`, `set__`, `validate__` in `scripts/config`
+  - a variable/property in a file with `:__FINALPATH__/my_file.php`
+  - a whole file with `__FINALPATH__/my_file.php`
+- `Pattern`: a `dict` with a regex to match the value against and an error message
+
+  ```toml
+  pattern.regexp = '^[A-F]\d\d$'
+  pattern.error = "Provide a room number such as F12: one uppercase and 2 numbers"
+  # or with translated error
+  pattern.error.en = "Provide a room number such as F12: one uppercase and 2 numbers"
+  pattern.error.fr = "Entrez un numéro de salle comme F12: une lettre majuscule et deux chiffres."
+  ```
+
+  - IMPORTANT: your `pattern.regexp` should be between simple quote, not double.
+
+## Configuration panel structure
+{% for name, docstring in configpanel.items() %}
+### {{name}}
+
+{{docstring}}
+{% if not loop.last %}
+---
+{% endif %}
+{%- endfor %}
+---
+
+## List of all option types
+{% for name, docstring in options.items() %}
+### {{name}}
+
+{{docstring}}
+{%- if "#### Properties" not in docstring %}
+
+#### Properties
+
+- [common properties](#common-properties)
+{%- endif %}
+{% if not loop.last %}
+---
+{% endif %}
+{%- endfor %}

scripts/forms_doc_template.md.j2

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+set -x
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+SRCDIR=$1
+
+DOCDIR=$(dirname "$SCRIPT_DIR")
+
+"$SCRIPT_DIR/helpers_doc_generate.py" 2     -i "$SRCDIR" -o "$DOCDIR/pages/06.contribute/10.packaging_apps/20.scripts/10.helpers/packaging_app_scripts_helpers.md"
+"$SCRIPT_DIR/helpers_doc_generate.py" 2.1   -i "$SRCDIR" -o "$DOCDIR/pages/06.contribute/10.packaging_apps/20.scripts/12.helpers21/packaging_app_scripts_helpers_v21.md"
+"$SCRIPT_DIR/resources_doc_generate.py"     -i "$SRCDIR" -o "$DOCDIR/pages/06.contribute/10.packaging_apps/10.manifest/10.appresources/packaging_app_manifest_resources.md"
+"$SCRIPT_DIR/forms_doc_generate.py"         -i "$SRCDIR" -o "$DOCDIR/pages/06.contribute/15.dev/03.forms/forms.md"