From 42339d70dd3f96e1d1673d143a99293325878a03 Mon Sep 17 00:00:00 2001 From: Xabier de Zuazo Date: Wed, 7 Oct 2015 00:34:26 +0200 Subject: [PATCH] Document all the libraries --- .inch.yml | 26 ++++++++++ .yardopts | 5 ++ README.md | 1 + TODO.md | 2 +- libraries/config.rb | 77 ++++++++++++++++++++++++++++- libraries/cookbook_helpers.rb | 76 +++++++++++++++++++++++++++- test/unit/support/cookbook_stubs.rb | 50 +++++++++++++++++++ test/unit/support/matchers.rb | 5 ++ 8 files changed, 238 insertions(+), 4 deletions(-) create mode 100644 .inch.yml create mode 100644 .yardopts diff --git a/.inch.yml b/.inch.yml new file mode 100644 index 0000000..4852a2d --- /dev/null +++ b/.inch.yml @@ -0,0 +1,26 @@ +files: + included: + - Berksfile + - Gemfile + - Guardfile + - Rakefile + - attributes/*.rb + - definitions/*.rb + - libraries/*.rb + - providers/*.rb + - recipes/*.rb + - resources/*.rb + - templates/**/*.rb + - spec/**/*.rb + - test/**/*.rb + - metatada.rb + - Gemfile + - Rakefile + - Capfile + - Guardfile + - Podfile + - Thorfile + - Vagrantfile + - Berksfile + - Cheffile + - Vagabondfile diff --git a/.yardopts b/.yardopts new file mode 100644 index 0000000..d8b4fc2 --- /dev/null +++ b/.yardopts @@ -0,0 +1,5 @@ +--markup markdown +--no-private +'*/**/*.rb' +- +*.md diff --git a/README.md b/README.md index 586e3cd..7b9fd89 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ ownCloud Cookbook [![Code Climate](http://img.shields.io/codeclimate/github/zuazo/owncloud-cookbook.svg?style=flat)](https://codeclimate.com/github/zuazo/owncloud-cookbook) [![Build Status](http://img.shields.io/travis/zuazo/owncloud-cookbook.svg?style=flat)](https://travis-ci.org/zuazo/owncloud-cookbook) [![Coverage Status](http://img.shields.io/coveralls/zuazo/owncloud-cookbook.svg?style=flat)](https://coveralls.io/r/zuazo/owncloud-cookbook?branch=master) +[![Inline docs](http://inch-ci.org/github/zuazo/owncloud-cookbook.svg?branch=master&style=flat)](http://inch-ci.org/github/zuazo/owncloud-cookbook) [Chef](https://www.chef.io/) cookbook to install and configure [ownCloud](http://owncloud.org/), an open source personal cloud for data and file sync, share and view. diff --git a/TODO.md b/TODO.md index b2202fd..f24ce94 100644 --- a/TODO.md +++ b/TODO.md @@ -1,4 +1,4 @@ TODO ==== -* [ ] Document the libraries. +* [ ] ... diff --git a/libraries/config.rb b/libraries/config.rb index 8bda4fe..cc667f7 100644 --- a/libraries/config.rb +++ b/libraries/config.rb @@ -25,9 +25,24 @@ # `owncloud` cookbook internal classes. module OwncloudCookbook # Class to read and write ownCloud configuration file. + # + # @example + # config_file = '/var/www/owncloud/config/config.php' + # c = OwncloudCookbook::Config.new(config_file) + # c.merge(node['owncloud']['config']) + # c.write class Config attr_reader :options + # OwncloudCookbook::Config constructor. + # + # Reads the current configuration values. + # + # @param file [String] ownCloud PHP configuration file path. + # @example + # config_file = '/var/www/owncloud/config/config.php' + # OwncloudCookbook::Config.new(config_file) + # @api public def initialize(file) @file = file @options = {} @@ -37,15 +52,37 @@ def initialize(file) protected + # Returns the configuration options in PHP compatible JSON format as + # string. + # + # @return [String] The JSON string. + # @example + # @options = Hash.new + # @options['key'] = "valu'e" + # options_php_json #=> "{\"key\":\"valu\\'e\"}" + # @private def options_php_json @options.to_json.gsub('\\', '\\\\\\').gsub("'", "\\\\'") end + # Merge two option values. + # + # Makes an union on array values. + # + # It also mantains the original dbtype when sqlite3 driver is available. + # + # @param key [String] configuration key name. + # @param value1 [Mixed] the original value. + # @param value2 [Mixed] the new value. + # @return [Mixed] the configuration values merged. + # @example + # merge_value('key', 'A', 'B') #=> "B" + # merge_value('array', %w(1 2), %w(2 3)) #=> ["1", "2", "3"] + # merge_value('dbtype', 'sqlite3', 'sqlite') #=> "sqlite3" + # @private def merge_value(key, value1, value2) - # make an union on array values if value1.is_a?(Array) && value2.is_a?(Array) value1 | value2 - # exotic case: mantain original dbtype when sqlite3 driver is available elsif key == 'dbtype' && value1 == 'sqlite3' && value2 == 'sqlite' value1 else @@ -55,10 +92,32 @@ def merge_value(key, value1, value2) public + # Gets an option value. + # + # @param index [Mixed] option name. + # @return [Mixed] option value. + # @example + # config_file = '/var/www/owncloud/config/config.php' + # c = OwncloudCookbook::Config.new(config_file) + # c['dbtype'] #=> 'mysql' + # @api public def [](index) @options[index] end + # Merges new configuration options with the current values. + # + # Saves the merged configuration values internally in an accumulator + # variable but not on disk. + # + # @param new_options [Hash] New configuration values. + # @return [Hash] Merged configuration values. + # @example + # config_file = '/var/www/owncloud/config/config.php' + # c = OwncloudCookbook::Config.new(config_file) + # c.merge(node['owncloud']['config']) + # #=> {"dbtype"=>"mysql", "dbname"=>"owncloud", ...} + # @api public def merge(new_options) return unless new_options.respond_to?(:to_hash) new_options = new_options.to_hash @@ -68,6 +127,17 @@ def merge(new_options) @options.merge!(new_options) { |k, v1, v2| merge_value(k, v1, v2) } end + # Reads the current configuration values from disk. + # + # Saves the read configuration values internally in an accumulator + # variable. + # + # @return [Hash] Configuration values. + # @example + # config_file = '/var/www/owncloud/config/config.php' + # c = OwncloudCookbook::Config.new(config_file) + # c.read #=> {"dbtype"=>"mysql", "dbname"=>"owncloud", ...} + # @api public def read return unless ::File.exist?(@file) f = IO.popen('php', 'r+') @@ -81,6 +151,9 @@ def read raise "Error reading ownCloud configuration: #{e.message}" end + # Writes the accumulated configuration values to disk. + # + # @return void def write return if @options == @original_options f = IO.popen('php', 'r+') diff --git a/libraries/cookbook_helpers.rb b/libraries/cookbook_helpers.rb index de946d6..7e379c2 100644 --- a/libraries/cookbook_helpers.rb +++ b/libraries/cookbook_helpers.rb @@ -22,26 +22,68 @@ # `owncloud` cookbook internal classes. module OwncloudCookbook # Some helpers to use from `owncloud` cookbook recipes or resources. + # + # @example + # self.class.send(:include, OwncloudCookbook::CookbookHelpers) + # apply_owncloud_configuration module CookbookHelpers + # Gets the ownCloud configuration file full path. + # + # @return [String] configuration file path. + # @example + # owncloud_config_file #=> '/var/www/owncloud/config/config.php' + # @api public def owncloud_config_file ::File.join(node['owncloud']['dir'], 'config', 'config.php') end + # Returns the [OwncloudCookbook::Config] instance. + # + # @return [OwncloudCookbook::Config] configuration object. + # @example + # owncloud_config #=> # + # @api public def owncloud_config @owncloud_config ||= OwncloudCookbook::Config.new(owncloud_config_file) end + # Gets ownCloud default configuration values. + # + # @return [Hash] configuration values. + # @example + # owncloud_cookbook_config + # #=> {"dbtype"=>"mysql", "dbname"=>"owncloud", ...} + # @api public def owncloud_cookbook_config @owncloud_cookbook_config ||= node['owncloud']['config'].to_hash end + # Generates the ownCloud trusted domain list. + # + # Generates the domain list from the `node['owncloud']['server_name']` and + # the `node['owncloud']['server_aliases']` attribute values. + # + # @return [Array] domain list. + # @example + # owncloud_trusted_domains #=> ["owncloud.example.com"] + # @api public def owncloud_trusted_domains [ node['owncloud']['server_name'], node['owncloud']['server_aliases'] ].flatten end - # Add server name and server aliases to trusted_domains config option. + # Adds server name and server aliases to trusted_domains configuration + # option. + # + # Merges the generated owncloud trusted domains and the + # `node['owncloud']['config']['trusted_domains']` attribute values. + # + # @return [Array] domain list. + # @example + # calculate_trusted_domains + # #=> ["owncloud.example.com", "www.example.com"] + # @api public def calculate_trusted_domains unless owncloud_cookbook_config.key?('trusted_domains') owncloud_cookbook_config['trusted_domains'] = [] @@ -52,6 +94,12 @@ def calculate_trusted_domains end end + # Calculates the database host. + # + # @return [String] database host and port. + # @example + # calculate_dbhost #=> "db.example.com:3306" + # @api public def calculate_dbhost owncloud_cookbook_config['dbhost'] = [ @@ -59,6 +107,14 @@ def calculate_dbhost ].join(':') end + # Updates the disk configuration values from the new calculated values. + # + # Merges all the configuration values. + # + # @return void + # @example + # owncloud_config_update + # @api public def owncloud_config_update owncloud_config.merge(owncloud_cookbook_config) owncloud_config.write @@ -66,6 +122,13 @@ def owncloud_config_update end # Store important options that where generated automatically by the setup. + # + # Saves them in Chef Node attributes. + # + # @return void + # @example + # save_owncloud_node_configuration + # @api public def save_owncloud_node_configuration return if Chef::Config[:solo] %w(passwordsalt instanceid).each do |value| @@ -73,6 +136,17 @@ def save_owncloud_node_configuration end end + # Calculates new configuration options, merged them and save them on disk. + # + # - Calculates trusted domains. + # - Calculates database host. + # - Updates ownCloud configuration options on disk. + # - Saves some generated options in Chef Node attributes. + # + # @return void + # @example + # apply_owncloud_configuration + # @api public def apply_owncloud_configuration calculate_trusted_domains calculate_dbhost diff --git a/test/unit/support/cookbook_stubs.rb b/test/unit/support/cookbook_stubs.rb index e9e1af7..e907ec3 100644 --- a/test/unit/support/cookbook_stubs.rb +++ b/test/unit/support/cookbook_stubs.rb @@ -18,12 +18,32 @@ # if defined?(ChefSpec) + # ChefSpec stubs for `apache2` cookbook. + # + # @return void + # @example + # describe 'mycookbook::default' do + # let(:chef_runner) { ChefSpec::SoloRunner.new } + # let(:chef_run) { chef_runner.converge(described_recipe) } + # before { stub_apache2_cookbook } + # # [...] + # end def stub_apache2_cookbook stub_command('/usr/sbin/apache2 -t').and_return(true) stub_command('/usr/sbin/httpd -t').and_return(true) stub_command('which php').and_return(true) end + # ChefSpec stubs for `php-fpm` cookbook. + # + # @return void + # @example + # describe 'mycookbook::default' do + # let(:chef_runner) { ChefSpec::SoloRunner.new } + # let(:chef_run) { chef_runner.converge(described_recipe) } + # before { stub_php_fpm_cookbook } + # # [...] + # end def stub_php_fpm_cookbook stub_command( 'test -d /etc/php5/fpm/pool.d || mkdir -p /etc/php5/fpm/pool.d' @@ -32,12 +52,32 @@ def stub_php_fpm_cookbook .and_return(true) end + # ChefSpec stubs for `nginx` cookbook. + # + # @return void + # @example + # describe 'mycookbook::default' do + # let(:chef_runner) { ChefSpec::SoloRunner.new } + # let(:chef_run) { chef_runner.converge(described_recipe) } + # before { stub_nginx_cookbook } + # # [...] + # end def stub_nginx_cookbook stub_php_fpm_cookbook stub_command('which nginx').and_return(true) allow(::File).to receive(:symlink?).and_call_original end + # ChefSpec stubs for `postgresql` cookbook. + # + # @return void + # @example + # describe 'mycookbook::default' do + # let(:chef_runner) { ChefSpec::SoloRunner.new } + # let(:chef_run) { chef_runner.converge(described_recipe) } + # before { stub_postgresql_cookbook } + # # [...] + # end def stub_postgresql_cookbook stub_command( "psql -c 'SELECT lanname FROM pg_catalog.pg_language' #{db_name} "\ @@ -50,6 +90,16 @@ def stub_postgresql_cookbook .and_return(true) end + # ChefSpec stubs for `postfix` cookbook. + # + # @return void + # @example + # describe 'mycookbook::default' do + # let(:chef_runner) { ChefSpec::SoloRunner.new } + # let(:chef_run) { chef_runner.converge(described_recipe) } + # before { stub_postfix_cookbook } + # # [...] + # end def stub_postfix_cookbook stub_command( '/usr/bin/test /etc/alternatives/mta -ef /usr/sbin/sendmail.postfix' diff --git a/test/unit/support/matchers.rb b/test/unit/support/matchers.rb index bda9150..de037a7 100644 --- a/test/unit/support/matchers.rb +++ b/test/unit/support/matchers.rb @@ -18,6 +18,11 @@ # if defined?(ChefSpec) + # ChefSpec matcher for MySQL services `:start` action. + # + # @return void + # @example + # expect(chef_run).to start_mysql_service('default') def start_mysql_service(resource_name) ChefSpec::Matchers::ResourceMatcher.new( :mysql_service, :start, resource_name