Merge pull request #1136 from YunoHost/readme-generator

README generator

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)

tools/README-generator/requirements.txt

@@ -0,0 +1,2 @@
+argparse
+jinja2

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 %}
+
+---
+
+<!--
+N.B.: This README was automatically generated by https://github.com/YunoHost/apps/tree/master/tools/README-generator
+It shall NOT be edited by hand.
+-->
+
+# {{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

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