From accd7d1a58d5d9811c1096bb5bda7ff3dc0cbff3 Mon Sep 17 00:00:00 2001 From: Henne Vogelsang Date: Tue, 8 Apr 2014 21:02:10 +0200 Subject: [PATCH] Starting to document things with rdoc --- .gitignore | 1 + Gemfile | 1 + Gemfile.lock | 9 ++ README.md | 95 +++--------- README.rdoc | 261 --------------------------------- app/helpers/home_helper.rb | 34 +++++ app/models/conference.rb | 65 ++++---- app/views/home/index.html.haml | 2 +- 8 files changed, 108 insertions(+), 360 deletions(-) delete mode 100644 README.rdoc create mode 100644 app/helpers/home_helper.rb diff --git a/.gitignore b/.gitignore index 6403fac1..7705eabb 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,4 @@ pickle-email-*.html *~ /public/assets /bundle +/doc/app diff --git a/Gemfile b/Gemfile index 7c86ee22..ebac87dd 100644 --- a/Gemfile +++ b/Gemfile @@ -23,6 +23,7 @@ group :development, :test do gem 'letter_opener' gem 'rspec-rails', '~> 3.0.0.beta' gem 'capybara', '1.1.2' + gem 'rdoc-generator-fivefish' end group :production do diff --git a/Gemfile.lock b/Gemfile.lock index a7c1b234..f6e27b37 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -91,6 +91,8 @@ GEM hike (1.2.3) htmlentities (4.3.1) i18n (0.6.9) + inversion (0.12.3) + loggability (~> 0.4) journey (1.0.4) jquery-fileupload-rails (0.4.1) actionpack (>= 3.1) @@ -106,6 +108,7 @@ GEM letter_opener (1.2.0) launchy (~> 2.2) libv8 (3.16.14.3) + loggability (0.10.1) mail (2.5.4) mime-types (~> 1.16) treetop (~> 1.4.8) @@ -162,6 +165,10 @@ GEM rake (10.1.1) rdoc (3.12.2) json (~> 1.4) + rdoc-generator-fivefish (0.0.1) + inversion (~> 0.10) + rdoc (~> 3.12) + yajl-ruby (~> 1.1) ref (1.0.5) rspec-collection_matchers (0.0.3) rspec-expectations (>= 2.99.0.beta1) @@ -227,6 +234,7 @@ GEM will_paginate (3.0.5) xpath (0.1.4) nokogiri (~> 1.3) + yajl-ruby (1.2.0) PLATFORMS ruby @@ -256,6 +264,7 @@ DEPENDENCIES prawn_rails pry rails (= 3.2.17) + rdoc-generator-fivefish rspec-rails (~> 3.0.0.beta) sass-rails (>= 3.2) sqlite3 diff --git a/README.md b/README.md index 8b9945f1..5187addf 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,11 @@ #OSEM The Open Source Event Manager. An event management tool tailored to Free and Open Source Software conferences. -##Local Installation +## Install OSEM +You can run rails apps in different modes (development, production). For more information +about rails and what it can do, see the [rails guides.](http://guides.rubyonrails.org/getting_started.html) -### Install Ruby and Ruby on Rails: - -* Install Ruby v. 1.9.3, guide at https://gist.github.com/AstonJ/2896818 for CentOS. - Debian has Ruby v. 1.9.3 packaged into the Testing suite already. -* Install Apache + mod_passenger, an handy guide is available at: - http://nathanhoad.net/how-to-ruby-on-rails-ubuntu-apache-with-passenger - -### Install OSEM +### Run OSEM in development 1. Clone the git repository to the directory you want Apache to serve the content from. ``` git clone https://github.com/openSUSE/osem.git @@ -19,78 +14,34 @@ git clone https://github.com/openSUSE/osem.git ``` bundle install ``` -3. Install ImageMagick - -* Fedora/CentOS: - -``` -yum install ImageMagick -``` - -* Ubuntu/Debian: - -``` -apt-get install imagemagick -``` - -4. Copy the sample configuration files +3. Install ImageMagick from your distribution repository +4. Copy the sample configuration files and adapt them ``` cp config/config.yml.example config/config.yml cp config/database.yml.example config/database.yml ``` - -5. Setup directories and permissions: -``` -mkdir storage cache system -``` -* Fedora/CentOS -``` -chown apache storage cache system -``` -* Debian/Ubuntu -``` -chown www-data storage cache system -``` - 6. Setup the database ``` bundle exec rake db:setup -bundle exec rake db:migrate -bundle exec rake db:seed ``` - -7. Create a new Apache vhost that should look like this: +7. Run OSEM ``` - - ServerName osem.example.org - DocumentRoot /srv/http/osem.example.org/public - RailsEnv development - - - # This relaxes Apache security settings. - AllowOverride all - # MultiViews must be turned off. - Options -MultiViews - - +rails server ``` +8. Visit the APP at +``` +http://localhost:3000 +``` +9. Sign up, the first user will be automatically assigned the admin role. -7. Connect to osem.example.org and register your first user. Make also sure that Postfix is installed and configured on the system for the confirmation mail to pass through. +### Run OSEM in production +We recommend to run OSEM in production with [mod_passenger](https://www.phusionpassenger.com/download/#open_source) +and the [apache web-server](https://www.apache.org/). There are tons of guides on how to deploy rails apps on various +base operating systems. Check Google ;-) -8. Just sign up as a new user and you will be automatically assigned as admin role. - - - -Caveats -======= - -If you have problems with rails console, try this in the Gemfile: - -* gem uninstall rb-readline -* gem 'rb-readline', '~>0.4.2' - -If you have problems with jquery-ui, try this in the Gemfile: - -* gem "jquery-rails", "~> 2.3.0" - -Or make the needed change as explained at http://stackoverflow.com/questions/17830313/couldnt-find-file-jquery-ui. +## Documentation +OSEM is extensively (some would say maniacally ;-) documented. You can generate a nice HTML documentation with ''rdoc'' +``` +bundle exec rdoc --op doc/app --all -f fivefish app +xdg-open doc/app/index.html +``` diff --git a/README.rdoc b/README.rdoc deleted file mode 100644 index 7c36f235..00000000 --- a/README.rdoc +++ /dev/null @@ -1,261 +0,0 @@ -== Welcome to Rails - -Rails is a web-application framework that includes everything needed to create -database-backed web applications according to the Model-View-Control pattern. - -This pattern splits the view (also called the presentation) into "dumb" -templates that are primarily responsible for inserting pre-built data in between -HTML tags. The model contains the "smart" domain objects (such as Account, -Product, Person, Post) that holds all the business logic and knows how to -persist themselves to a database. The controller handles the incoming requests -(such as Save New Account, Update Product, Show Post) by manipulating the model -and directing data to the view. - -In Rails, the model is handled by what's called an object-relational mapping -layer entitled Active Record. This layer allows you to present the data from -database rows as objects and embellish these data objects with business logic -methods. You can read more about Active Record in -link:files/vendor/rails/activerecord/README.html. - -The controller and view are handled by the Action Pack, which handles both -layers by its two parts: Action View and Action Controller. These two layers -are bundled in a single package due to their heavy interdependence. This is -unlike the relationship between the Active Record and Action Pack that is much -more separate. Each of these packages can be used independently outside of -Rails. You can read more about Action Pack in -link:files/vendor/rails/actionpack/README.html. - - -== Getting Started - -1. At the command prompt, create a new Rails application: - rails new myapp (where myapp is the application name) - -2. Change directory to myapp and start the web server: - cd myapp; rails server (run with --help for options) - -3. Go to http://localhost:3000/ and you'll see: - "Welcome aboard: You're riding Ruby on Rails!" - -4. Follow the guidelines to start developing your application. You can find -the following resources handy: - -* The Getting Started Guide: http://guides.rubyonrails.org/getting_started.html -* Ruby on Rails Tutorial Book: http://www.railstutorial.org/ - - -== Debugging Rails - -Sometimes your application goes wrong. Fortunately there are a lot of tools that -will help you debug it and get it back on the rails. - -First area to check is the application log files. Have "tail -f" commands -running on the server.log and development.log. Rails will automatically display -debugging and runtime information to these files. Debugging info will also be -shown in the browser on requests from 127.0.0.1. - -You can also log your own messages directly into the log file from your code -using the Ruby logger class from inside your controllers. Example: - - class WeblogController < ActionController::Base - def destroy - @weblog = Weblog.find(params[:id]) - @weblog.destroy - logger.info("#{Time.now} Destroyed Weblog ID ##{@weblog.id}!") - end - end - -The result will be a message in your log file along the lines of: - - Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1! - -More information on how to use the logger is at http://www.ruby-doc.org/core/ - -Also, Ruby documentation can be found at http://www.ruby-lang.org/. There are -several books available online as well: - -* Programming Ruby: http://www.ruby-doc.org/docs/ProgrammingRuby/ (Pickaxe) -* Learn to Program: http://pine.fm/LearnToProgram/ (a beginners guide) - -These two books will bring you up to speed on the Ruby language and also on -programming in general. - - -== Debugger - -Debugger support is available through the debugger command when you start your -Mongrel or WEBrick server with --debugger. This means that you can break out of -execution at any point in the code, investigate and change the model, and then, -resume execution! You need to install ruby-debug to run the server in debugging -mode. With gems, use sudo gem install ruby-debug. Example: - - class WeblogController < ActionController::Base - def index - @posts = Post.all - debugger - end - end - -So the controller will accept the action, run the first line, then present you -with a IRB prompt in the server window. Here you can do things like: - - >> @posts.inspect - => "[#nil, "body"=>nil, "id"=>"1"}>, - #"Rails", "body"=>"Only ten..", "id"=>"2"}>]" - >> @posts.first.title = "hello from a debugger" - => "hello from a debugger" - -...and even better, you can examine how your runtime objects actually work: - - >> f = @posts.first - => #nil, "body"=>nil, "id"=>"1"}> - >> f. - Display all 152 possibilities? (y or n) - -Finally, when you're ready to resume execution, you can enter "cont". - - -== Console - -The console is a Ruby shell, which allows you to interact with your -application's domain model. Here you'll have all parts of the application -configured, just like it is when the application is running. You can inspect -domain models, change values, and save to the database. Starting the script -without arguments will launch it in the development environment. - -To start the console, run rails console from the application -directory. - -Options: - -* Passing the -s, --sandbox argument will rollback any modifications - made to the database. -* Passing an environment name as an argument will load the corresponding - environment. Example: rails console production. - -To reload your controllers and models after launching the console run -reload! - -More information about irb can be found at: -link:http://www.rubycentral.org/pickaxe/irb.html - - -== dbconsole - -You can go to the command line of your database directly through rails -dbconsole. You would be connected to the database with the credentials -defined in database.yml. Starting the script without arguments will connect you -to the development database. Passing an argument will connect you to a different -database, like rails dbconsole production. Currently works for MySQL, -PostgreSQL and SQLite 3. - -== Description of Contents - -The default directory structure of a generated Ruby on Rails application: - - |-- app - | |-- assets - | |-- images - | |-- javascripts - | `-- stylesheets - | |-- controllers - | |-- helpers - | |-- mailers - | |-- models - | `-- views - | `-- layouts - |-- config - | |-- environments - | |-- initializers - | `-- locales - |-- db - |-- doc - |-- lib - | `-- tasks - |-- log - |-- public - |-- script - |-- test - | |-- fixtures - | |-- functional - | |-- integration - | |-- performance - | `-- unit - |-- tmp - | |-- cache - | |-- pids - | |-- sessions - | `-- sockets - `-- vendor - |-- assets - `-- stylesheets - `-- plugins - -app - Holds all the code that's specific to this particular application. - -app/assets - Contains subdirectories for images, stylesheets, and JavaScript files. - -app/controllers - Holds controllers that should be named like weblogs_controller.rb for - automated URL mapping. All controllers should descend from - ApplicationController which itself descends from ActionController::Base. - -app/models - Holds models that should be named like post.rb. Models descend from - ActiveRecord::Base by default. - -app/views - Holds the template files for the view that should be named like - weblogs/index.html.erb for the WeblogsController#index action. All views use - eRuby syntax by default. - -app/views/layouts - Holds the template files for layouts to be used with views. This models the - common header/footer method of wrapping views. In your views, define a layout - using the layout :default and create a file named default.html.erb. - Inside default.html.erb, call <% yield %> to render the view using this - layout. - -app/helpers - Holds view helpers that should be named like weblogs_helper.rb. These are - generated for you automatically when using generators for controllers. - Helpers can be used to wrap functionality for your views into methods. - -config - Configuration files for the Rails environment, the routing map, the database, - and other dependencies. - -db - Contains the database schema in schema.rb. db/migrate contains all the - sequence of Migrations for your schema. - -doc - This directory is where your application documentation will be stored when - generated using rake doc:app - -lib - Application specific libraries. Basically, any kind of custom code that - doesn't belong under controllers, models, or helpers. This directory is in - the load path. - -public - The directory available for the web server. Also contains the dispatchers and the - default HTML files. This should be set as the DOCUMENT_ROOT of your web - server. - -script - Helper scripts for automation and generation. - -test - Unit and functional tests along with fixtures. When using the rails generate - command, template test files will be generated for you and placed in this - directory. - -vendor - External libraries that the application depends on. Also includes the plugins - subdirectory. If the app has frozen rails, those gems also go here, under - vendor/rails/. This directory is in the load path. diff --git a/app/helpers/home_helper.rb b/app/helpers/home_helper.rb new file mode 100644 index 00000000..659d7168 --- /dev/null +++ b/app/helpers/home_helper.rb @@ -0,0 +1,34 @@ +## +# This class contains helper for the home views. + +module HomeHelper + + ## + # Returns a string build from the start and end date of the given conference. + # + # If the conference starts and ends in the same month and year + # * %B %d - %d, %Y (January 17 - 21 2014) + # If the conference ends in another month but in the same year + # * %B %d - %B %d, %Y (January 31 - February 02 2014) + # All other cases + # * %B %d, %Y - %B %d, %Y (December 30, 2013 - January 02, 2014) + def conference_date_string(conf) + startstr = "Unknown - " + endstr = "Unknown" + # When the conference in the same motn + if conf.start_date.month == conf.end_date.month and conf.start_date.year == conf.end_date.year + startstr = conf.start_date.strftime("%B %d - ") + endstr = conf.end_date.strftime("%d, %Y") + elsif conf.start_date.month != conf.end_date.month && conf.start_date.year == conf.end_date.year + startstr = conf.start_date.strftime("%B %d - ") + endstr = conf.end_date.strftime("%B %d, %Y") + else + startstr = conf.start_date.strftime("%B %d, %Y - ") + endstr = conf.end_date.strftime("%B %d, %Y") + end + + result = startstr + endstr + result + end + +end diff --git a/app/models/conference.rb b/app/models/conference.rb index c72a6049..785068de 100644 --- a/app/models/conference.rb +++ b/app/models/conference.rb @@ -1,3 +1,6 @@ +## +# This class represents a conference + class Conference < ActiveRecord::Base attr_accessible :title, :short_title, :social_tag, :contact_email, :timezone, :html_export_path, :start_date, :end_date, :rooms_attributes, :tracks_attributes, :dietary_choices_attributes, @@ -61,41 +64,34 @@ class Conference < ActiveRecord::Base before_create :create_venue before_create :create_email_settings - def self.current - self.order("created_at DESC").first - end - - def date_range_string - startstr = "Unknown - " - endstr = "Unknown" - if start_date.month == end_date.month && start_date.year == end_date.year - startstr = start_date.strftime("%B %d - ") - endstr = end_date.strftime("%d, %Y") - elsif start_date.month != end_date.month && start_date.year == end_date.year - startstr = start_date.strftime("%B %d - ") - endstr = end_date.strftime("%B %d, %Y") - else - startstr = start_date.strftime("%B %d, %Y - ") - endstr = end_date.strftime("%B %d, %Y") - end - - result = startstr + endstr - result - end - + ## + # Checks if the user is registered to the conference + # + # ====Args + # * +user+ -> The user we check for + # ====Returns + # * +nil+ -> If the user doesn't exist + # * +false+ -> If the user is registered + # * +true+ - If the user isn't registered def user_registered? user return nil if user.nil? return nil if user.person.nil? if self.registrations.where(:person_id => user.person.id).count == 0 - Rails.logger.debug("Returning false") - false + logger.debug("User #{user.email} isn't registered to self.title") + return false else - Rails.logger.debug("Returning true") - true + return true end end + ## + # Checks if the registration for the conference is currently open + # + # ====Returns + # * +false+ -> If the conference dates are not set or today isn't in the + # registration period. + # * +true+ -> If today is in the registration period. def registration_open? today = Date.current if self.registration_start_date.nil? || self.registration_end_date.nil? @@ -105,6 +101,12 @@ class Conference < ActiveRecord::Base (registration_start_date..registration_end_date).cover?(today) end + ## + # Checks if the call for papers for the conference is currently open + # + # ====Returns + # * +false+ -> If the CFP is not set or today isn't in the CFP period. + # * +true+ -> If today is in the CFP period. def cfp_open? today = Date.current cfp = self.call_for_papers @@ -114,17 +116,28 @@ class Conference < ActiveRecord::Base return false end + private + ## + # Creates a venue and sets self.venue_id to it's id. Used as before_create. + # def create_venue self.venue_id = Venue.create.id true end + ## + # Creates a EmailSettings association proxy. Used as before_create. + # def create_email_settings build_email_settings true end + + ## + # Creates a UID for the conference. Used as before_create. + # def generate_guid begin guid = SecureRandom.urlsafe_base64 diff --git a/app/views/home/index.html.haml b/app/views/home/index.html.haml index a37067c4..73702c5f 100644 --- a/app/views/home/index.html.haml +++ b/app/views/home/index.html.haml @@ -13,7 +13,7 @@ = conference.title %small %b - = conference.date_range_string + = conference_date_string(conference) - if conference.venue.name and conference.venue.website and conference.venue.address %p %small