improve(docs:) cleaning up docstrings and admonitions (#767)

Author: Guts

docs/guides/howto_behind_proxy.md

@@ -1,6 +1,6 @@
 # How to use behind a network proxy
 
-:::{info}
+:::{note}
 Only HTTP and HTTPS proxies are supported. No socks. Automatic values definition from PAC file available.
 :::
 

docs/guides/howto_check_qdt_binary_certificate.md

@@ -104,7 +104,7 @@ A security warning may appear for self-signed certificates; confirm by clicking
 
 ### Automate import with a PowerShell script
 
-:::{info}
+:::{important}
 This script is a sample and might not comply with your environment and/or IT policy. If you intend to use it in production, take time to review it before. If you improve or fix it, please share it.
 :::
 

docs/guides/howto_download_latest_qdt_exe.md

@@ -4,7 +4,7 @@ QDT comes with an upgrade command that check if a new version has been released
 
 Sometimes a system script fits better to usage, use-case or IT policy. We give below an example in PowerShell for Windows.
 
-:::{info}
+:::{important}
 This script is a sample and might not comply with your environment and/or IT policy. If you intend to use it in production, take time to review it before. If you improve or fix it, please share it.
 :::
 

docs/guides/howto_manage_private_git.md

@@ -27,7 +27,7 @@ flowchart LR
 
 To execute the intermediate git pull, the approach depends on the organization and GIS team habits. This can be done manually through the command-line, with a GUI like the excellent [GitHub Desktop](https://github.com/apps/desktop) or with a script. Below is an example PowerShell script for Windows.
 
-:::{info}
+:::{attention}
 This script is provided as a sample and may not fully comply with your environment or IT policies. Before implementing in production, take time to review and test it in your environment. If you make improvements or fixes, please share them.
 :::
 

docs/index.md

@@ -188,7 +188,6 @@ usage/settings
 ```{toctree}
 ---
 caption: Guides
-glob:
 maxdepth: 1
 ---
 guides/howto_download_latest_qdt_exe.md
@@ -201,7 +200,6 @@ guides/howto_publish_http
 guides/howto_qgis_get_plugin_id
 guides/howto_schedule_deployment
 guides/howto_windows_sign_executable
-guides/*
 ```
 
 ```{toctree}

qgis_deployment_toolbelt/jobs/job_profiles_synchronizer.py

@@ -1,7 +1,6 @@
 #! python3  # noqa: E265
 
-"""
-Synchronize profiles between downloaded (in QDT working folder) and installed
+"""Synchronize profiles between downloaded (in QDT working folder) and installed
     profiles (in QGIS profiles'folder).
 
 Author: Julien Moura (https://github.com/guts)
@@ -108,10 +107,10 @@ def compare_downloaded_with_installed_profiles(
         Returns:
             tuple[list[QdtProfile], list[QdtProfile], list[QdtProfile]]: a tuple with
             the following structure (
-                list of installed profiles which are outdated (lesser version number),
-                list of installed profiles with a different version (lesser or greater),
-                list of profiles with the same version number in downloaded/installed
-                )
+            list of installed profiles and outdated (lesser version number),
+            list of installed profiles with a different version (lesser or greater),
+            list of profiles with the same version number in downloaded/installed
+            )
         """
         li_profiles_outdated = []
         li_profiles_different = []

qgis_deployment_toolbelt/jobs/job_shortcuts.py

@@ -105,7 +105,7 @@ def __init__(self, options: dict) -> None:
         """Instantiate the class.
 
         :param dict options: profiles source (remote, can be a local network) and
-        destination (local).
+            destination (local).
         """
         super().__init__()
         self.options: dict = self.validate_options(options)

qgis_deployment_toolbelt/profiles/qgis_ini_handler.py

@@ -1,7 +1,6 @@
-#! python3  # noqa: E265
+#! python3
 
-"""
-Read and write QGIS configuration files.
+"""Read and write QGIS configuration files.
 
 Author: Julien Moura (https://github.com/guts)
 """
@@ -64,14 +63,14 @@ def __init__(
 
         Args:
             ini_filepath (Path): path to the QGIS3.ini configuration file
-            ini_type (Literal[ "profile_qgis3", \
-                "profile_qgis3customization", "plugin_metadata", \
-                None ], optional): type of ini file. None enables autodetection. \
-                Defaults to None.
-            strict (bool, optional): strict mode applied to ConfigParser. Defaults to \
+            ini_type (Literal['profile_qgis3', 'profile_qgis3customization',\
+                'plugin_metadata', None ], optional): type of ini file.\
+                None enables autodetection. Defaults to None.
+            strict (bool, optional): strict mode applied to ConfigParser. Defaults to
                 False.
-            enable_environment_variables_interpolation (bool, optional): if enabled, \
+            enable_environment_variables_interpolation (bool, optional): if enabled,
                 values matching environment variables are interepreted. Defaults to True.
+
         """
         if (
             ini_filepath is not None

qgis_deployment_toolbelt/utils/linux_utils.py

@@ -1,10 +1,8 @@
 #! python3  # noqa: E265
 
-"""
-Utilities specific for Linux.
+"""Utilities specific for Linux.
 
 Author: Julien Moura (https://github.com/guts)
-
 """
 
 # #############################################################################
@@ -98,7 +96,8 @@ def find_key_from_values(value_to_find: str) -> str | None:
 
 
 def get_environment_variable(envvar_name: str, scope: str = "user") -> str | None:
-    """Get environment variable from Linux profile file
+    """Get environment variable from Linux profile file.
+
     Args:
         envvar_name (str): environment variable name (= key) to retrieve
         scope (str, optional): environment variable scope. Must be "user" or "system",
@@ -134,7 +133,8 @@ def get_environment_variable(envvar_name: str, scope: str = "user") -> str | Non
 def set_environment_variable(
     envvar_name: str, envvar_value: str | bool | int, scope: str = "user"
 ) -> bool:
-    """Set environment variable in Linux profile file
+    """Set environment variable in Linux profile file.
+
     Args:
         envvar_name (str): environment variable name (= key) to set
         envvar_value (str): environment variable value to set
@@ -225,7 +225,8 @@ def set_environment_variable(
 def delete_environment_variable(
     envvar_name: str, scope: Literal["system", "user"] = "user"
 ) -> bool:
-    """Remove environment variable from Linux profile file
+    """Remove environment variable from Linux profile file.
+
     Args:
         envvar_name (str): environment variable name (= key) to remove
         scope (str, optional): environment variable scope. Must be "user" or "system",
@@ -316,7 +317,8 @@ def refresh_environment() -> bool:
 
 
 def get_profile_file(scope: Literal["system", "user"]) -> Path | None:
-    """Get Linux profile file depending on shell and scope
+    """Get Linux profile file depending on shell and scope.
+
     Args:
         scope (str, optional): environment variable scope. Must be "user" or "system",
             defaults to "user". Defaults to "user".

qgis_deployment_toolbelt/utils/user_groups.py

@@ -1,7 +1,6 @@
 #! python3  # noqa: E265
 
-"""
-Utilities to manage user security groups either on Linux and Windows.
+"""Utilities to manage user security groups either on Linux and Windows.
 
 Author: Julien Moura (https://github.com/guts)
 """
@@ -143,9 +142,9 @@ def get_user_local_groups(user_name: str | None = None) -> list[str]:
 def get_user_domain_groups(user_guid_or_name: str | None = None) -> list[str]:
     """Lists the domain groups to which the user belong.
 
-    On Linux and MacOS, it always return an empty list. TODO: implement it (probably
-        using pure LDAP).
-    On Windows, it relies on win32net (COM).
+    On Linux and MacOS, it always return an empty list. On Windows, it relies on win32net (COM).
+
+    TODO: implement it for Linux and MacOS (probably using pure LDAP).
 
     Args:
         user_guid_or_name (str | None, optional): name of user. If None, the current user name
@@ -272,9 +271,9 @@ def _is_computer_in_domain_win32() -> bool:
 def is_computer_attached_to_a_domain() -> bool:
     """Determine if the computer is attached to a domain or not.
 
-    On Linux and MacOS, it always return False.
-    On Windows, it tries to use wmi (Windows Management Instrumentation), Active
-        Directory (through pyad) or subprocessed powershell as final fallback.
+    On Linux and MacOS, it always return False. On Windows, it tries to use wmi
+        (Windows Management Instrumentation), Active Directory (through pyad) or
+        subprocessed powershell as final fallback.
 
     Raises:
         NotImplementedError: if operating system is not supported.