From 935b972d6e61a8966da862cdee4421ce8e5ffb19 Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Fri, 9 Mar 2018 17:55:07 +0100 Subject: [PATCH 1/2] Misc fixes in the helpers to clean the autodoc --- data/helpers.d/backend | 17 ++++++++--------- data/helpers.d/ip | 10 +++++----- data/helpers.d/mysql | 4 ++-- data/helpers.d/system | 32 +++++++++++++++++--------------- 4 files changed, 32 insertions(+), 31 deletions(-) diff --git a/data/helpers.d/backend b/data/helpers.d/backend index c2c626829..28c5b8e91 100644 --- a/data/helpers.d/backend +++ b/data/helpers.d/backend @@ -2,7 +2,7 @@ # # usage: ynh_use_logrotate [logfile] [--non-append] # | arg: logfile - absolute path of logfile -# | option: --non-append - Replace the config file instead of appending this new config. +# | arg: --non-append - (Option) Replace the config file instead of appending this new config. # # 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. @@ -64,9 +64,9 @@ ynh_remove_logrotate () { # Create a dedicated systemd config # -# usage: ynh_add_systemd_config [Service name] [Template name] -# | arg: Service name (optionnal, $app by default) -# | arg: Name of template file (optionnal, this is 'systemd' by default, meaning ./conf/systemd.service will be used as template) +# usage: ynh_add_systemd_config [service] [template] +# | arg: service - Service name (optionnal, $app by default) +# | arg: template - Name of template file (optionnal, this is 'systemd' by default, meaning ./conf/systemd.service will be used as template) # # This will use the template ../conf/.service # to generate a systemd config, by replacing the following keywords @@ -76,7 +76,6 @@ ynh_remove_logrotate () { # __APP__ by $app # __FINALPATH__ by $final_path # -# usage: ynh_add_systemd_config ynh_add_systemd_config () { local service_name="${1:-$app}" @@ -101,10 +100,9 @@ ynh_add_systemd_config () { # Remove the dedicated systemd config # -# usage: ynh_remove_systemd_config [Service name] -# | arg: Service name (optionnal, $app by default) +# usage: ynh_remove_systemd_config [service] +# | arg: service - Service name (optionnal, $app by default) # -# usage: ynh_remove_systemd_config ynh_remove_systemd_config () { local service_name="${1:-$app}" @@ -119,6 +117,8 @@ ynh_remove_systemd_config () { # Create a dedicated nginx config # +# usage: ynh_add_nginx_config +# # This will use a template in ../conf/nginx.conf # __PATH__ by $path_url # __DOMAIN__ by $domain @@ -126,7 +126,6 @@ ynh_remove_systemd_config () { # __NAME__ by $app # __FINALPATH__ by $final_path # -# usage: ynh_add_nginx_config ynh_add_nginx_config () { finalnginxconf="/etc/nginx/conf.d/$domain.d/$app.conf" ynh_backup_if_checksum_is_different "$finalnginxconf" diff --git a/data/helpers.d/ip b/data/helpers.d/ip index 874675c9d..092cdff4b 100644 --- a/data/helpers.d/ip +++ b/data/helpers.d/ip @@ -1,10 +1,10 @@ # Validate an IP address # +# usage: ynh_validate_ip [family] [ip_address] +# | ret: 0 for valid ip addresses, 1 otherwise +# # example: ynh_validate_ip 4 111.222.333.444 # -# usage: ynh_validate_ip -# -# exit code : 0 for valid ip addresses, 1 otherwise ynh_validate_ip() { # http://stackoverflow.com/questions/319279/how-to-validate-ip-address-in-python#319298 @@ -31,8 +31,8 @@ EOF # example: ynh_validate_ip4 111.222.333.444 # # usage: ynh_validate_ip4 +# | ret: 0 for valid ipv4 addresses, 1 otherwise # -# exit code : 0 for valid ipv4 addresses, 1 otherwise ynh_validate_ip4() { ynh_validate_ip 4 $1 @@ -44,8 +44,8 @@ ynh_validate_ip4() # example: ynh_validate_ip6 2000:dead:beef::1 # # usage: ynh_validate_ip6 +# | ret: 0 for valid ipv6 addresses, 1 otherwise # -# exit code : 0 for valid ipv6 addresses, 1 otherwise ynh_validate_ip6() { ynh_validate_ip 6 $1 diff --git a/data/helpers.d/mysql b/data/helpers.d/mysql index 8aa81a1fe..452a95eec 100644 --- a/data/helpers.d/mysql +++ b/data/helpers.d/mysql @@ -90,7 +90,7 @@ ynh_mysql_create_user() { # # usage: ynh_mysql_user_exists user # | arg: user - the user for which to check existence -function ynh_mysql_user_exists() +ynh_mysql_user_exists() { local user=$1 if [[ -z $(ynh_mysql_execute_as_root "SELECT User from mysql.user WHERE User = '$user';") ]] @@ -153,7 +153,7 @@ ynh_mysql_remove_db () { # Sanitize a string intended to be the name of a database # (More specifically : replace - and . by _) # -# Exemple: dbname=$(ynh_sanitize_dbid $app) +# example: dbname=$(ynh_sanitize_dbid $app) # # usage: ynh_sanitize_dbid name # | arg: name - name to correct/sanitize diff --git a/data/helpers.d/system b/data/helpers.d/system index f204c836a..dbd21a4ec 100644 --- a/data/helpers.d/system +++ b/data/helpers.d/system @@ -1,18 +1,17 @@ # Manage a fail of the script # -# Print a warning to inform that the script was failed -# Execute the ynh_clean_setup function if used in the app script -# -# usage of ynh_clean_setup function -# This function provide a way to clean some residual of installation that not managed by remove script. -# To use it, simply add in your script: +# usage: +# ynh_exit_properly is used only by the helper ynh_abort_if_errors. +# You should not use it directly. +# Instead, add to your script: # ynh_clean_setup () { # instructions... # } -# This function is optionnal. # -# Usage: ynh_exit_properly is used only by the helper ynh_abort_if_errors. -# You must not use it directly. +# This function provide a way to clean some residual of installation that not managed by remove script. +# +# It prints a warning to inform that the script was failed, and execute the ynh_clean_setup function if used in the app script +# ynh_exit_properly () { local exit_code=$? if [ "$exit_code" -eq 0 ]; then @@ -31,20 +30,23 @@ ynh_exit_properly () { ynh_die # Exit with error status } -# Exit if an error occurs during the execution of the script. +# Exits if an error occurs during the execution of the script. # -# Stop immediatly the execution if an error occured or if a empty variable is used. -# The execution of the script is derivate to ynh_exit_properly function before exit. +# usage: ynh_abort_if_errors +# +# This configure the rest of the script execution such that, if an error occurs +# or if an empty variable is used, the execution of the script stops +# immediately and a call to `ynh_exit_properly` is triggered. # -# Usage: ynh_abort_if_errors ynh_abort_if_errors () { set -eu # Exit if a command fail, and if a variable is used unset. trap ynh_exit_properly EXIT # Capturing exit signals on shell script } -# Return the Debian release codename (i.e. jessie, stretch, etc.) +# Fetch the Debian release codename # # usage: ynh_get_debian_release +# | ret: The Debian release codename (i.e. jessie, stretch, ...) ynh_get_debian_release () { echo $(lsb_release --codename --short) -} \ No newline at end of file +} From af22474a5068093f22b0074c01eaa784d29a0d5d Mon Sep 17 00:00:00 2001 From: Alexandre Aubin Date: Sat, 10 Mar 2018 19:01:33 +0100 Subject: [PATCH 2/2] Add some [internal] flags in the comment to hide a few helpers from autodoc --- data/helpers.d/filesystem | 7 +++++++ data/helpers.d/mysql | 8 ++++++++ data/helpers.d/package | 4 ++++ data/helpers.d/print | 4 ++++ data/helpers.d/system | 5 ++++- 5 files changed, 27 insertions(+), 1 deletion(-) diff --git a/data/helpers.d/filesystem b/data/helpers.d/filesystem index 6361d278e..6836aeebe 100644 --- a/data/helpers.d/filesystem +++ b/data/helpers.d/filesystem @@ -136,6 +136,8 @@ ynh_restore () { # Return the path in the archive where has been stocked the origin path # +# [internal] +# # usage: _get_archive_path ORIGIN_PATH _get_archive_path () { # For security reasons we use csv python library to read the CSV @@ -203,6 +205,9 @@ ynh_restore_file () { } # Deprecated helper since it's a dangerous one! +# +# [internal] +# ynh_bind_or_cp() { local AS_ROOT=${3:-0} local NO_ROOT=0 @@ -213,6 +218,8 @@ ynh_bind_or_cp() { # Create a directory under /tmp # +# [internal] +# # Deprecated helper # # usage: ynh_mkdir_tmp diff --git a/data/helpers.d/mysql b/data/helpers.d/mysql index 452a95eec..7bc93fad5 100644 --- a/data/helpers.d/mysql +++ b/data/helpers.d/mysql @@ -35,6 +35,8 @@ ynh_mysql_execute_file_as_root() { # Create a database and grant optionnaly privilegies to a user # +# [internal] +# # usage: ynh_mysql_create_db db [user [pwd]] # | arg: db - the database name to create # | arg: user - the user to grant privilegies @@ -56,6 +58,8 @@ ynh_mysql_create_db() { # Drop a database # +# [internal] +# # If you intend to drop the database *and* the associated user, # consider using ynh_mysql_remove_db instead. # @@ -78,6 +82,8 @@ ynh_mysql_dump_db() { # Create a user # +# [internal] +# # usage: ynh_mysql_create_user user pwd [host] # | arg: user - the user name to create # | arg: pwd - the password to identify user by @@ -103,6 +109,8 @@ ynh_mysql_user_exists() # Drop a user # +# [internal] +# # usage: ynh_mysql_drop_user user # | arg: user - the user name to drop ynh_mysql_drop_user() { diff --git a/data/helpers.d/package b/data/helpers.d/package index c616105d1..4d147488c 100644 --- a/data/helpers.d/package +++ b/data/helpers.d/package @@ -26,6 +26,8 @@ ynh_package_version() { # APT wrapper for non-interactive operation # +# [internal] +# # usage: ynh_apt update ynh_apt() { DEBIAN_FRONTEND=noninteractive sudo apt-get -y -qq $@ @@ -73,6 +75,8 @@ ynh_package_autopurge() { # Build and install a package from an equivs control file # +# [internal] +# # example: generate an empty control file with `equivs-control`, adjust its # content and use helper to build and install the package: # ynh_package_install_from_equivs /path/to/controlfile diff --git a/data/helpers.d/print b/data/helpers.d/print index d9c8f1ec4..b13186d62 100644 --- a/data/helpers.d/print +++ b/data/helpers.d/print @@ -6,7 +6,11 @@ ynh_die() { } # Ignore the yunohost-cli log to prevent errors with conditionals commands +# +# [internal] +# # usage: ynh_no_log COMMAND +# # Simply duplicate the log, execute the yunohost command and replace the log without the result of this command # It's a very badly hack... ynh_no_log() { diff --git a/data/helpers.d/system b/data/helpers.d/system index dbd21a4ec..70cc57493 100644 --- a/data/helpers.d/system +++ b/data/helpers.d/system @@ -1,5 +1,7 @@ # Manage a fail of the script # +# [internal] +# # usage: # ynh_exit_properly is used only by the helper ynh_abort_if_errors. # You should not use it directly. @@ -36,7 +38,8 @@ ynh_exit_properly () { # # This configure the rest of the script execution such that, if an error occurs # or if an empty variable is used, the execution of the script stops -# immediately and a call to `ynh_exit_properly` is triggered. +# immediately and a call to `ynh_clean_setup` is triggered if it has been +# defined by your script. # ynh_abort_if_errors () { set -eu # Exit if a command fail, and if a variable is used unset.