diff --git a/doc/generate_helper_doc.py b/doc/generate_helper_doc.py index 110d1d4cd..77a515399 100644 --- a/doc/generate_helper_doc.py +++ b/doc/generate_helper_doc.py @@ -119,7 +119,7 @@ class Parser: # Then we keep this bloc and start a new one # (we ignore helpers containing [internal] ...) - if "[internal]" not in current_block["comments"]: + if "[packagingv1]" not in current_block["comments"] and "[internal]" not in current_block["comments"]: self.blocks.append(current_block) current_block = { "name": None, diff --git a/helpers/apt b/helpers/apt index 5ce94e26c..eceabcf16 100644 --- a/helpers/apt +++ b/helpers/apt @@ -66,6 +66,8 @@ ynh_package_is_installed() { # # example: version=$(ynh_package_version --package=yunohost) # +# [internal] +# # usage: ynh_package_version --package=name # | arg: -p, --package= - the package name to get version # | ret: the version or an empty string @@ -100,6 +102,8 @@ ynh_apt() { # Update package index files # +# [internal] +# # usage: ynh_package_update # # Requires YunoHost version 2.2.4 or higher. @@ -109,6 +113,8 @@ ynh_package_update() { # Install package(s) # +# [internal] +# # usage: ynh_package_install name [name [...]] # | arg: name - the package name to install # @@ -120,6 +126,8 @@ ynh_package_install() { # Remove package(s) # +# [internal] +# # usage: ynh_package_remove name [name [...]] # | arg: name - the package name to remove # @@ -130,6 +138,8 @@ ynh_package_remove() { # Remove package(s) and their uneeded dependencies # +# [internal] +# # usage: ynh_package_autoremove name [name [...]] # | arg: name - the package name to remove # @@ -140,6 +150,8 @@ ynh_package_autoremove() { # Purge package(s) and their uneeded dependencies # +# [internal] +# # usage: ynh_package_autopurge name [name [...]] # | arg: name - the package name to autoremove and purge # @@ -212,6 +224,8 @@ YNH_INSTALL_APP_DEPENDENCIES_REPLACE="true" # Define and install dependencies with a equivs control file # +# [packagingv1] +# # This helper can/should only be called once per app # # example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5" @@ -330,6 +344,8 @@ EOF # Add dependencies to install with ynh_install_app_dependencies # +# [packagingv1] +# # usage: ynh_add_app_dependencies --package=phpversion [--replace] # | arg: -p, --package= - Packages to add as dependencies for the app. # @@ -348,6 +364,8 @@ ynh_add_app_dependencies() { # Remove fake package and its dependencies # +# [packagingv1] +# # Dependencies will removed only if no other package need them. # # usage: ynh_remove_app_dependencies @@ -380,6 +398,8 @@ ynh_remove_app_dependencies() { # Install packages from an extra repository properly. # +# [packagingv1] +# # usage: ynh_install_extra_app_dependencies --repo="repo" --package="dep1 dep2" [--key=key_url] [--name=name] # | arg: -r, --repo= - Complete url of the extra repository. # | arg: -p, --package= - The packages to install from this extra repository diff --git a/helpers/backup b/helpers/backup index ade3ce5e5..a596ac9e0 100644 --- a/helpers/backup +++ b/helpers/backup @@ -417,6 +417,8 @@ ynh_backup_archive_exists() { # Make a backup in case of failed upgrade # +# [packagingv1] +# # usage: ynh_backup_before_upgrade # # Usage in a package script: @@ -465,6 +467,8 @@ ynh_backup_before_upgrade() { # Restore a previous backup if the upgrade process failed # +# [packagingv1] +# # usage: ynh_restore_upgradebackup # # Usage in a package script: diff --git a/helpers/fail2ban b/helpers/fail2ban index 648a90359..613dcc490 100644 --- a/helpers/fail2ban +++ b/helpers/fail2ban @@ -8,8 +8,6 @@ # | arg: -m, --max_retry= - Maximum number of retries allowed before banning IP address - default: 3 # | arg: -p, --ports= - Ports blocked for a banned IP address - default: http,https # -# ----------------------------------------------------------------------------- -# # usage 2: ynh_add_fail2ban_config --use_template # | arg: -t, --use_template - Use this helper in template mode # diff --git a/helpers/hardware b/helpers/hardware index 3ccf7ffe8..091f023f6 100644 --- a/helpers/hardware +++ b/helpers/hardware @@ -2,6 +2,8 @@ # Get the total or free amount of RAM+swap on the system # +# [packagingv1] +# # usage: ynh_get_ram [--free|--total] [--ignore_swap|--only_swap] # | arg: -f, --free - Count free RAM+swap # | arg: -t, --total - Count total RAM+swap @@ -63,6 +65,8 @@ ynh_get_ram() { # Return 0 or 1 depending if the system has a given amount of RAM+swap free or total # +# [packagingv1] +# # usage: ynh_require_ram --required=RAM [--free|--total] [--ignore_swap|--only_swap] # | arg: -r, --required= - The amount to require, in MB # | arg: -f, --free - Count free RAM+swap diff --git a/helpers/mysql b/helpers/mysql index a5290f794..c11f7989a 100644 --- a/helpers/mysql +++ b/helpers/mysql @@ -152,6 +152,8 @@ ynh_mysql_create_user() { # Check if a mysql user exists # +# [internal] +# # usage: ynh_mysql_user_exists --user=user # | arg: -u, --user= - the user for which to check existence # | ret: 0 if the user exists, 1 otherwise. @@ -186,6 +188,8 @@ ynh_mysql_drop_user() { # Create a database, an user and its password. Then store the password in the app's config # +# [packagingv1] +# # 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 @@ -216,6 +220,8 @@ ynh_mysql_setup_db() { # Remove a database if it exists, and the associated user # +# [packagingv1] +# # usage: ynh_mysql_remove_db --db_user=user --db_name=name # | arg: -u, --db_user= - Owner of the database # | arg: -n, --db_name= - Name of the database diff --git a/helpers/network b/helpers/network index d6c15060a..bed9dd402 100644 --- a/helpers/network +++ b/helpers/network @@ -2,6 +2,8 @@ # Find a free port and return it # +# [packagingv1] +# # usage: ynh_find_port --port=begin_port # | arg: -p, --port= - port to start to search # | ret: the port number @@ -26,6 +28,8 @@ ynh_find_port() { # Test if a port is available # +# [packagingv1] +# # usage: ynh_find_port --port=XYZ # | arg: -p, --port= - port to check # | ret: 0 if the port is available, 1 if it is already used by another process. diff --git a/helpers/permission b/helpers/permission index 6c2fa7ef8..d3eb71c22 100644 --- a/helpers/permission +++ b/helpers/permission @@ -36,6 +36,8 @@ # | arg: -t, --show_tile= - (optional) Define if a tile will be shown in the SSO. If yes the name of the tile will be the 'label' parameter. Defaults to false for the permission different than 'main'. # | arg: -P, --protected= - (optional) Define if this permission is protected. If it is protected the administrator won't be able to add or remove the visitors group of this permission. Defaults to 'false'. # +# [packagingv1] +# # If provided, 'url' or 'additional_urls' is assumed to be relative to the app domain/path if they # start with '/'. For example: # / -> domain.tld/app @@ -143,6 +145,8 @@ ynh_permission_create() { # Remove a permission for the app (note that when the app is removed all permission is automatically removed) # +# [packagingv1] +# # example: ynh_permission_delete --permission=editors # # usage: ynh_permission_delete --permission="permission" @@ -161,6 +165,8 @@ ynh_permission_delete() { # Check if a permission exists # +# [packagingv1] +# # usage: ynh_permission_exists --permission=permission # | arg: -p, --permission= - the permission to check # | exit: Return 1 if the permission doesn't exist, 0 otherwise @@ -179,6 +185,8 @@ ynh_permission_exists() { # Redefine the url associated to a permission # +# [packagingv1] +# # usage: ynh_permission_url --permission "permission" [--url="url"] [--add_url="new-url" [ "other-new-url" ]] [--remove_url="old-url" [ "other-old-url" ]] # [--auth_header=true|false] [--clear_urls] # | arg: -p, --permission= - the name for the permission (by default a permission named "main" is removed automatically when the app is removed) @@ -247,6 +255,8 @@ ynh_permission_url() { # Update a permission for the app # +# [packagingv1] +# # usage: ynh_permission_update --permission "permission" [--add="group" ["group" ...]] [--remove="group" ["group" ...]] # [--label="label"] [--show_tile=true|false] [--protected=true|false] # | arg: -p, --permission= - the name for the permission (by default a permission named "main" already exist) @@ -352,6 +362,8 @@ ynh_permission_has_user() { # Check if a legacy permissions exist # +# [packagingv1] +# # usage: ynh_legacy_permissions_exists # | exit: Return 1 if the permission doesn't exist, 0 otherwise # @@ -367,6 +379,8 @@ ynh_legacy_permissions_exists() { # Remove all legacy permissions # +# [packagingv1] +# # usage: ynh_legacy_permissions_delete_all # # example: diff --git a/helpers/postgresql b/helpers/postgresql index 796a36214..35b95cd5f 100644 --- a/helpers/postgresql +++ b/helpers/postgresql @@ -160,6 +160,8 @@ ynh_psql_create_user() { # Check if a psql user exists # +# [packagingv1] +# # usage: ynh_psql_user_exists --user=user # | arg: -u, --user= - the user for which to check existence # | exit: Return 1 if the user doesn't exist, 0 otherwise @@ -222,6 +224,8 @@ ynh_psql_drop_user() { # Create a database, an user and its password. Then store the password in the app's config # +# [packagingv1] +# # usage: ynh_psql_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 @@ -257,6 +261,8 @@ ynh_psql_setup_db() { # Remove a database if it exists, and the associated user # +# [packagingv1] +# # usage: ynh_psql_remove_db --db_user=user --db_name=name # | arg: -u, --db_user= - Owner of the database # | arg: -n, --db_name= - Name of the database diff --git a/helpers/setting b/helpers/setting index a2cf3a93d..82a5d274e 100644 --- a/helpers/setting +++ b/helpers/setting @@ -113,6 +113,8 @@ EOF # Check availability of a web path # +# [packagingv1] +# # usage: ynh_webpath_available --domain=domain --path_url=path # | arg: -d, --domain= - the domain/host of the url # | arg: -p, --path_url= - the web path to check the availability of @@ -134,6 +136,8 @@ ynh_webpath_available() { # Register/book a web path for an app # +# [packagingv1] +# # usage: ynh_webpath_register --app=app --domain=domain --path_url=path # | arg: -a, --app= - the app for which the domain should be registered # | arg: -d, --domain= - the domain/host of the web path diff --git a/helpers/string b/helpers/string index dc1658e3d..b674d9a4a 100644 --- a/helpers/string +++ b/helpers/string @@ -91,6 +91,8 @@ ynh_replace_special_string() { # Sanitize a string intended to be the name of a database # +# [packagingv1] +# # usage: ynh_sanitize_dbid --db_name=name # | arg: -n, --db_name= - name to correct/sanitize # | ret: the corrected name diff --git a/helpers/user b/helpers/user index f5f3ec7bd..e608a3308 100644 --- a/helpers/user +++ b/helpers/user @@ -56,6 +56,8 @@ ynh_user_list() { # Check if a user exists on the system # +# [packagingv1] +# # usage: ynh_system_user_exists --username=username # | arg: -u, --username= - the username to check # | ret: 0 if the user exists, 1 otherwise. @@ -74,6 +76,8 @@ ynh_system_user_exists() { # Check if a group exists on the system # +# [packagingv1] +# # usage: ynh_system_group_exists --group=group # | arg: -g, --group= - the group to check # | ret: 0 if the group exists, 1 otherwise. @@ -92,6 +96,8 @@ ynh_system_group_exists() { # Create a system user # +# [packagingv1] +# # usage: ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell] [--groups="group1 group2"] # | 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 @@ -146,6 +152,8 @@ ynh_system_user_create() { # Delete a system user # +# [packagingv1] +# # usage: ynh_system_user_delete --username=user_name # | arg: -u, --username= - Name of the system user that will be create # diff --git a/helpers/utils b/helpers/utils index 34de8f0bc..3d179df1d 100644 --- a/helpers/utils +++ b/helpers/utils @@ -51,6 +51,8 @@ ynh_exit_properly() { # Exits if an error occurs during the execution of the script. # +# [packagingv1] +# # usage: ynh_abort_if_errors # # This configure the rest of the script execution such that, if an error occurs @@ -832,6 +834,8 @@ ynh_render_template() { # Fetch the Debian release codename # +# [packagingv1] +# # usage: ynh_get_debian_release # | ret: The Debian release codename (i.e. jessie, stretch, ...) # @@ -964,6 +968,8 @@ ynh_app_upstream_version() { # Read package version from the manifest # +# [internal] +# # usage: ynh_app_package_version [--manifest="manifest.json"] # | arg: -m, --manifest= - Path of the manifest to read # | ret: the version number of the package