From a9761d356b8c787cbef6f0fb38025e75cb5e1ef0 Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Mon, 8 Apr 2019 18:59:04 +0200 Subject: [PATCH] Update script to automatically generate helper documentation --- data/helpers.d/backend | 15 ++++++------ data/helpers.d/filesystem | 39 +++++++++++++------------------- data/helpers.d/mysql | 4 ++-- data/helpers.d/network | 12 ++++++---- data/helpers.d/system | 2 +- data/helpers.d/user | 11 ++++----- doc/generate_helper_doc.py | 44 ++++++++++++++++++++++++++++-------- doc/helper_doc_template.html | 28 +++++++++++++++++++---- 8 files changed, 96 insertions(+), 59 deletions(-) diff --git a/data/helpers.d/backend b/data/helpers.d/backend index 28c91e4f6..710e6299b 100644 --- a/data/helpers.d/backend +++ b/data/helpers.d/backend @@ -3,17 +3,17 @@ # Use logrotate to manage the logfile # # usage: ynh_use_logrotate [--logfile=/log/file] [--nonappend] [--specific_user=user/group] -# | arg: -l, --logfile= - absolute path of logfile -# | arg: -n, --nonappend - (Option) Replace the config file instead of appending this new config. +# | arg: -l, --logfile - absolute path of logfile +# | arg: -n, --nonappend - (optional) Replace the config file instead of appending this new config. # | arg: -u, --specific_user : run logrotate as the specified user and group. If not specified logrotate is runned as root. # -# If no argument provided, a standard directory will be use. /var/log/${app} -# You can provide a path with the directory only or with the logfile. +# If no --logfile is provided, /var/log/${app} will be used as default. +# logfile can be just a directory, or a full path to a logfile : # /parentdir/logdir # /parentdir/logdir/logfile.log # -# It's possible to use this helper several times, each config will be added to the same logrotate config file. -# Unless you use the option --non-append +# It's possible to use this helper multiple times, each config will be added to +# the same logrotate config file. Unless you use the option --non-append # # Requires YunoHost version 2.6.4 or higher. ynh_use_logrotate () { @@ -175,8 +175,7 @@ ynh_remove_systemd_config () { # # usage: ynh_add_nginx_config "list of others variables to replace" # -# | arg: list of others variables to replace separeted by a space -# | for example : 'path_2 port_2 ...' +# | arg: list - (Optional) list of others variables to replace separated by spaces. For example : 'path_2 port_2 ...' # # This will use a template in ../conf/nginx.conf # __PATH__ by $path_url diff --git a/data/helpers.d/filesystem b/data/helpers.d/filesystem index 6fb6347a6..07614d179 100644 --- a/data/helpers.d/filesystem +++ b/data/helpers.d/filesystem @@ -15,16 +15,13 @@ CAN_BIND=${CAN_BIND:-1} # If DEST is ended by a slash it complete this path with the basename of SRC. # # usage: ynh_backup --src_path=src_path [--dest_path=dest_path] [--is_big] [--not_mandatory] -# | arg: -s, --src_path - file or directory to bind or symlink or copy. it shouldn't be in -# the backup dir. -# | arg: -d, --dest_path - destination file or directory inside the -# backup dir +# | arg: -s, --src_path - file or directory to bind or symlink or copy. it shouldn't be in the backup dir. +# | arg: -d, --dest_path - destination file or directory inside the backup dir # | arg: -b, --is_big - Indicate data are big (mail, video, image ...) # | arg: -m, --not_mandatory - Indicate that if the file is missing, the backup can ignore it. # | arg: arg - Deprecated arg # -# example: -# # Wordpress app context +# Example in the context of a wordpress app # # ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" # # => This line will be added into CSV file @@ -198,28 +195,25 @@ with open(sys.argv[1], 'r') as backup_file: # Restore a file or a directory # # Use the registered path in backup_list by ynh_backup to restore the file at -# the good place. +# the right place. # # usage: ynh_restore_file --origin_path=origin_path [--dest_path=dest_path] [--not_mandatory] -# | arg: -o, --origin_path - Path where was located the file or the directory before -# to be backuped or relative path to $YNH_CWD where it is located in the backup archive -# | arg: -d, --dest_path - Path where restore the file or the dir, if unspecified, -# the destination will be ORIGIN_PATH or if the ORIGIN_PATH doesn't exist in -# the archive, the destination will be searched into backup.csv +# | arg: -o, --origin_path - Path where was located the file or the directory before to be backuped or relative path to $YNH_CWD where it is located in the backup archive +# | arg: -d, --dest_path - Path where restore the file or the dir, if unspecified, the destination will be ORIGIN_PATH or if the ORIGIN_PATH doesn't exist in the archive, the destination will be searched into backup.csv # | arg: -m, --not_mandatory - Indicate that if the file is missing, the restore process can ignore it. # +# examples: +# ynh_restore_file "/etc/nginx/conf.d/$domain.d/$app.conf" +# # You can also use relative paths: +# ynh_restore_file "conf/nginx.conf" +# # If DEST_PATH already exists and is lighter than 500 Mo, a backup will be made in # /home/yunohost.conf/backup/. Otherwise, the existing file is removed. # -# examples: -# ynh_restore_file "/etc/nginx/conf.d/$domain.d/$app.conf" -# # if apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf exists, restore it into -# # /etc/nginx/conf.d/$domain.d/$app.conf -# # if no, search a correspondance in the csv (eg: conf/nginx.conf) and restore it into -# # /etc/nginx/conf.d/$domain.d/$app.conf -# -# # DON'T GIVE THE ARCHIVE PATH: -# ynh_restore_file "conf/nginx.conf" +# if apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf exists, restore it into +# /etc/nginx/conf.d/$domain.d/$app.conf +# if no, search for a match in the csv (eg: conf/nginx.conf) and restore it into +# /etc/nginx/conf.d/$domain.d/$app.conf # # Requires YunoHost version 2.6.4 or higher. ynh_restore_file () { @@ -348,8 +342,7 @@ ynh_store_file_checksum () { # # usage: ynh_backup_if_checksum_is_different --file=file # | arg: -f, --file - The file on which the checksum test will be perfomed. -# -# | ret: Return the name a the backup file, or nothing +# | ret: the name of a backup file, or nothing # # Requires YunoHost version 2.6.4 or higher. ynh_backup_if_checksum_is_different () { diff --git a/data/helpers.d/mysql b/data/helpers.d/mysql index 313b7a245..d7400db2d 100644 --- a/data/helpers.d/mysql +++ b/data/helpers.d/mysql @@ -186,7 +186,7 @@ ynh_mysql_drop_user() { # usage: ynh_mysql_setup_db --db_user=user --db_name=name [--db_pwd=pwd] # | arg: -u, --db_user - Owner of the database # | arg: -n, --db_name - Name of the database -# | arg: -p, --db_pwd - Password of the database. If not given, a password will be generated +# | arg: -p, --db_pwd - Password of the database. If not provided, a password will be generated # # Requires YunoHost version 2.6.4 or higher. ynh_mysql_setup_db () { @@ -200,7 +200,7 @@ ynh_mysql_setup_db () { ynh_handle_getopts_args "$@" local new_db_pwd=$(ynh_string_random) # Generate a random password - # If $db_pwd is not given, use new_db_pwd instead for db_pwd + # If $db_pwd is not provided, use new_db_pwd instead for db_pwd db_pwd="${db_pwd:-$new_db_pwd}" ynh_mysql_create_db "$db_name" "$db_user" "$db_pwd" # Create the database diff --git a/data/helpers.d/network b/data/helpers.d/network index 8812f8f39..4dc080203 100644 --- a/data/helpers.d/network +++ b/data/helpers.d/network @@ -1,14 +1,16 @@ #!/bin/bash # Normalize the url path syntax +# # Handle the slash at the beginning of path and its absence at ending # Return a normalized url path # -# example: url_path=$(ynh_normalize_url_path $url_path) -# ynh_normalize_url_path example -> /example -# ynh_normalize_url_path /example -> /example -# ynh_normalize_url_path /example/ -> /example -# ynh_normalize_url_path / -> / +# examples: +# url_path=$(ynh_normalize_url_path $url_path) +# ynh_normalize_url_path example # -> /example +# ynh_normalize_url_path /example # -> /example +# ynh_normalize_url_path /example/ # -> /example +# ynh_normalize_url_path / # -> / # # usage: ynh_normalize_url_path --path_url=path_to_normalize # | arg: -p, --path_url - URL path to normalize before using it diff --git a/data/helpers.d/system b/data/helpers.d/system index a491b19b5..757fdf93c 100644 --- a/data/helpers.d/system +++ b/data/helpers.d/system @@ -241,7 +241,7 @@ ynh_app_package_version () { # - UPGRADE_APP if the upstream app version has changed # - UPGRADE_PACKAGE if only the YunoHost package has changed # -## It stops the current script without error if the package is up-to-date +# It stops the current script without error if the package is up-to-date # # This helper should be used to avoid an upgrade of an app, or the upstream part # of it, when it's not needed diff --git a/data/helpers.d/user b/data/helpers.d/user index 83fa47aa8..9ee44515d 100644 --- a/data/helpers.d/user +++ b/data/helpers.d/user @@ -89,16 +89,15 @@ ynh_system_group_exists() { # Create a system user # # examples: -# - ynh_system_user_create --username=nextcloud -> creates a nextcloud user with -# no home directory and /usr/sbin/nologin login shell (hence no login capability) -# - ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell --> creates a -# discourse user using /var/www/discourse as home directory and the default login shell +# # Create a nextcloud user with no home directory and /usr/sbin/nologin login shell (hence no login capability) +# ynh_system_user_create --username=nextcloud +# # Create a discourse user using /var/www/discourse as home directory and the default login shell +# ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell # # usage: ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell] # | arg: -u, --username - Name of the system user that will be create # | arg: -h, --home_dir - Path of the home dir for the user. Usually the final path of the app. If this argument is omitted, the user will be created without home -# | arg: -s, --use_shell - Create a user using the default login shell if present. -# If this argument is omitted, the user will be created with /usr/sbin/nologin shell +# | arg: -s, --use_shell - Create a user using the default login shell if present. If this argument is omitted, the user will be created with /usr/sbin/nologin shell # # Requires YunoHost version 2.6.4 or higher. ynh_system_user_create () { diff --git a/doc/generate_helper_doc.py b/doc/generate_helper_doc.py index 7d8c489b7..5b51dda02 100644 --- a/doc/generate_helper_doc.py +++ b/doc/generate_helper_doc.py @@ -4,7 +4,12 @@ import os import glob import datetime -def render(data): +def render(helpers): + + data = { "helpers": helpers, + "date": datetime.datetime.now().strftime("%m/%d/%Y"), + "version": open("../debian/changelog").readlines()[0].split()[1].strip("()") + } from jinja2 import Template from ansi2html import Ansi2HTMLConverter @@ -43,7 +48,7 @@ class Parser(): "code": [] } for i, line in enumerate(self.file): - + if line.startswith("#!/bin/bash"): continue @@ -103,7 +108,6 @@ class Parser(): b["usage"] = "" b["args"] = [] b["ret"] = "" - b["example"] = "" subblocks = '\n'.join(b["comments"]).split("\n\n") @@ -114,17 +118,29 @@ class Parser(): b["brief"] = subblock continue - elif subblock.startswith("example"): + elif subblock.startswith("example:"): b["example"] = " ".join(subblock.split()[1:]) continue + elif subblock.startswith("examples:"): + b["examples"] = subblock.split("\n")[1:] + continue + elif subblock.startswith("usage"): for line in subblock.split("\n"): if line.startswith("| arg"): - argname = line.split()[2] - argdescr = " ".join(line.split()[4:]) - b["args"].append((argname, argdescr)) + linesplit = line.split() + argname = linesplit[2] + # Detect that there's a long argument version (-f, --foo - Some description) + if argname.endswith(",") and linesplit[3].startswith("--"): + argname = argname.strip(",") + arglongname = linesplit[3] + argdescr = " ".join(linesplit[5:]) + b["args"].append((argname, arglongname, argdescr)) + else: + argdescr = " ".join(linesplit[4:]) + b["args"].append((argname, argdescr)) elif line.startswith("| ret"): b["ret"] = " ".join(line.split()[2:]) else: @@ -136,9 +152,17 @@ class Parser(): elif subblock.startswith("| arg"): for line in subblock.split("\n"): if line.startswith("| arg"): - argname = line.split()[2] - argdescr = line.split()[4:] - b["args"].append((argname, argdescr)) + linesplit = line.split() + argname = linesplit[2] + # Detect that there's a long argument version (-f, --foo - Some description) + if argname.endswith(",") and linesplit[3].startswith("--"): + argname = argname.strip(",") + arglongname = linesplit[3] + argdescr = " ".join(linesplit[5:]) + b["args"].append((argname, arglongname, argdescr)) + else: + argdescr = " ".join(linesplit[4:]) + b["args"].append((argname, argdescr)) continue else: diff --git a/doc/helper_doc_template.html b/doc/helper_doc_template.html index 1fa1f68ad..92611c737 100644 --- a/doc/helper_doc_template.html +++ b/doc/helper_doc_template.html @@ -2,7 +2,7 @@

App helpers

-{% for category, helpers in data %} +{% for category, helpers in data.helpers %}

{{ category }}

@@ -27,8 +27,12 @@

Arguments:

@@ -38,11 +42,25 @@ Returns: {{ h.ret }}

{% endif %} - {% if h.example %} + {% if "example" in h.keys() %}

Example: {{ h.example }}

{% endif %} + {% if "examples" in h.keys() %} +

+ Examples:

+

+ {% endif %} {% if h.details %}

Details: @@ -63,6 +81,8 @@ {% endfor %} {% endfor %} +

Generated by this script on {{data.date}} (Yunohost version {{data.version}})

+