yard 0.5.8 → 0.6.0

data/docs/WhatsNew.md

@@ -1,3 +1,223 @@
+What's New in 0.6.x?
+====================
+
+1. **Local documentation server for RubyGems or projects (`yard server`)** (0.6.0)
+2. **Groups support for method listing** (0.6.0)
+3. **Single file template (`--one-file`) support** (0.6.0)
+4. **`yard` CLI executable with pluggable commands** (0.6.0)
+5. **`yard diff` command to object-diff two versions of a project** (0.6.0)
+6. **Added `--asset` option to `yardoc`** (0.6.0)
+7. **New template API** (0.6.0)
+8. **HTML template now adds inline Table of Contents for extra files pages** (0.6.0)
+9. **Removed `--incremental` in favour of `--use-cache`** (0.6.0)
+10. **Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.)** (0.6.0)
+11. **Added `--transitive-tags` to register transitive tags** (0.6.0)
+12. **`yardoc` now displays RDoc-like statistics (`--no-stats` to hide)** (0.6.0)
+13. **`yri` now works on constants** (0.6.0)
+
+## Local documentation server for RubyGems or projects (`yard server`) (0.6.0)
+
+The new `yard server` command spawns a documentation server that can serve
+either documentation for a local project or installed RubyGems. The server 
+will host (by default) on http://localhost:8808. 
+
+To serve documentation for the active project (in the current directory):
+
+    $ yard server
+    
+The server can also run in "incremental" mode for local projects. In this 
+situation, any modified sources will immediately be updated at each request, 
+ensuring that the server always serve the code exactly as it is on disk. 
+Documenting your code in this fashion essentially gives you an efficient a 
+live preview without running a separate command everytime you make a change. 
+To serve documentation for the active project in incremental mode:
+
+    $ yard server --reload
+    
+<span class="note">Note that in incremental mode, objects or method groupings 
+  cannot be removed. If you have removed objects or modified groupings, you 
+  will need to flush the cache by deleting `.yardoc` and (optionally) 
+  restarting the server.</span>
+
+The documentation server can also serve documentation for all installed gems 
+on your system, similar to `gem server`, but using YARD's functionality and 
+templates. To serve documentation for installed gems:
+
+    $ yard server --gems
+    
+<span class="note">Documentation for the gem need not be previously generated 
+  at install-time. If documentation for the gem has not been generated, YARD 
+  will do this for you on-the-fly. It is therefore possible to speed up your 
+  gem installs by using `gem install GEMNAME --no-rdoc` without repercussion.
+  You can also add this switch to your `~/.gemrc` file so that you don't need
+   to re-type it each time. See [this link](http://stackoverflow.com/questions/1789376/how-do-i-make-no-ri-no-rdoc-the-default-for-gem-install) 
+   for exact instructions.</span>
+
+## Groups support for method listing (0.6.0)
+
+You can now organize methods in a class/module into logical separated groups. 
+These groups apply lexically and are listed in the order they are defined. 
+For instance, to define a group:
+
+    # @group Rendering an Object
+    
+    # Documentation here
+    def foo; end
+    
+    # Extra documentation...
+    def bar; end
+    
+    # @group Another Group
+    
+    def aaa; end
+    
+<span class="note">Note that these `@group` and `@endgroup` declarations are 
+  not "tags" and should always be separated with at least 1 line of whitespace 
+  from any other documentation or code.</span>
+    
+In the above example, "Rendering an Object" will be listed with "foo" and 
+"bar" above "Another Group", even though "aaa" comes before the two other 
+methods, alphabetically. To end a group, use `@endgroup`. It is not necessary 
+to end a group to start a new one, only if there is an object following the 
+group that should not belong in any group.
+
+    # @group Group 1
+    
+    def foo; end
+    
+    # @endgroup
+    
+    # This method should not be listed in any group
+    def bar; end
+
+## Single file template (`--one-file`) support (0.6.0)
+
+`yardoc` now has the `--one-file` option to generate a single-file template 
+for small scripts and libraries. In this case, any comments at the top of 
+the script file will be recognized as a README.
+
+## `yard` CLI executable with pluggable commands (0.6.0)
+
+<span class="note">The `yardoc` and `yri` commands are not deprecated and can 
+  continue to be used. They are shortcuts for `yard doc` and `yard ri` 
+  respectively. However, `yard-graph` has been removed.</span>
+
+YARD now has a `yard` executable which combines all pre-existing and new 
+commands into a single pluggable command that is both easier to remember and 
+access. To get a list of commands, type `yard --help`.
+
+If you are a plugin developer, you can create your own `yard` command by first 
+subclassing the {YARD::CLI::Command} class and then registering this class 
+with the {YARD::CLI::CommandParser.commands} list. For instance:
+
+    YARD::CLI::CommandParser.commands[:my_command] = MyCommandClass
+    
+The above line will enable the user to execute `yard my_command [options]`.
+
+## `yard diff` command to object-diff two versions of a project (0.6.0)
+
+One of the built-in commands that comes with the new `yard` executable is the 
+ability to do object-oriented diffing across multiple versions of the same 
+project, either by 2 versions of a gem, or 2 working copies. Just like 
+regular diffing tells you which lines have been added/removed in a file, 
+object diffing allows you to see what classes/methods/modules have been 
+added/removed between versions of a codebase.
+
+For an overview of how to use `yard diff`, see [YARD Object Oriented Diffing](http://gnuu.org/2010/06/26/yard-object-oriented-diffing/).
+
+## `yard stats` to display statistics and undocumented objects (0.6.0)
+
+YARD now outputs the following statistics when `yard stats` is run:
+
+    Files:         125
+    Modules:        35 (    4 undocumented)
+    Classes:       139 (   29 undocumented)
+    Constants:      53 (   20 undocumented)
+    Methods:       602 (   70 undocumented)
+     85.16% documented
+    
+Note that these statistics are based on what you have set to show in your 
+documentation. If you use `@private` tags and/or do not display 
+private/protected methods in your documentation, these will not show up as 
+undocumented. Therefore this metric is contextual.
+
+You can also specifically list all undocumented objects (and their file 
+locations) with the `--list-undoc` option.
+
+## Added `--asset` option to `yardoc` (0.6.0)
+
+The `yardoc` command can now take the `--asset` option to copy over 
+files/directories (recursively) to the output path after generating 
+documentation. The format of the argument is "from:to" where from is the 
+source path and to is the destination. For instance, YARD uses the following 
+syntax in the `.yardopts` file to copy over image assets from the 
+'docs/images' directory into the 'images' directory after generating HTML:
+
+    --asset docs/images:images
+
+## New template API (0.6.0)
+
+The new template API allows for easier insertion of sections within an 
+inherited template. You should no longer need to insert by index, an 
+error-prone process that could break when a template is updated. Instead of:
+
+    sections.last.place(:my_section).before(:another_section)
+
+use:
+
+    sections.place(:my_section).before_any(:another_section)
+    
+You can see more in the {file:docs/Templates.md#Inserting_and_Traversing_Sections}
+document.
+
+## HTML template now adds inline Table of Contents for extra files pages (0.6.0)
+
+A table of contents is now generated dynamically using JavaScript for extra 
+file pages (such as README's, or this document). It is generated based off the
+headers (h1,h2,... tags) used in the document, and can be floated to the 
+right or listed inline on the page.
+
+## Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.) (0.6.0)
+
+Simple meta-data tags can now be added at the command-line and registered to 
+display in templates in a number of pre-defined ways. For instance, to create 
+a freeform text tag, use the following:
+
+    --tag my_tag_name:"My Tag Title"
+    
+You can also create a "typed" tag (similar to `@return`), a typed named tag 
+(similar to `@param`) as well as various combinations. The full list of 
+options are listed in `yardoc --help` under the "Tag Options" section.
+    
+If you wish to create a tag to store data but do not wish to show this data 
+in the templates, use the `--hide-tag` option to hide it from generated output:
+
+    --hide-tag my_tag_name
+
+## Added `--transitive-tags` to register transitive tags (0.6.0)
+
+Transitive tags are tags that apply to all descendents of a namespace (class 
+or module) when documented on that namespace. For instance, the `@since` tag 
+is a transitive tag. Applying `@since` to a class will automatically apply 
+`@since` to all methods in the class. Creating a `@since` tag directly on a 
+method will override the inherited value.
+
+You can specify transitive tags on the command-line by using this option. Note
+that the tags must already exist (built-in or created with the `--tag` option)
+to be specified as transitive. If you wish to do this programmatically, see 
+the {YARD::Tags::Library.transitive_tags} attribute.
+
+## `yardoc` now displays RDoc-like statistics (`--no-stats` to hide) (0.6.0)
+
+As seen in the `yard stats` feature overview, `yardoc` displays RDoc-like 
+statistics when it is run. The output is equivalent to typing `yard stats`. 
+To hide this output when yardoc is run, use `--no-stats`.
+
+## `yri` now works on constants (0.6.0)
+
+Templates have now been added for text view of constants, which displays any 
+documentation and the constant value.
+
 What's New in 0.5.x?
 ====================
 
@@ -205,7 +425,7 @@ that existed but were previously omitted from the generated documentation.
 
 There is also a new templating engine (based on the tadpole templating library) 
 to allow for much more user customization. You can read about it in 
-{file:Templates.md}.
+{file:docs/Templates.md}.
 
 yardoc `--query` argument
 -------------------------
@@ -252,7 +472,7 @@ use this tag sparingly, as it is not meant to be an equivalent to RDoc's
 This tag exists so that you can create a query (`--query !@private`) to
 ignore all of these private objects in your documentation. You can also
 use the new `--no-private` switch, which is a shortcut to the afformentioned
-query. You can read more about the new tags in the {file:GettingStarted.md} 
+query. You can read more about the new tags in the {file:docs/GettingStarted.md} 
 guide.
 
 Default rake task is now `rake yard`

data/lib/rubygems_plugin.rb

@@ -7,6 +7,7 @@ unless defined? Gem::DocManager.load_yardoc
     overwrite_accessor(:has_rdoc) { @has_rdoc }
     overwrite_accessor(:has_rdoc=) {|v| @has_rdoc = v }
   
+    # @since 0.5.3
     def has_yardoc=(value)
       @has_rdoc = 'yard'
     end

data/lib/yard.rb

@@ -1,7 +1,13 @@
 module YARD
-  VERSION = "0.5.8"
+  VERSION = "0.6.0"
+  
+  # The root path for YARD source libraries
   ROOT = File.expand_path(File.dirname(__FILE__))
+  
+  # The root path for YARD builtin templates
   TEMPLATE_ROOT = File.join(ROOT, '..', 'templates')
+  
+  # The location where YARD stores user-specific settings
   CONFIG_DIR = File.expand_path('~/.yard')
   
   # An alias to {Parser::SourceParser}'s parsing method

data/lib/yard/autoload.rb

@@ -3,10 +3,16 @@ def __p(*path) File.join(YARD::ROOT, 'yard', *path) end
 
 module YARD
   module CLI # Namespace for command-line interface components
-    autoload :Base,       __p('cli/base')
-    autoload :YardGraph,  __p('cli/yard_graph')
-    autoload :Yardoc,     __p('cli/yardoc')
-    autoload :YRI,        __p('cli/yri')
+    autoload :Command,        __p('cli/command')
+    autoload :CommandParser,  __p('cli/command_parser')
+    autoload :Diff,           __p('cli/diff')
+    autoload :Gems,           __p('cli/gems')
+    autoload :Graph,          __p('cli/graph')
+    autoload :Help,           __p('cli/help')
+    autoload :Server,         __p('cli/server')
+    autoload :Stats,          __p('cli/stats')
+    autoload :Yardoc,         __p('cli/yardoc')
+    autoload :YRI,            __p('cli/yri')
   end
   
   # A "code object" is defined as any entity in the Ruby language.
@@ -127,6 +133,38 @@ module YARD
     autoload :YardocSerializer,     __p('serializers/yardoc_serializer')
   end
   
+  # Namespace for classes and modules that handle serving documentation over HTTP
+  # @since 0.6.0
+  module Server
+    module Commands
+      autoload :Base,                 __p('server/commands/base')
+      autoload :DisplayFileCommand,   __p('server/commands/display_file_command')
+      autoload :DisplayObjectCommand, __p('server/commands/display_object_command')
+      autoload :FramesCommand,        __p('server/commands/frames_command')
+      autoload :ListCommand,          __p('server/commands/list_command')
+      autoload :ListClassesCommand,   __p('server/commands/list_command')
+      autoload :ListFilesCommand,     __p('server/commands/list_command')
+      autoload :ListMethodsCommand,   __p('server/commands/list_command')
+      autoload :LibraryCommand,       __p('server/commands/library_command')
+      autoload :LibraryIndexCommand,  __p('server/commands/library_index_command')
+      autoload :SearchCommand,        __p('server/commands/search_command')
+      autoload :StaticFileCommand,    __p('server/commands/static_file_command')
+    end
+    
+    autoload :Adapter,                __p('server/adapter')
+    autoload :DocServerSerializer,    __p('server/doc_server_serializer')
+    autoload :DocServerHelper,        __p('server/doc_server_helper')
+    autoload :FinishRequest,          __p('server/adapter')
+    autoload :LibraryVersion,         __p('server/library_version')
+    autoload :NotFoundError,          __p('server/adapter')
+    autoload :RackAdapter,            __p('server/rack_adapter')
+    autoload :RackMiddleware,         __p('server/rack_adapter')
+    autoload :Router,                 __p('server/router')
+    autoload :StaticCaching,          __p('server/static_caching')
+    autoload :WebrickAdapter,         __p('server/webrick_adapter')
+    autoload :WebrickServlet,         __p('server/webrick_adapter')
+  end
+  
   module Tags # Namespace for Tag components
     autoload :DefaultFactory, __p('tags/default_factory')
     autoload :DefaultTag,     __p('tags/default_tag')
@@ -139,7 +177,8 @@ module YARD
     autoload :TagFormatError, __p('tags/tag_format_error')
   end
   
-  module Templates # Namespace for templating system
+  # Namespace for templating system
+  module Templates
     module Helpers # Namespace for template helpers
       autoload :BaseHelper,                 __p('templates/helpers/base_helper')
       autoload :FilterHelper,               __p('templates/helpers/filter_helper')
@@ -153,8 +192,9 @@ module YARD
     end
 
     autoload :Engine,   __p('templates/engine')
-    autoload :Template, __p('templates/template')
     autoload :ErbCache, __p('templates/erb_cache')
+    autoload :Section,  __p('templates/section')
+    autoload :Template, __p('templates/template')
   end
 
   autoload :Docstring,      __p('docstring')

data/lib/yard/cli/{base.rb → command.rb}

@@ -6,11 +6,14 @@ module YARD
     # the option parser
     # 
     # @abstract
-    class Base
-      def initialize
-        log.show_backtraces = false
-      end
-      
+    # @since 0.6.0
+    class Command
+      # Helper method to run the utility on an instance.
+      # @see #run
+      def self.run(*args) new.run(*args) end
+        
+      def description; '' end
+          
       protected
 
       # Adds a set of common options to the tail of the OptionParser
@@ -20,6 +23,17 @@ module YARD
       def common_options(opts)
         opts.separator ""
         opts.separator "Other options:"
+        opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
+          begin
+            require(file.gsub(/\.rb$/, ''))
+          rescue LoadError
+            log.error "The file `#{file}' could not be loaded, check the path and try again."
+            exit
+          end
+        end
+        opts.on('--legacy', 'Use old style Ruby parser and handlers. Always on in 1.8.x.') do
+          YARD::Parser::SourceParser.parser_type = :ruby18
+        end
         opts.on_tail('-q', '--quiet', 'Show no warnings.') { log.level = Logger::ERROR }
         opts.on_tail('--verbose', 'Show more information.') { log.level = Logger::INFO }
         opts.on_tail('--debug', 'Show debugging information.') { log.level = Logger::DEBUG }
@@ -27,7 +41,7 @@ module YARD
         opts.on_tail('-v', '--version', 'Show version.') { puts "yard #{YARD::VERSION}"; exit }
         opts.on_tail('-h', '--help', 'Show this help.')  { puts opts; exit }
       end
-      
+    
       # Parses the option and gracefully handles invalid switches
       # 
       # @param [OptionParser] opts the option parser object

data/lib/yard/cli/command_parser.rb

@@ -0,0 +1,87 @@
+module YARD
+  module CLI
+    # This class parses a command name out of the +yard+ CLI command and calls
+    # that command in the form:
+    # 
+    #   $ yard command_name [options]
+    # 
+    # If no command or arguments are specified, or if the arguments immediately
+    # begin with a +--opt+ (not +--help+), the {default_command} will be used 
+    # (which itself defaults to +:doc+).
+    # 
+    # == Adding a Command
+    # 
+    # To add a custom command via plugin, create a mapping in {commands} from 
+    # the Symbolic command name to the {Command} class that implements the 
+    # command. To implement a command, see the documentation for the {Command}
+    # class.
+    # 
+    # @see Command
+    # @see commands
+    # @see default_command
+    class CommandParser
+      class << self
+        # @return [Hash{Symbol => Command}] the mapping of command names to
+        #   command classes to parse the user command.
+        attr_accessor :commands
+        
+        # @return [Symbol] the default command name to use when no options
+        #   are specified or 
+        attr_accessor :default_command
+      end
+      
+      self.commands = SymbolHash[
+        :diff   => Diff,
+        :doc    => Yardoc,
+        :gems   => Gems,
+        :graph  => Graph,
+        :help   => Help,
+        :ri     => YRI,
+        :server => Server,
+        :stats  => Stats
+      ]
+      
+      self.default_command = :doc
+      
+      # Convenience method to create a new CommandParser and call {#run}
+      # @return (see #run)
+      def self.run(*args) new.run(*args) end
+        
+      def initialize
+        log.show_backtraces = false
+      end
+           
+      # Runs the {Command} object matching the command name of the first
+      # argument.
+      # @return [void] 
+      def run(*args)
+        unless args == ['--help']
+          if args.size == 0 || args.first =~ /^-/
+            command_name = self.class.default_command
+          else
+            command_name = args.first.to_sym
+            args.shift
+          end
+          if commands.has_key?(command_name)
+            return commands[command_name].run(*args)
+          end
+        end
+        list_commands
+      end
+      
+      private
+
+      def commands; self.class.commands end
+      
+      def list_commands
+        puts "Usage: yard <command> [options]"
+        puts
+        puts "Commands:"
+        commands.keys.sort_by {|k| k.to_s }.each do |command_name|
+          command = commands[command_name].new
+          puts "%-8s %s" % [command_name, command.description] 
+        end
+      end
+    end
+  end
+end