Add documentation and README.md

README.md

@@ -0,0 +1,61 @@
+# MDT - Versioned module
+
+A module that implements versioned releases deployment flow for MDT.
+
+## Requirements
+
+* [mdt-core](https://github.com/Phitherek/mdt-core "mdt-core") >= 0.1.0
+* Ruby (tested with 2.5.0, earlier versions down to 2.0 may also work)
+* RubyGems
+
+## Installation
+
+`gem install mdt-versioned`
+
+## Usage
+
+The module is automatically loaded by `mdt`. All you need to do is to use appropriate keys in your `mdt-deploy.yml`.
+
+## Objects defined by module
+
+NOTE: All of the options are optional unless indicated otherwise.
+
+### Commands
+
+* `versioned.link_current` - creates a symlink to the current release version.
+Options:
+    * `current_name` - name of the link to the current release version, "current" by default.
+* `versioned.link_shared` - creates symlinks to the contents of the shared directory inside the current release directory.
+Options:
+    * `shared_name` - name of the shared directory, "shared" by default.
+* `versioned.cleanup` - deletes old releases. Options:
+    * `retained_versions_count` - number of releases to retain including current release, 2 by default.
+
+### Directory choosers
+
+* `versioned.integer` - uses versioned subdirectories based on increasing integer (1, 2, etc.). Creates and changes to the directory. Removes the directory on failure.
+Options:
+    * `path` - path of the base deployment directory. Required.
+    * `releases_dirname` - name of the directory that contains versioned release directories, "releases" by default.
+* `versioned.timestamp` - uses versioned subdirectories based on the formatted date and time.  Creates and changes to the directory. Removes the directory on failure.
+Options:
+    * `path` - path of the base deployment directory. Required.
+    * `releases_dirname` - name of the directory that contains versioned release directories, "releases" by default.
+    * `timestamp_format` - format of the timestamp as required by Ruby Time.strftime method, "%Y%m%d%H%M%S" by default.
+
+Both of the directory choosers set the following data in the MDT::DataStorage object:
+* `versioned_base_path` - path of the base deployment directory.
+* `versioned_version_id` - current version identifier.
+* `versioned_releases_dirname` - name of the directory that contains versioned release directories.
+
+## Data storage notice
+
+All of the data in the MDT::DataStorage object set by the directory choosers has to be set for this module's commands to work properly.
+
+## Contributing
+
+You can contribute to the development of this MDT module by submitting an issue or pull request.
+
+## Documentation
+
+Generated RDoc documentation can be found [here](https://rubydoc.info/github/Phitherek/mdt-versioned "here").

lib/mdt/commands/versioned.rb

@@ -1,16 +1,33 @@
 require 'mdt-core'
 require 'fileutils'
 module MDT
+  # A module containing all commands
   module Commands
+    # A class that implements commands for versioned releases flow
     class Versioned < MDT::Commands::Base
+      # A method that defines a key for commands class.
+      # Returns:
+      # * "versioned"
       def self.key
         'versioned'
       end
 
+      # A method that defines keys for available commands.
+      # Returns:
+      # * +["link_current", "link_shared", "cleanup"]+
       def self.subkeys
         ['link_current', 'link_shared', 'cleanup']
       end
 
+      # A method that defines how to execute a command and how to apply command modifiers.
+      # Arguments:
+      # * +key+ - a key identifier of a particular command
+      # * +modifiers+ - an array of command modifier configurations - each configuration is a Hash that includes modifier type and modifier options
+      # * +options+ - options for command as a Hash
+      # Returns:
+      # * Exit code of command +key+
+      # More information:
+      # * See README.md for detailed description of commands
       def execute(key, modifiers = [], options = {})
         case key
         when 'link_current'

lib/mdt/directory_choosers/versioned.rb

@@ -1,16 +1,32 @@
 require 'mdt-core'
 require 'fileutils'
 module MDT
+  # A module containing all directory choosers
   module DirectoryChoosers
+    # A class that implements directory choosers for versioned releases flow
     class Versioned < MDT::DirectoryChoosers::Base
+      # A method that defines a key for command modifiers class.
+      # Returns:
+      # * "versioned"
       def self.key
         'versioned'
       end
 
+      # A method that defines keys for available command modifiers.
+      # Returns:
+      # * +["timestamp", "integer"]+
       def self.subkeys
         ['timestamp', 'integer']
       end
 
+      # A method that defines how to create a deploy directory with directory choosers.
+      # Arguments:
+      # * +key+ - a key identifier of a particular directory chooser
+      # * +options+ - options for directory chooser as a Hash
+      # Returns:
+      # * Exit code for directory chooser +key+
+      # More information:
+      # * See README.md for detailed description of directory choosers
       def mkdir(key, options = {})
         return 1 unless options['path']
         options['releases_dirname'] ||= 'releases'
@@ -25,19 +41,15 @@ def mkdir(key, options = {})
             FileUtils.mkdir_p("#{MDT::DataStorage.instance.versioned_base_path}/#{MDT::DataStorage.instance.versioned_releases_dirname}/#{MDT::DataStorage.instance.versioned_version_id}")
             0
           rescue => e
-            puts e.to_s
-            puts e.backtrace
             1
           end
         when 'integer'
           begin
             if Dir.exist?("#{options['path']}/#{options['releases_dirname']}")
-              puts 'exists'
               previous_versions = []
               Dir["#{options['path']}/#{options['releases_dirname']}/*"].each do |vd|
                 previous_versions << vd.split('/').last
               end
-              puts previous_versions
               previous_versions.sort!
               MDT::DataStorage.instance.versioned_version_id = (previous_versions.last.to_i + 1).to_s
             else
@@ -49,13 +61,19 @@ def mkdir(key, options = {})
             FileUtils.mkdir_p("#{MDT::DataStorage.instance.versioned_base_path}/#{MDT::DataStorage.instance.versioned_releases_dirname}/#{MDT::DataStorage.instance.versioned_version_id}")
             0
           rescue => e
-            puts e.to_s
-            puts e.backtrace
             1
           end
         end
       end
 
+      # A method that defines how to change working directory to a deploy directory with directory choosers.
+      # Arguments:
+      # * +key+ - a key identifier of a particular directory chooser
+      # * +options+ - options for directory chooser as a Hash
+      # Returns:
+      # * Exit code for directory chooser +key+
+      # More information:
+      # * See README.md for detailed description of directory choosers
       def cd(key, options = {})
         return 1 unless self.class.subkeys.include?(key)
         begin
@@ -67,6 +85,14 @@ def cd(key, options = {})
         end
       end
 
+      # A method that defines how to remove a deploy directory with directory choosers.
+      # Arguments:
+      # * +key+ - a key identifier of a particular directory chooser
+      # * +options+ - options for directory chooser as a Hash
+      # Returns:
+      # * Exit code for directory chooser +key+
+      # More information:
+      # * See README.md for detailed description of directory choosers
       def rm(key, options = {})
         return 1 unless self.class.subkeys.include?(key)
         begin