set Markdown as default markup

fix, update and add documentation
fix css

.yardopts

@@ -2,6 +2,7 @@
 --private
 --verbose
 --use-cache
+--markup markdown
 --template default
 --template-path ./yard-template
 --plugin yard-activerecord
@@ -15,5 +16,5 @@
 ./db/schema.rb
 -
 ./doc/**/*.md
-./doc/RailsReadme
-./LICENSE
+./doc/RailsReadme.rdoc
+./LICENSE.txt

README.md

@@ -1,25 +1,44 @@
-# Katello Rails app documentation 
+# Katello Rails app developer documentation 
 
-## Guides
+## What is documented?
+
+### Guides
 
 - {file:doc/ForemanIntegration.md}
 - {file:doc/RailsReadme}
+- {file:doc/Graphs.md}
 
-## How to generate this doc
+### Source
 
-- go to Katello src `cd katello/src`
-- generate the documentation (it will use `src/.yardopts` automatically) `yard`
+- {Katello::Configuration}
+- {Notifications}
 
-### Viewing
+## YARD
 
-There are several options
+### How to generate this documentation
+
+- go to rails home
+
+      !!!txt
+      cd katello/src
 
-- start Katello server and click on the link in the footer
+- generate the documentation (it will use `src/.yardopts` automatically)
+
+      !!!txt
+      yard
+
+### Browsing the documentation
+
+There are several options
 
-  - or go directly to {http://katello.path/prefix/yard/docs}
+1. start Katello server and click on the link in the footer or go directly to {http://path.to.katello/a_prefix/yard/docs/katello/frames}
+1. open statically generated documentation `open yardoc/index.html`, run `yard doc` to generate the files first
+1. run standalone server `yard server --reload` and go to {http://localhost:8808}
 
-- open statically generated documentation `open yardoc/index.html`
+### How to
 
-  - run `yard doc` to generate the files first
+- YARD is set to [Markdown syntax](http://daringfireball.net/projects/markdown/syntax#html) by default. Files without extension and code documentation will us it. It can be overridden by different file extension.
+- [Getting started](http://rubydoc.info/docs/yard/file/docs/GettingStarted.md) with YARD
 
-- run server `yard server --reload` and go to {http://localhost:8808}
+  - [Tag list](http://rubydoc.info/docs/yard/file/docs/Tags.md#List_of_Available_Tags) is also useful
+

lib/katello_config.rb

@@ -26,8 +26,7 @@ module Katello
   # (even before Rails). Therefore this configuration can be used anywhere
   # (Gemfile, boot scripts, stand-alone)
   #
-  # Configuration access points are methods #config and #early_config, see method documentation.
-  # There are shortcuts defined: `Katello.config` and `Katello.early_config`
+  # Configuration access points are methods {Katello.config} and {Katello.early_config}, see method documentation.
   #
   # Configuration is represented with tree-like-structure defined with Configuration::Node. Node has
   # minimal Hash-like interface. Node is more strict than Hash. Differences:
@@ -39,6 +38,8 @@ module Katello
   # AppConfig will work for now, but warning is printed to `$stderr`.
   #
   # Some examples
+  #
+  #     !!!txt
   #     # create by a Hash which is converted to Node instance
   #     irb> n = Katello::Configuration::Node.new 'a' => nil
   #     => #<Katello::Configuration::Node:0x10e27b618 @data={:a=>nil}>
@@ -64,12 +65,12 @@ module Katello
   #         {:a=>#<Katello::Configuration::Node:0x10e2a64d0 @data={:a=>12, :b=>34}>}>
   #     irb> n.to_hash
   #     => {:a=>{:a=>12, :b=>34}}
+  #
   module Configuration
 
     # Hash like container for configuration
     # @example allows access by method
-    #   Config.new('a' => {:b => 2}).a.b # => 2
-    # @example
+    #     Config.new('a' => {:b => 2}).a.b # => 2
     class Node
       class NoKey < StandardError
         def initialize(message = nil)
@@ -88,9 +89,9 @@ def each(&block)
         @data.each &block
       end
 
-      # get configuration for +key+
+      # get configuration for `key`
       # @param [Symbol] key
-      # @raise [NoKye] when +key+ is missing
+      # @raise [NoKye] when key is missing
       def [](key)
         raise ArgumentError, "#{key.inspect} should be a Symbol" unless Symbol === key
         if has_key? key
@@ -100,7 +101,8 @@ def [](key)
         end
       end
 
-      # converts +value+ to Config (see #convert)
+      # converts `value` to Config
+      # @see #convert
       def []=(key, value)
         @data[key.to_sym] = convert value
       end
@@ -109,7 +111,7 @@ def has_key?(key)
         @data.has_key? key
       end
 
-      # @example does node contain value at node[:key1][:key2]
+      # @example does node contain value at `node[:key1][:key2]`
       #    node.present? :key1, :key2
       def present?(*keys)
         key, rest = keys.first, keys[1..-1]
@@ -124,7 +126,7 @@ def present?(*keys)
       end
 
       # allows access keys by method call
-      # @raise [NoKye] when +key+ is missing
+      # @raise [NoKye] when `key` is missing
       def method_missing(method, *args, &block)
         if has_key?(method)
           self[method]
@@ -387,14 +389,17 @@ def config_file_path
   end
 
 
+  # @see Configuration::LoaderImpl#config
   def self.config
     Configuration::Loader.config
   end
 
+  # @see Configuration::LoaderImpl#early_config
   def self.early_config
     Configuration::Loader.early_config
   end
 
+  # @see Configuration::LoaderImpl#database_configs
   def self.database_configs
     Configuration::Loader.database_configs
   end

lib/notifications/controller_helper.rb

@@ -12,6 +12,16 @@
 
 module Notifications
   module ControllerHelper
+
+    # defines helper to access notifications from controller
+    # @example how to send notification from controller
+    #   notify.success _("Welcome Back") + ", " + current_user.username, :persist => false
+    #   notify.message _("'%s' no longer matches the current search criteria.") % @gpg_key["name"], :asynchronous => false
+    #   notify.invalid_record @an_user
+    #   notify.warning _("You must be logged in to access that page.")
+    #   notify.error _("Please select at least one system group.")
+    #   notify.exception an_exception
+    # @see Notifier
     def notify
       @notifier ||= Notifier.new(self, default_notify_options)
     end

lib/notifications/notifier.rb

@@ -12,6 +12,8 @@
 
 module Notifications
 
+
+  # sends notifications, see public instance methods
   class Notifier
     include Rails.application.routes.url_helpers
 
@@ -90,34 +92,34 @@ def exception(*args)
 
     # Generate a notice:
     #
-    # notices:              The text to include or Array of texts (nil values are dropped)
-    # options:              Optional hash containing various optional parameters. This includes:
-    #
-    #   level:               The type of notice to be generated. Supported values include:
-    #                        :message, :success (Default), :warning, :error
-    #
-    #   asynchronous:        if notifier has controller default is false, if notifier has no controller
-    #                        (used in model) default is true.
-    #                        if this notice is associated with an event where
-    #                        the user would expect to receive a response immediately
-    #                        as part of a response. This typically applies for events
-    #                        involving things such as create, update and delete.
-    #
-    #                        IMPORTANT: If creating a synchronous request, the invocation of notice
-    #                        must be from within a controller (i.e. not a model).
+    # @param [Array<String>] notices the text to include or Array of texts (nil values are dropped)
+    # @param [Hash] options Optional hash containing various optional parameters
+    # @option options [Symbol] :level The type of notice to be generated, see {LEVELS}, dafault is `:success`
+    # @option options [true, false] :asynchronous
+    #   if notifier has controller default is false, if notifier has no controller
+    #   (used in model) default is true.
+    #   if this notice is associated with an event where
+    #   the user would expect to receive a response immediately
+    #   as part of a response. This typically applies for events
+    #   involving things such as create, update and delete.
+    #   IMPORTANT: If creating a synchronous request, the invocation of notice
+    #   must be from within a controller (i.e. not a model).
     #
-    #   persist:             default is true, if this notice should be stored via ActiveRecord.
-    #                        Note: this option only applies when asynchronous is false.
+    # @option options [true, false] :persist
+    #   default is true, if this notice should be stored via ActiveRecord.
+    #   Note: this option only applies when asynchronous is false.
     #
-    #   details:             String containing additional details. This would typically be to store
-    #                        information such as a stack trace that is in addition to the notice text.
+    # @option options [String] :details
+    #   String containing additional details. This would typically be to store
+    #   information such as a stack trace that is in addition to the notice text.
     #
-    #   request_type:        String representing the request/action this notice is associated with.  In the case
-    #                        of notices generated by controllers, this option is not necessary; however,
-    #                        if the notice is generated by a model, it should be provided.  The typical format
-    #                        would be something like "controller"+"___"+"action" (e.g. "changesets___promote")
+    # @option options [String] :request_type
+    #   String representing the request/action this notice is associated with.  In the case
+    #   of notices generated by controllers, this option is not necessary; however,
+    #   if the notice is generated by a model, it should be provided.  The typical format
+    #   would be something like "controller"+"___"+"action" (e.g. "changesets___promote")
     #
-    #   user:                the user to send the notification to.  If not set, User.current is used
+    # @option options [User] :user the user to send the notification to.  If not set, User.current is used
     #
     def notice(notices, options = { })
       options = process_options options

lib/notify.rb

@@ -10,4 +10,7 @@
 # have received a copy of GPLv2 along with this software; if not, see
 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
 
+# used for sending notifications form ActiveRecord models
+# @example
+#   Notify.success a_message
 Notify = Notifications::Notifier.new

yard-template/default/fulldoc/html/css/common.css

@@ -1,12 +1,23 @@
 /* Override this file with custom rules */
 
-.docstring code, .docstring .object_link a {
-    padding: 1px 3px;
+body {
+    line-height: 18px;
+}
+
+.docstring code, .docstring .object_link a, #filecontents code {
+    padding: 0px 3px 1px 3px;
     border: 1px solid #eef;
     background: #f5f5ff;
 }
 
-#filecontents pre.code, .docstring pre.code, .tags pre.example, .docstring code, .docstring .object_link a {
+#filecontents pre code, .docstring pre code {
+    border: none;
+    background: none;
+    padding: 0;
+}
+
+#filecontents pre.code, .docstring pre.code, .tags pre.example, .docstring code, .docstring .object_link a,
+#filecontents code {
     -moz-border-radius: 2px;
     -webkit-border-radius: 2px;
 }