diff --git a/tools/README-generator/make_readme.py b/tools/README-generator/make_readme.py new file mode 100755 index 00000000..ffbc8f49 --- /dev/null +++ b/tools/README-generator/make_readme.py @@ -0,0 +1,50 @@ +#! /usr/bin/python3 + +import argparse +import json +import os + +from jinja2 import Environment, FileSystemLoader + + +def generate_READMEs(app_path): + + if not os.path.exists(app_path): + raise Exception("App path provided doesn't exists ?!") + + env = Environment(loader=FileSystemLoader('./templates')) + + for lang, lang_suffix in [("en", ""), ("fr", "_fr")]: + + template = env.get_template(f'README{lang_suffix}.md.j2') + + manifest = json.load(open(os.path.join(app_path, "manifest.json"))) + upstream = manifest.get("upstream", {}) + + if os.path.exists(os.path.join(app_path, "doc", "screenshots")): + screenshots = os.listdir(os.path.join(app_path, "doc", "screenshots")) + if ".gitkeep" in screenshots: + screenshots.remove(".gitkeep") + else: + screenshots = [] + + if os.path.exists(os.path.join(app_path, "doc", f"DISCLAIMER{lang_suffix}.md")): + disclaimer = open(os.path.join(app_path, "doc", f"DISCLAIMER{lang_suffix}.md")).read() + # Fallback to english if maintainer too lazy to translate the disclaimer idk + elif os.path.exists(os.path.join(app_path, "doc", "DISCLAIMER.md")): + disclaimer = open(os.path.join(app_path, "doc", "DISCLAIMER.md")).read() + else: + disclaimer = None + + out = template.render(lang=lang, upstream=upstream, screenshots=screenshots, disclaimer=disclaimer, manifest=manifest) + with open(os.path.join(app_path, f"README{lang_suffix}.md"), "w") as f: + f.write(out) + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description='Automatically (re)generate README for apps') + parser.add_argument('app_path', + help='Path to the app to generate/update READMEs for') + + args = parser.parse_args() + generate_READMEs(args.app_path) diff --git a/tools/README-generator/requirements.txt b/tools/README-generator/requirements.txt new file mode 100644 index 00000000..908d867d --- /dev/null +++ b/tools/README-generator/requirements.txt @@ -0,0 +1,2 @@ +argparse +jinja2 diff --git a/tools/README-generator/templates/README.md.j2 b/tools/README-generator/templates/README.md.j2 new file mode 100644 index 00000000..f368039e --- /dev/null +++ b/tools/README-generator/templates/README.md.j2 @@ -0,0 +1,72 @@ +{% if manifest.id == "example" %} +# Packaging your an app, starting from this example + +- Copy this app before working on it, using the ['Use this template'](https://github.com/YunoHost/example_ynh/generate) button on the Github repo. +- Edit the `manifest.json` with app specific info. +- Edit the `install`, `upgrade`, `remove`, `backup`, and `restore` scripts, and any relevant conf files in `conf/`. + - Using the [script helpers documentation.](https://yunohost.org/packaging_apps_helpers) +- Add a `LICENSE` file for the package. +- Edit `doc/DISCLAIMER*.md` +- The `README.md` files are to be automatically generated by https://github.com/YunoHost/apps/tree/master/tools/README-generator +{% endif %} + +--- + + + +# {{manifest.name}} for YunoHost + +[![Integration level](https://dash.yunohost.org/integration/{{manifest.id}}.svg)](https://dash.yunohost.org/appci/app/{{manifest.id}}) ![](https://ci-apps.yunohost.org/ci/badges/{{manifest.id}}.status.svg) ![](https://ci-apps.yunohost.org/ci/badges/{{manifest.id}}.maintain.svg) +[![Install {{manifest.id}} with YunoHost](https://install-app.yunohost.org/install-with-yunohost.svg)](https://install-app.yunohost.org/?app={{manifest.id}}) + +*[Lire ce readme en français.](./README_fr.md)* + +> *This package allows you to install {{manifest.id}} quickly and simply on a YunoHost server. +If you don't have YunoHost, please consult [the guide](https://yunohost.org/#/install) to learn how to install it.* + +## Overview + +{{manifest.description[lang]}} + +**Shipped version:** {{manifest.version}} + +{% if upstream.demo %}**Demo:** {{upstream.demo}}{% endif %} + +{% if screenshots %} +## Screenshots + +{% for screenshot in screenshots %} + ![](./doc/screenshots/{{screenshot}}) +{% endfor %} +{% endif %} + +{% if disclaimer %} +## Disclaimers / important information + +{{ disclaimer }} +{% endif %} + +## Documentation and resources + +{% if upstream.website %}* Official app website: {{ upstream.website }}{% endif %} +{% if upstream.userdoc %}* Official user documentation: {{ upstream.userdoc }}{% endif %} +{% if upstream.admindoc %}* Official admin documentation: {{ upstream.admindoc }}{% endif %} +{% if upstream.code %}* Upstream app code repository: {{ upstream.code }}{% endif %} +* YunoHost documentation for this app: https://yunohost.org/app_{{manifest.id}} +* Report a bug: https://github.com/YunoHost-Apps/{{manifest.id}}_ynh/issues + +## Developer info + +Please send your pull request to the [testing branch](https://github.com/YunoHost-Apps/{{manifest.id}}_ynh/tree/testing). + +To try the testing branch, please proceed like that. +``` +sudo yunohost app install https://github.com/YunoHost-Apps/{{manifest.id}}_ynh/tree/testing --debug +or +sudo yunohost app upgrade {{manifest.id}} -u https://github.com/YunoHost-Apps/{{manifest.id}}_ynh/tree/testing --debug +``` + +**More info regarding app packaging:** https://yunohost.org/packaging_apps diff --git a/tools/README-generator/templates/README_fr.md.j2 b/tools/README-generator/templates/README_fr.md.j2 new file mode 100644 index 00000000..5ad17c28 --- /dev/null +++ b/tools/README-generator/templates/README_fr.md.j2 @@ -0,0 +1,54 @@ +# {{manifest.name}} pour YunoHost + +[![Niveau d'intégration](https://dash.yunohost.org/integration/{{manifest.id}}.svg)](https://dash.yunohost.org/appci/app/{{manifest.id}}) ![](https://ci-apps.yunohost.org/ci/badges/{{manifest.id}}.status.svg) ![](https://ci-apps.yunohost.org/ci/badges/{{manifest.id}}.maintain.svg) +[![Installer {{manifest.id}} avec YunoHost](https://install-app.yunohost.org/install-with-yunohost.svg)](https://install-app.yunohost.org/?app={{manifest.id}}) + +*[Read this readme in english.](./README.md)* +*[Lire ce readme en français.](./README_fr.md)* + +> *This package allows you to install {{manifest.id}} quickly and simply on a YunoHost server. +If you don't have YunoHost, please consult [the guide](https://yunohost.org/#/install) to learn how to install it.* + +## Vue d'ensemble + +{{manifest.description[lang]}} + +**Version incluse:** {{manifest.version}} + +{% if upstream.demo %}**Démo:** {{upstream.demo}}{% endif %} + +{% if screenshots %} +## Captures d'écran + +{% for screenshot in screenshots %} + ![](./doc/screenshots/{{screenshot}}) +{% endfor %} +{% endif %} + +{% if disclaimer %} +## Avertissements / informations importantes + +{{ disclaimer }} +{% endif %} + +## Documentations et ressources + +{% if upstream.website %}* Site official de l'app : {{ upstream.website }}{% endif %} +{% if upstream.userdoc %}* Documentation officielle utilisateur: {{ upstream.userdoc }}{% endif %} +{% if upstream.admindoc %}* Documentation officielle de l'admin: {{ upstream.admindoc }}{% endif %} +{% if upstream.code %}* Dépôt de code officiel de l'app: {{ upstream.code }}{% endif %} +* Documentation YunoHost pour cette app: https://yunohost.org/app_{{manifest.id}} +* Signaler un bug: https://github.com/YunoHost-Apps/{{manifest.id}}_ynh/issues + +## Informations pour les développeurs + +Merci de faire vos pull request sur la [branche testing](https://github.com/YunoHost-Apps/{{manifest.id}}_ynh/tree/testing). + +Pour essayer la branche testing, procédez comme suit. +``` +sudo yunohost app install https://github.com/YunoHost-Apps/{{manifest.id}}_ynh/tree/testing --debug +or +sudo yunohost app upgrade {{manifest.id}} -u https://github.com/YunoHost-Apps/{{manifest.id}}_ynh/tree/testing --debug +``` + +**Plus d'infos sur le packaging d'applications:** https://yunohost.org/packaging_apps