Se entadarizar documentación se utiliza reStructuredText

Author: nbcontreras

fabfile.py

@@ -26,17 +26,26 @@ def get_connection(
     config: dict | None = None
 ) -> Connection | DockerRunner | Context:
     """
-    Return a connection object based on environment variables or config.
+    Resolve the appropriate connection object for the site.
 
-    Priority:
-    1. Environment variables: DEPLOYER_HOST, USER, PORT
-    2. Docker runner if configured.
-    3. Host/port from config.
-    4. Fallback connection or local.
+    Selects the correct runner based on environment variables,
+    Docker settings, or host definitions. Priority order:
 
-    :param fallback_connection: Local context or default connection
-    :param config: Optional site configuration dictionary
-    :return: Fabric Connection, DockerRunner, or Context
+    1. Environment variables: ``DEPLOYER_HOST``, ``DEPLOYER_USER``,
+    ``DEPLOYER_PORT``
+    2. Docker runner (if ``runner: docker`` is set in config)
+    3. SSH host/port defined in config
+    4. Fallback connection
+    5. Default to local context
+
+    :param fallback_connection: Default local or remote runner.
+    :type fallback_connection: Union[Connection, DockerRunner, Context]
+
+    :param config: Optional site config loaded from YAML.
+    :type config: dict or None
+
+    :return: A connection object suitable for deployment.
+    :rtype: Union[Connection, DockerRunner, Context]
     """
     # 1. If environment variable is set, override all
     host = os.getenv("DEPLOYER_HOST")
@@ -82,8 +91,14 @@ def deploy(c: Connection | DockerRunner | Context, site: str) -> None:
     """
     Deploy a single site defined in the configuration file.
 
-    :param c: Fabric connection object.
-    :param site: Name of the site defined in sites.yml.
+    Loads site-specific configuration, resolves the proper connection
+    (local, Docker, or SSH), and runs the full deployment process.
+
+    :param c: Fabric connection or context object.
+    :type c: Union[Connection, DockerRunner, Context]
+
+    :param site: Name of the site as defined in ``sites.yml``.
+    :type site: str
     """
     # Load all site definitions from the YAML config
     sites = load_sites()
@@ -108,9 +123,13 @@ def deploy(c: Connection | DockerRunner | Context, site: str) -> None:
 @task
 def deploy_all(c: Connection | DockerRunner | Context) -> None:
     """
-    Deploy all sites listed in sites.yml.
+    Deploy all sites listed in the configuration file.
+
+    Iterates through all entries in ``sites.yml`` and runs the
+    deployment pipeline for each one sequentially.
 
-    :param c: Fabric connection object.
+    :param c: Fabric connection or context object.
+    :type c: Union[Connection, DockerRunner, Context]
     """
     # Load all site definitions
     sites = load_sites()
@@ -127,20 +146,29 @@ def deploy_all(c: Connection | DockerRunner | Context) -> None:
 @task
 def list_sites(c: Connection | DockerRunner | Context) -> None:
     """
-    Display all available site configurations.
+    Display all configured sites and their repository URLs.
+
+    Loads site data from ``sites.yml`` and prints the site name
+    alongside its associated Git repository.
 
-    :param c: Fabric connection object.
+    :param c: Fabric connection or context object.
+    :type c: Union[Connection, DockerRunner, Context]
     """
     # Print table of available site names
     print_site_list()
 
 @task(help={"site": "Name of the site to rollback"})
 def rollback(c: Connection | DockerRunner | Context, site: str) -> None:
     """
-    Rollback a site to its previous release.
+    Rollback a site to the previous release.
+
+    Identifies the most recent backup release and reverts to it.
+
+    :param c: Fabric connection or context object.
+    :type c: Union[Connection, DockerRunner, Context]
 
-    :param c: Fabric connection object.
     :param site: Name of the site to rollback.
+    :type site: str
     """
     # Initialize logger
     logger = get_logger(site)
@@ -166,9 +194,13 @@ def rollback(c: Connection | DockerRunner | Context, site: str) -> None:
 @task
 def rollback_all(c: Connection | DockerRunner | Context) -> None:
     """
-    Rollback all sites to their previous release.
+    Rollback all sites to their previous releases.
+
+    Iterates through all configured sites and performs a rollback
+    to their last known good deployment.
 
-    :param c: Fabric connection object.
+    :param c: Fabric connection or context object.
+    :type c: Union[Connection, DockerRunner, Context]
     """
     # Load all site configs
     sites = load_sites()
@@ -185,10 +217,16 @@ def rollback_all(c: Connection | DockerRunner | Context) -> None:
 @task(help={"site": "Name of the site to unlock"})
 def unlock(c: Connection | DockerRunner | Context, site: str) -> None:
     """
-    Remove the lock file for a specific site.
+    Force-remove the deployment lock for a specific site.
+
+    Useful when a previous deployment was interrupted and the
+    lock wasn't released.
+
+    :param c: Fabric connection or context object.
+    :type c: Union[Connection, DockerRunner, Context]
 
-    :param c: Fabric connection object.
     :param site: Name of the site to unlock.
+    :type site: str
     """
     # Initialize logger
     logger = get_logger(site)
@@ -214,9 +252,12 @@ def unlock(c: Connection | DockerRunner | Context, site: str) -> None:
 @task
 def unlock_all(c: Connection | DockerRunner | Context) -> None:
     """
-    Unlock all sites by removing their lock files.
+    Remove lock files for all sites defined in ``sites.yml``.
+
+    Useful when recovering from interrupted deploys or rollbacks.
 
-    :param c: Fabric connection object.
+    :param c: Fabric connection or context object.
+    :type c: Union[Connection, DockerRunner, Context]
     """
     # Load site configurations
     sites = load_sites()

fabricator/deploy.py

@@ -33,21 +33,42 @@
 
 def deploy_site(c: Connection | DockerRunner | Context, config: dict) -> None:
     """
-    Deploy a Python project using runner (local, docker, or ssh).
-
-    This function orchestrates the full deployment pipeline:
-    - Acquires a deployment lock to prevent concurrent deploys.
-    - Verifies remote directory structure.
-    - Creates a compressed backup of the current version.
-    - Clones the repository and creates a timestamped release folder.
-    - Updates the `current` symlink to the new release.
-    - Symlinks shared files and writable folders.
-    - Installs dependencies, runs migrations, collectstatic, restarts services.
-    - Performs automatic rollback in case of failure.
-    - Releases the lock regardless of success or failure.
-
-    :param c: Fabric connection or context object (local, ssh, or Docker).
-    :param config: Site configuration dictionary loaded from sites.yml.
+    Deploy a Python web project using local, Docker, or SSH context.
+
+    This function executes the full deployment pipeline for a Django or
+    Python-based project. It handles preparation, code updates, shared
+    resources, virtualenv management, database migrations, static files,
+    and service restarts. It also ensures safety through locking and
+    rollback mechanisms.
+
+    Deployment steps include:
+
+    1. Acquiring a lock to prevent concurrent deployments.
+    2. Verifying and preparing the remote directory structure.
+    3. Creating a compressed backup of the current version.
+    4. Cloning the repository into a new timestamped release folder.
+    5. Cleaning up old releases beyond `max_releases`.
+    6. Linking shared files and directories to the new release.
+    7. Setting permissions on writable directories.
+    8. Installing dependencies in a virtual environment.
+    9. Running Django database migrations.
+    10. Running Django `collectstatic`.
+    11. Updating the `current` symlink to point to the new release.
+    12. Restarting services like Gunicorn to apply changes.
+    13. Rolling back to the previous release if a failure occurs.
+    14. Releasing the deployment lock at the end.
+
+    :param c: The Fabric context or connection object. Can be a local
+            `Context`, remote `Connection`, or `DockerRunner`.
+    :type c: Union[Connection, DockerRunner, Context]
+
+    :param config: Dictionary with all deployment-related settings loaded
+                from `sites.yml`, including project name, paths, shared
+                files, and service settings.
+    :type config: dict
+
+    :raises DeployerException: If any step in the process fails.
+    :rtype: None
     """
     # Initialize logger for this site
     logger = get_logger(config['name'])

fabricator/exceptions/deployer_exceptions.py

@@ -8,9 +8,17 @@ def __init__(self, message, code = None, params = None):
         """
         Initialize the DeployerException.
 
-        :param message: The error message.
-        :param code: The error code.
-        :param params: The error parameters.
+        Stores the error message, optional code, and any additional
+        parameters passed for debugging or context.
+
+        :param message: Description of the error.
+        :type message: str
+
+        :param code: Optional error code.
+        :type code: int or str, optional
+
+        :param params: Optional error context or data.
+        :type params: dict or any, optional
         """
         self.message = message
         self.code = code
@@ -19,9 +27,12 @@ def __init__(self, message, code = None, params = None):
 
     def __str__(self):
         """
-        Return a string representation of the error.
+        Return a formatted string representation of the error.
+
+        If a code is provided, it is included in the output. Otherwise,
+        only the message is shown.
 
-        :return: A string representation of the error.
+        :return: A string representing the error.
         :rtype: str
         """
         if self.code is not None:

fabricator/logger.py

@@ -11,12 +11,21 @@
 
 def get_logger(name: str = "deploy") -> logging.Logger:
     """
-    Return a reusable logger configured to output to the console.
+    Get or create a reusable console-based logger by name.
 
-    Ensures that handlers are added only once to avoid duplicate logs.
+    This function returns a configured `logging.Logger` instance with
+    an attached console handler. It prevents duplication of handlers
+    if the logger is requested multiple times.
 
-    :param name: Name to identify the logger (e.g., the site name).
-    :return: Configured Logger instance.
+    The logger outputs messages in the format:
+    `[timestamp] [LEVEL] message`.
+
+    :param name: Name to identify the logger instance. Typically used
+                to separate logs by context or project.
+    :type name: str
+
+    :return: A configured `Logger` object ready for use.
+    :rtype: logging.Logger
     """
     logger = logging.getLogger(name)