From e596f456f120a4eea9fa2619d2a0baf7f152da0c Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Fri, 23 Apr 2021 20:01:40 +0200 Subject: [PATCH 1/5] Add a README generator --- tools/READMEs/make_readme.py | 40 ++++++++++++++++++ tools/READMEs/templates/README.md.j2 | 53 ++++++++++++++++++++++++ tools/READMEs/templates/README_fr.md.j2 | 54 +++++++++++++++++++++++++ 3 files changed, 147 insertions(+) create mode 100644 tools/READMEs/make_readme.py create mode 100644 tools/READMEs/templates/README.md.j2 create mode 100644 tools/READMEs/templates/README_fr.md.j2 diff --git a/tools/READMEs/make_readme.py b/tools/READMEs/make_readme.py new file mode 100644 index 00000000..fcaa7f85 --- /dev/null +++ b/tools/READMEs/make_readme.py @@ -0,0 +1,40 @@ +from jinja2 import Environment, FileSystemLoader +import json +import os +import sys + +if len(sys.argv) <= 1: + raise Exception("You should provide the path to the app as first arg") + +app = sys.argv[1] + +if not os.path.exists(app): + 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, "manifest.json"))) + upstream = manifest.get("upstream", {}) + + if os.path.exists(os.path.join(app, "doc", "screenshots")): + screenshots = os.listdir(os.path.join(app, "doc", "screenshots")) + if ".gitkeep" in screenshots: + screenshots.remove(".gitkeep") + else: + screenshots = [] + + if os.path.exists(os.path.join(app, "doc", f"DISCLAIMER{lang_suffix}.md")): + disclaimer = open(os.path.join(app, "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, "doc", f"DISCLAIMER.md")): + disclaimer = open(os.path.join(app, "doc", f"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, f"README{lang_suffix}.md"), "w") as f: + f.write(out) diff --git a/tools/READMEs/templates/README.md.j2 b/tools/READMEs/templates/README.md.j2 new file mode 100644 index 00000000..b8bda148 --- /dev/null +++ b/tools/READMEs/templates/README.md.j2 @@ -0,0 +1,53 @@ +# {{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/READMEs/templates/README_fr.md.j2 b/tools/READMEs/templates/README_fr.md.j2 new file mode 100644 index 00000000..5ad17c28 --- /dev/null +++ b/tools/READMEs/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 From f8c150a217aa2d81134c97011d66d55c8f53fa06 Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Wed, 28 Apr 2021 20:11:42 +0200 Subject: [PATCH 2/5] Use argparse --- tools/READMEs/make_readme.py | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/tools/READMEs/make_readme.py b/tools/READMEs/make_readme.py index fcaa7f85..23bae03a 100644 --- a/tools/READMEs/make_readme.py +++ b/tools/READMEs/make_readme.py @@ -1,14 +1,17 @@ -from jinja2 import Environment, FileSystemLoader +import argparse import json import os -import sys -if len(sys.argv) <= 1: - raise Exception("You should provide the path to the app as first arg") +from jinja2 import Environment, FileSystemLoader -app = sys.argv[1] +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') -if not os.path.exists(app): +args = parser.parse_args() +app_path = args.app_path + +if not os.path.exists(app_path): raise Exception("App path provided doesn't exists ?!") env = Environment(loader=FileSystemLoader('./templates')) @@ -17,24 +20,24 @@ 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, "manifest.json"))) + manifest = json.load(open(os.path.join(app_path, "manifest.json"))) upstream = manifest.get("upstream", {}) - if os.path.exists(os.path.join(app, "doc", "screenshots")): - screenshots = os.listdir(os.path.join(app, "doc", "screenshots")) + 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, "doc", f"DISCLAIMER{lang_suffix}.md")): - disclaimer = open(os.path.join(app, "doc", f"DISCLAIMER{lang_suffix}.md")).read() + 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, "doc", f"DISCLAIMER.md")): - disclaimer = open(os.path.join(app, "doc", f"DISCLAIMER.md")).read() + 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, f"README{lang_suffix}.md"), "w") as f: + with open(os.path.join(app_path, f"README{lang_suffix}.md"), "w") as f: f.write(out) From 3b8d5f5152e023c163dc20b96236541189b0d396 Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Wed, 28 Apr 2021 20:11:53 +0200 Subject: [PATCH 3/5] Add requirements.txt --- tools/READMEs/requirements.txt | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 tools/READMEs/requirements.txt diff --git a/tools/READMEs/requirements.txt b/tools/READMEs/requirements.txt new file mode 100644 index 00000000..908d867d --- /dev/null +++ b/tools/READMEs/requirements.txt @@ -0,0 +1,2 @@ +argparse +jinja2 From 231890575060a9b4d6a5c3a56978ad0f9c075617 Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Wed, 28 Apr 2021 20:14:48 +0200 Subject: [PATCH 4/5] Factorize README generation into a function --- tools/READMEs/make_readme.py | 61 +++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 28 deletions(-) diff --git a/tools/READMEs/make_readme.py b/tools/READMEs/make_readme.py index 23bae03a..63dc8cbf 100644 --- a/tools/READMEs/make_readme.py +++ b/tools/READMEs/make_readme.py @@ -4,40 +4,45 @@ import os from jinja2 import Environment, FileSystemLoader -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() -app_path = args.app_path +def generate_READMEs(app_path): -if not os.path.exists(app_path): - raise Exception("App path provided doesn't exists ?!") + if not os.path.exists(app_path): + raise Exception("App path provided doesn't exists ?!") -env = Environment(loader=FileSystemLoader('./templates')) + env = Environment(loader=FileSystemLoader('./templates')) -for lang, lang_suffix in [("en", ""), ("fr", "_fr")]: + for lang, lang_suffix in [("en", ""), ("fr", "_fr")]: - template = env.get_template(f'README{lang_suffix}.md.j2') + 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", {}) + 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", "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 + 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) + 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) From 385ff4b079061a9cdd6d3f1ed0c6bbf39889306c Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Mon, 10 May 2021 17:23:40 +0200 Subject: [PATCH 5/5] Misc tweaks --- .../make_readme.py | 2 ++ .../requirements.txt | 0 .../templates/README.md.j2 | 19 +++++++++++++++++++ .../templates/README_fr.md.j2 | 0 4 files changed, 21 insertions(+) rename tools/{READMEs => README-generator}/make_readme.py (98%) mode change 100644 => 100755 rename tools/{READMEs => README-generator}/requirements.txt (100%) rename tools/{READMEs => README-generator}/templates/README.md.j2 (71%) rename tools/{READMEs => README-generator}/templates/README_fr.md.j2 (100%) diff --git a/tools/READMEs/make_readme.py b/tools/README-generator/make_readme.py old mode 100644 new mode 100755 similarity index 98% rename from tools/READMEs/make_readme.py rename to tools/README-generator/make_readme.py index 63dc8cbf..ffbc8f49 --- a/tools/READMEs/make_readme.py +++ b/tools/README-generator/make_readme.py @@ -1,3 +1,5 @@ +#! /usr/bin/python3 + import argparse import json import os diff --git a/tools/READMEs/requirements.txt b/tools/README-generator/requirements.txt similarity index 100% rename from tools/READMEs/requirements.txt rename to tools/README-generator/requirements.txt diff --git a/tools/READMEs/templates/README.md.j2 b/tools/README-generator/templates/README.md.j2 similarity index 71% rename from tools/READMEs/templates/README.md.j2 rename to tools/README-generator/templates/README.md.j2 index b8bda148..f368039e 100644 --- a/tools/READMEs/templates/README.md.j2 +++ b/tools/README-generator/templates/README.md.j2 @@ -1,3 +1,22 @@ +{% 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) diff --git a/tools/READMEs/templates/README_fr.md.j2 b/tools/README-generator/templates/README_fr.md.j2 similarity index 100% rename from tools/READMEs/templates/README_fr.md.j2 rename to tools/README-generator/templates/README_fr.md.j2