updated docsdtrings for pip and docker

modules/docker.py

@@ -25,6 +25,25 @@ except ImportError:
 
 @task
 def docker_ip():
+    """
+    Retrieves the IP address for the Docker database.
+
+    This method determines the appropriate IP address for the Docker-based
+    database.  If the host is set to 'local' in the configuration under
+    docker.database, it assumes the environment is OSX and uses docker-machine
+    to retrieve the IP. Otherwise, it returns the predefined host IP address
+    from the configuration.
+
+    Note:
+        - This method currently returns 'localhost' for 'local' configurations
+          instead of using docker-machine.
+        - For configurations with a specific IP (not 'local'), it directly
+          returns the configured IP address.
+
+    :returns: The IP address of the Docker database.
+    :rtype: str
+    """
+
     configuration = env.config
 
     # in the configuration file under docker,database, if host is set to local
@@ -77,15 +96,26 @@ def docker_run(cmd):
 @task
 def generate():
     """
-    generates and uploads the docker.yml configuration file based on the
+    Generates and uploads a docker.yml configuration file.
-    settings in the yml file for the current branch.
+
+    This method creates a docker.yml file based on settings specified in the
+    YAML file for the current branch. It dynamically sets up the Docker
+    container configuration for the branch in use. This includes service names,
+    container names, environment variables (such as user, password, and
+    database name), Docker image, and port settings. If additional volume
+    settings are specified, these are also included in the context.
 
     e.g. if we are using development.yml then it will check for the docker
     settings in there to find out what conf values we want to use when creating
     whatever docker containers we are usign for this branch
 
-    currently, only the development branch is using docker, but I might change
+    Note:
-    that in the future.
+        - Primarily used for development branch currently, but can be adapted
+          for others.
+        - In debug mode, additional logging and context printing are enabled.
+
+    :returns: None. The method generates a file and optionally logs the
+        process.
     """
 
     configuration = env.config
@@ -178,12 +208,26 @@ def generate():
 @task
 def create(container='database'):
     """
-    helper function to create a docker-based database container
+    Creates a Docker-based database container.
 
-    container - specifies the type of container being built
+    This function is responsible for setting up a Docker container,
+    specifically a database container by default. It generates a container
+    template based on the specified type and uses Docker Compose to bring up
+    the container.
 
-    NOTE:
+    :param container: Specifies the type of container to create, defaults to
-        "container" must have a corresponding value in configuration file
+                      'database'.  The container type should have corresponding
+                      settings in the configuration file.
+
+    :type container: str
+
+    Note:
+        - The configuration file must contain corresponding settings for the
+          specified container type under the 'docker' section.
+        - In debug mode, additional logging information about the build path
+          and Docker Compose command is provided.
+
+    :returns: None. The function primarily executes Docker Compose commands.
     """
     configuration = env.config
 
@@ -220,19 +264,38 @@ under "docker"
 
 @task
 def status():
+    """
+    Displays the status of all Docker containers.
+
+    This function runs the 'docker ps -a' command which lists all Docker
+    containers and their current status, including those that are stopped.
+
+    :returns: None. The output is displayed to the console.
+    """
     docker_run("docker ps -a")
 
 
 @task
 def start(create=False):
     """
-    this will start the docker container referenced by container_type
+    Starts a specific Docker container.
 
-    NOTE: you should have created it with the docker.create method above
+    This function starts the Docker container as specified in the
-    first!
+    configuration. If the container does not exist and 'create' is set to True,
+    the container will be created and started.
 
-    container_type - the type of container to start
+    :param create: Flag indicating whether to create the container if it does
-    create - craete if container has not yet been created
+                   not exist, defaults to False.
+
+    :type create: bool
+
+    Note:
+        - The container is identified by the 'container_name' attribute in the
+          'docker.database' section of the configuration.
+        - The container should be created first using the 'docker.create'
+          method, unless 'create' is True.
+
+    :returns: None. The container is started, but no value is returned.
     """
     if env.debug:
         logger = loggify("docker", 'create')
@@ -253,14 +316,25 @@ def start(create=False):
 @task
 def stop(remove=False):
     """
-    remove=False
+    Stops and optionally removes a specific Docker container.
-    this will start the docker container referenced by container_type
 
-    NOTE: you should have created it with the docker.create method above
+    This function stops the Docker container as specified in the configuration.
-    first!
+    If the 'remove' flag is set to True, the container will also be removed
+    after being stopped.
 
-    container_type - the type of container to start
+    :param remove: Flag indicating whether to remove the container after
-    create - craete if container has not yet been created
+                   stopping, defaults to False.
+    :type remove: bool
+
+    Note:
+        - The container is identified by the 'container_name' attribute in the
+          'docker.database' section of the configuration.
+
+        - The container should be created first using the 'docker.create'
+            method.
+
+    :returns: None. The container is stopped, and optionally removed, but no
+        value is returned.
     """
     configuration = env.config
     remove = booleanize(remove)
@@ -284,7 +358,31 @@ def stop(remove=False):
 @task
 def edit(param='help'):
     """
-    calls up mvim on the docker conf and build files
+    Opens Docker configuration and build files in MacVim for editing.
+
+    This function streamlines the process of editing Docker-related files by
+    opening them in MacVim, a macOS version of the Vim text editor. It can be
+    directed to open specific Docker configuration or build files based on the
+    provided parameter. If 'help' or an unrecognized key is supplied as the
+    parameter, the function lists all the available files for editing along
+    with their paths.
+
+    :param param: The key for the specific Docker file to edit. Providing
+                  'help' lists all available keys and their associated file
+                  paths.  Defaults to 'help'.
+
+    :type param: str
+
+    Note:
+        - The editable file paths are determined from the project's
+          configuration.
+        - This function is tailored for use in environments where MacVim is
+          available.
+        - File editing is facilitated by the 'maintenance_edit' function, which
+          integrates with MacVim.
+
+    :returns: None. The function either invokes MacVim for a specific file or
+        outputs information.
     """
 
     from .maintenance import edit as maintenance_edit

modules/pip.py

@@ -16,6 +16,23 @@ ERROR_BAD_PARAM = -2
 
 @task
 def setup_virtualenv(python3=True):
+    """
+    Sets up a virtual environment using virtualenvwrapper.
+
+    This method creates a new virtual environment with the specified Python
+    version. It uses the 'mkvirtualenv' command from virtualenvwrapper and can
+    optionally use Python 3.
+
+    :param python3: Specifies whether to use Python 3 for the virtual
+                    environment, defaults to True.
+
+    :type python3: bool
+
+    Note:
+        - The virtual environment's name is taken from
+            `configuration.virtualenv.name`.
+        - If `env.debug` is True, the method logs additional debug information.
+    """
     configuration = env.config
 
     if env.debug:
@@ -70,16 +87,30 @@ def setup_virtualenv(python3=True):
 @task
 def bootstrap_pip():
     """
-    bootstraps pip
+    Bootstraps pip in the current environment.
+
+    This method is a wrapper that calls the 'setup' method, intended for
+    setting up or bootstrapping pip in the current virtual environment.
+
+    Note:
+        - This method currently calls 'setup', which handles the installation
+          of packages via pip based on the requirements file.
     """
     # upgrade()
     setup()
 
 
 @task
-def upgrade():
+def update_pip():
     """
-    upgrade pip to latest version
+    Updates pip to the latest version.
+
+    This method updates pip, the Python package installer, to its latest
+    version within the current virtual environment.
+
+    Note:
+        - The method assumes it's running inside a virtual environment.
+        - If `env.debug` is True, it logs the upgrade command being executed.
     """
 
     # configuration = env.config
@@ -102,7 +133,15 @@ def upgrade():
 @task
 def setup():
     """
-    install all packages via pip
+    Installs all required packages via pip.
+
+    This method installs packages specified in a requirements file using pip.
+    The requirements file path is retrieved from
+    `configuration.virtualenv.requirements.filepath`.
+
+    Note:
+        - Assumes execution within a virtual environment.
+        - If `env.debug` is enabled, debug information is logged.
     """
     configuration = env.config