Ottomata has submitted this change and it was merged. Change subject: Add Sphinx function documentation for deploy module ......................................................................
Add Sphinx function documentation for deploy module This change adds basic Sphinx documentation to the deploy module. Change-Id: Ia8f04c8bc95ef521192e1ea9fa1a176b4bd58b8a --- M modules/deployment/files/modules/deploy.py 1 file changed, 152 insertions(+), 9 deletions(-) Approvals: Ottomata: Verified; Looks good to me, approved diff --git a/modules/deployment/files/modules/deploy.py b/modules/deployment/files/modules/deploy.py index 21ad4d1..d3ab312 100644 --- a/modules/deployment/files/modules/deploy.py +++ b/modules/deployment/files/modules/deploy.py @@ -12,6 +12,8 @@ def _get_redis_serv(): ''' Return a redis server object + + :rtype: A Redis object ''' deployment_config = __pillar__.get('deployment_config') deploy_redis = deployment_config['redis'] @@ -22,6 +24,16 @@ def _check_in(function, repo): + """ + Private function used for reporting that a function has started. + Writes to redis with basic status information. + + :param function: The function being reported on. + :type function: str + :param repo: The repository being acted on. + :type repo: str + :rtype: None + """ serv = _get_redis_serv() minion = __grains__.get('id') timestamp = time.time() @@ -39,6 +51,16 @@ def _map_args(repo, args): + """ + Maps a set of arguments to a predefined set of values. Currently only + __REPO__ is support and will be replaced with the repository name. + + :param repo: The repo name used for mapping. + :type repo: str + :param args: An array of arguments to map. + :type args: list + :rtype: list + """ arg_map = {'__REPO__': repo} mapped_args = [] for arg in args: @@ -47,6 +69,14 @@ def get_config(repo): + """ + Fetches the configuration for this repo from the pillars and returns + a hash with the munged configuration (with defaults and helper config). + + :param repo: The specific repo for which to return config data. + :type repo: str + :rtype: hash + """ deployment_config = __pillar__.get('deployment_config') config = __pillar__.get('repo_config') config = config[repo] @@ -90,6 +120,14 @@ def deployment_server_init(): + """ + Initializes a set of repositories on the deployment server. This + function will only run on the deployment server and will initialize + any repository defined in the pillar configuration. This function is + safe to call at any point. + + :rtype: int + """ ret_status = 0 serv = _get_redis_serv() is_deployment_server = __grains__.get('deployment_server') @@ -152,11 +190,20 @@ def sync_all(): ''' - Sync all repositories. If a repo doesn't exist on target, clone as well. + Sync all repositories for this minion. If a repo doesn't exist on target, + clone it as well. This function will ensure all repositories for the + minion are at the current tag as defined by the master and is + be safe to call at any point. - CLI Example:: + CLI Example (from the master): - salt -G 'cluster:appservers' deploy.sync_all + salt -G 'deployment_target:test' deploy.sync_all + + CLI Example (from a minion): + + salt-call deploy.sync_all + + :rtype: hash ''' repo_config = __pillar__.get('repo_config') deployment_target = __grains__.get('deployment_target') @@ -175,6 +222,23 @@ def _update_gitmodules(config, location, shadow=False): + """ + Finds all .gitmodules in a repository, changes all submodules within them + to point to the correct submodule on the deployment server, then runs + a submodule sync. This function is in support of recursive submodules. + + In the case we need to update a shadow reference repo, the .gitmodules + files will have their submodules point to the reference clone. + + :param config: The config hash for the repo (as pulled from get_config). + :type config: hash + :param location: The location on the filesystem to find the .gitmodules + files. + :type location: str + :param shadow: Defines whether or not this is a shadow reference repo. + :type shadow: bool + :rtype: int + """ gitmodules_list = __salt__['file.find'](location, name='.gitmodules') for gitmodules in gitmodules_list: gitmodules_dir = os.path.dirname(gitmodules) @@ -221,6 +285,21 @@ def _clone(config, location, tag, shadow=False): + """ + Perform a clone of a repo at a specified location, and + do a fetch and checkout of the repo to ensure it's at the + current deployment tag. + + :param config: Config hash as fetched from get_config + :type config: hash + :param location: The location on the filesystem to clone this repo. + :type location: str + :param tag: The tag to ensure this clone is checked out to. + :type tag: str + :param shadow: Whether or not this repo is a shadow reference. + :type shadow: bool + :rtype: int + """ if shadow: cmd = '/usr/bin/git clone --reference {0} {1}/.git {2}' cmd = cmd.format(config['location'], config['url'], location) @@ -243,9 +322,17 @@ ''' Call a fetch for the specified repo - CLI Example:: + CLI Example (from the master): - salt -G 'cluster:appservers' deploy.fetch 'slot0' + salt -G 'deployment_target:test' deploy.fetch 'test/testrepo' + + CLI Example (from the minion): + + salt-call deploy.fetch 'test/testrepo' + + :param repo: The repo on which to perform the fetch. + :type repo: str + :rtype: hash ''' config = get_config(repo) @@ -304,6 +391,16 @@ def _fetch_location(config, location, shadow=False): + """ + Fetch a repo at a specified location. Optionally define this repo as a + shadow repo. + + :param config: Config hash as fetched from get_config. + :type config: hash + :param location: The location on the filesystem to run the fetch. + :type location: str + :rtype: int + """ cmd = '/usr/bin/git fetch' status = __salt__['cmd.retcode'](cmd, location) if status != 0: @@ -331,6 +428,14 @@ def _get_tag(config): + """ + Fetch the current deploy file from the repo on the deployment server and + return the current tag associated with it. + + :param config: Config hash as fetched from get_config. + :type config: hash + :rtype: str + """ # Fetch the .deploy file from the server and get the current tag deployfile = config['url'] + '/.deploy' f = urllib.urlopen(deployfile) @@ -354,9 +459,21 @@ ''' Checkout the current deployment tag. Assumes a fetch has been run. - CLI Example:: + CLI Example (on master): - salt -G 'cluster:appservers' deploy.checkout 'slot0' + salt -G 'deployment_target:test' deploy.checkout 'test/testrepo' + + CLI Example (on minion): + + salt deploy.checkout 'test/testrepo' + + :param repo: The repo name to check out. + :type repo: str + :param reset: Whether or not to do a checkout and hard reset based + on if the repo is already at the defined tag on the + deployment server. + :type reset: bool + :rtype: hash ''' #TODO: replace the cmd.retcode calls with git module calls, # where appropriate @@ -385,6 +502,24 @@ def _checkout_location(config, location, tag, reset=False, shadow=False): + """ + Checkout a repo at the specified location to the specified tag. If reset + is true checkout the repo even if it is already at the tag defined on the + deployment server. Optionally specify if this is a shadow reference repo. + + :param config: Config hash as fetched from get_config. + :type config: hash + :param location: The location on the filesystem to run this checkout. + :type location: str + :param tag: The tag to checkout this location to. + :type tag: str + :param reset: Whether or not to checkout this repo if it is already at the + tag specified by the deployment server. + :type reset: bool + :param shadow: Whether or not this is a shadow reference repo. + :type shadow: bool + :rtype: int + """ for dependency in config['dependencies']: depstats.append(__salt__['deploy.checkout'](dependency, reset)) @@ -424,9 +559,17 @@ ''' Restart the service associated with this repo. - CLI Example:: + CLI Example (on the master): - salt -G 'cluster:appservers' deploy.restart 'slot0' + salt -G 'deployment_target:test' deploy.restart 'test/testrepo' + + CLI Example (on the minion): + + salt-call deploy.restart 'test/testrepo' + + :param repo: The repo name used to find the service to restart. + :type repo: str + :rtype: hash ''' config = get_config(repo) _check_in('deploy.restart', repo) -- To view, visit https://gerrit.wikimedia.org/r/112649 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: merged Gerrit-Change-Id: Ia8f04c8bc95ef521192e1ea9fa1a176b4bd58b8a Gerrit-PatchSet: 2 Gerrit-Project: operations/puppet Gerrit-Branch: production Gerrit-Owner: Ryan Lane <rl...@wikimedia.org> Gerrit-Reviewer: BryanDavis <bda...@wikimedia.org> Gerrit-Reviewer: Ori.livneh <o...@wikimedia.org> Gerrit-Reviewer: Ottomata <o...@wikimedia.org> Gerrit-Reviewer: jenkins-bot <> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits