From 216847e36c0a181c701074593e3f773daabecbde Mon Sep 17 00:00:00 2001 From: Petr Chalupa Date: Wed, 16 Jan 2013 09:54:32 +0100 Subject: [PATCH] set Markdown as default markup fix, update and add documentation fix css --- .yardopts | 5 +- LICENSE => LICENSE.txt | 0 README.md | 43 +++++++++++----- doc/{RailsReadme => RailsReadme.rdoc} | 0 lib/katello_config.rb | 23 +++++---- lib/notifications/controller_helper.rb | 10 ++++ lib/notifications/notifier.rb | 50 ++++++++++--------- lib/notify.rb | 3 ++ .../default/fulldoc/html/css/common.css | 17 +++++-- 9 files changed, 101 insertions(+), 50 deletions(-) rename LICENSE => LICENSE.txt (100%) rename doc/{RailsReadme => RailsReadme.rdoc} (100%) diff --git a/.yardopts b/.yardopts index 3368e71bad6..afb0322a413 100644 --- a/.yardopts +++ b/.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 diff --git a/LICENSE b/LICENSE.txt similarity index 100% rename from LICENSE rename to LICENSE.txt diff --git a/README.md b/README.md index ec5b674aa45..cbf07a02d25 100644 --- a/README.md +++ b/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 + \ No newline at end of file diff --git a/doc/RailsReadme b/doc/RailsReadme.rdoc similarity index 100% rename from doc/RailsReadme rename to doc/RailsReadme.rdoc diff --git a/lib/katello_config.rb b/lib/katello_config.rb index af98216abcb..ca593796d58 100644 --- a/lib/katello_config.rb +++ b/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 # => #nil}> @@ -64,12 +65,12 @@ module Katello # {: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 diff --git a/lib/notifications/controller_helper.rb b/lib/notifications/controller_helper.rb index 8a4b3c072d8..aeb61686db2 100644 --- a/lib/notifications/controller_helper.rb +++ b/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 diff --git a/lib/notifications/notifier.rb b/lib/notifications/notifier.rb index 12d513b3751..ea7bb5446dc 100644 --- a/lib/notifications/notifier.rb +++ b/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] 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 diff --git a/lib/notify.rb b/lib/notify.rb index 504de9e9e72..32bbf1b0266 100644 --- a/lib/notify.rb +++ b/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 diff --git a/yard-template/default/fulldoc/html/css/common.css b/yard-template/default/fulldoc/html/css/common.css index b2029c01bcd..b2cfe1b0433 100644 --- a/yard-template/default/fulldoc/html/css/common.css +++ b/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; }