YunoHost/yunohost
1
0
Fork 0
mirror of https://github.com/YunoHost/yunohost.git synced 2024-09-03 20:06:10 +02:00
Code Issues Projects Releases Packages Wiki Activity

Update script to automatically generate helper documentation

Browse source
This commit is contained in:
Alexandre Aubin 2019-04-08 18:59:04 +02:00
parent c262313477
commit a9761d356b
8 changed files with 96 additions and 59 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
data/helpers.d/backend
View file

@ -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

39
data/helpers.d/filesystem
View file

@ -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 () {

4
data/helpers.d/mysql
View file

@ -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

12
data/helpers.d/network
View file

@ -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

2
data/helpers.d/system
View file

@ -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

11
data/helpers.d/user
View file

@ -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 () {

42
doc/generate_helper_doc.py
View file

@ -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
@ -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:

28
doc/helper_doc_template.html
View file

@ -2,7 +2,7 @@
<h1>App helpers</h1>
{% for category, helpers in data %}
{% for category, helpers in data.helpers %}
<h3 style="text-transform: uppercase; font-weight: bold">{{ category }}</h3>
@ -27,8 +27,12 @@
<p>
<strong>Arguments</strong>:
<ul>
{% for name, descr in h.args %}
<li><code>{{ name }}</code> : {{ descr }}</li>
{% for infos in h.args %}
{% if infos|length == 2 %}
<li><code>{{ infos[0] }}</code> : {{ infos[1] }}</li>
{% else %}
<li><code>{{ infos[0] }}</code>, <code>{{ infos[1] }}</code> : {{ infos[2] }}</li>
{% endif %}
{% endfor %}
</ul>
</p>
@ -38,11 +42,25 @@
<strong>Returns</strong>: {{ h.ret }}
</p>
{% endif %}
{% if h.example %}
{% if "example" in h.keys() %}
<p>
<strong>Example</strong>: <code class="helper-code">{{ h.example }}</code>
</p>
{% endif %}
{% if "examples" in h.keys() %}
<p>
<strong>Examples</strong>:<ul>
{% for example in h.examples %}
{% if not example.strip().startswith("# ") %}
<code class="helper-code">{{ example }}</code>
{% else %}
{{ example.strip("# ") }}
{% endif %}
<br>
{% endfor %}
</ul>
</p>
{% endif %}
{% if h.details %}
<p>
<strong>Details</strong>:
@ -63,6 +81,8 @@
{% endfor %}
{% endfor %}
<p>Generated by <a href="https://github.com/YunoHost/yunohost/blob/stretch-unstable/doc/generate_helper_doc.py">this script</a> on {{data.date}} (Yunohost version {{data.version}})</p>
<style>
/*=================================================