yard 0.6.8 → 0.7.0

data/docs/Templates.md

@@ -1,12 +1,12 @@
-Templates Architecture
-======================
+# @title Templates Architecture
+
+# Templates Architecture
 
 Templates are the main component in the output rendering process of YARD,
 which is invoked when conventional HTML/text output needs to be rendered
 for a set of code objects.
 
-Design Goals
-------------
+## Design Goals
 
 The general design attempts to be as abstracted from actual content and templates
 as possible. Unlike RDoc which uses one file to describe the entire template,
@@ -30,15 +30,13 @@ The design goals can be summarized as follows:
      any existing sections in the document. This allows for easy modification
      of templates by plugins.
      
-Templates
----------
+## Templates
 
 Template modules are the objects used to orchestrate the design goals listed 
 above. Specifically, they organize the sections and render the template contents
 depending on the format. 
 
-Engine
-------
+## Engine
 
 The Engine class orchestrates the creation and rendering of Template modules and 
 handles serialization or specific rendering scenarios (like HTML). To create
@@ -63,8 +61,7 @@ object. For instance, the above render example is equivalent to the simple
 call `myobject.format`. The `generate` method is a special kind of render
 and is called from the {YARD::CLI::Yardoc} command line utility.
 
-Template Options
-----------------
+## Template Options
 
 A template keeps state when it is rendering output. This state is kept in
 an options hash which is initially passed to it during instantiation. Some
@@ -75,8 +72,7 @@ HTML instead of text can be done as follows:
 
     myobject.format(:format => :html)
     
-Serializer
-----------
+## Serializer
 
 This class abstracts the logic involved in deciding how to serialize data to
 the expected endpoint. For instance, there is both a {YARD::Serializers::StdoutSerializer StdoutSerializer}
@@ -91,8 +87,7 @@ otherwise the rendered object is returned as a string to its parent. Nested
 Templates automatically set the serializer to nil so that they return
 as a String to their parent.
 
-Creating a Template
--------------------
+## Creating a Template
 
 Templates are represented by a directory inside the {YARD::Templates::Engine.template_paths}
 on disk. A standard template directory looks like the following tree:
@@ -137,8 +132,7 @@ files are the sections that make up the template.
 Note that the subdirectory `html/` is also its own "template" that inherits
 from the parent directory. We will see more on this later.
 
-setup.rb
---------
+## setup.rb
 
 Every template should have at least one `setup.rb` file that defines the 
 {YARD::Templates::Template#init #init} method to set the 
@@ -153,8 +147,7 @@ A standard setup.rb file looks like:
       sections :section1, :section2, :section3
     end
 
-Sections
---------
+## Sections
 
 Sections are smaller components that correlate to template
 fragments. Practically speaking, a section can either be a template fragment 
@@ -162,8 +155,7 @@ fragments. Practically speaking, a section can either be a template fragment
 (which returns a String) or another {YARD::Templates::Template} (which in turn has its own 
 list of sections).
 
-Nested Sections
----------------
+## Nested Sections
 
 Sections often require the ability to encapsulate a set of sub-sections in markup
 (HTML, for instance). Rather than use heavier Template subclass objects, a more
@@ -198,8 +190,7 @@ to each individually (in order) until there are no more left to yield to.
 In the vast majority of cases, you'd want to use `yieldall`, since `yield`
 makes it hard for users to override your template.
 
-Inheriting Templates
---------------------
+## Inheriting Templates
 
 Parent directory templates are automatically inherited (or mixed in, to be
 more accurate) by the current template. This means that the 'default/class/html'
@@ -223,8 +214,7 @@ For instance, the first line in `default/class/html/setup.rb` is:
 This includes the 'default/module/html', which means it also includes 'default/module'
 by extension. This allows class to make use of any of module's erb files.
 
-Inserting and Traversing Sections
----------------------------------
+## Inserting and Traversing Sections
 
 The ability to insert sections was mentioned above. The class template, for
 instance, will modify the #init method to insert class specific sections:
@@ -264,8 +254,7 @@ recursively. The above example could simply be rewritten as:
 
     sections.place(:e).after_any(:d)
 
-Overriding Templates by Registering a Template Path
----------------------------------------------------
+## Overriding Templates by Registering a Template Path
 
 Inheriting templates explicitly is useful when creating a customized template
 that wants to take advantage of code re-use. However, most users who want
@@ -305,3 +294,225 @@ The `setup.rb` file would look like:
 
 Now, when a class object is formatted as HTML, our customsection.erb will be 
 appended to the rendered data.
+
+
+### Overriding Stylesheets and Javascripts
+
+Template authors can override existing stylesheets and javascripts by creating
+a file with the same name as existing files within the `fulldoc` template. The
+documentation output will utilize the new replacement file.
+
+YARD's `fulldoc` template defines three stylesheets:
+
+    /yard/templates/default/:
+    |-- fulldoc
+    |   |-- html
+    |   |   |-- css
+    |   |   |   |-- common.css
+    |   |   |   |-- full_list.css
+    |   |   |   |-- style.css
+
+The `style.css` is the primary stylesheet for the HTML output.
+
+The `full_list.css` is an additional stylesheet loaded specifically for the
+search field menus (i.e. class list, method list, and file list).
+
+The `common.css` is an empty css file that an template author can easily override
+to provide custom styles for their plugin. However, if a user installs multiple
+plugins that utilize this same file to deliver styles, it is possible that they
+will be overridden.
+
+YARD's `fulldoc` template defines three javascript files:
+
+    /yard/templates/default/:
+    |-- fulldoc
+    |   |-- html
+    |   |   |-- js
+    |   |   |   |-- app.js
+    |   |   |   |-- full_list.js
+    |   |   |   |-- jquery.js
+
+The `app.js` is the primary javascript file for the HTML output.
+
+The `full_list.js` defines additional javascript loaded specifically for the
+search field menus (i.e. class list, method list, and file list).
+
+The `jquery.js` is copy of the jquery javascript library.
+
+### Adding a Custom Stylesheet or Javascript
+
+To load additional stylesheets and javascripts with every page (except the search
+field menus) generated from the base `layout` template:
+
+  1. Define your own custom stylesheet and/or javascript file 
+     (default/ is the default template name inside of the /template root directory):
+
+        /template/default/:
+        |-- fulldoc
+        |   |-- html
+        |   |   |-- css
+        |   |   |   |-- custom.css
+        |   |   |-- js
+        |   |   |   |-- custom.js
+
+  2. Create a `setup.rb` in the `layout` template directory and override the methods 
+     `stylesheets` and `javascripts`. The path to the template would be:
+  
+        /template/default/:
+        |-- layout
+        |   |-- html
+        |   |   |-- setup.rb
+        
+      And the code would look like:
+  
+        def stylesheets
+          # Load the existing stylesheets while appending the custom one
+          super + %w(css/custom.css)
+        end
+    
+        def javascripts
+          # Load the existing javascripts while appending the custom one
+          super + %w(js/custom.js)
+        end
+    
+
+To load additional stylesheets and javascripts for the search menus loaded from 
+the `fulldoc` template:
+
+  1. Define your own custom stylesheet and/or javascript file.
+
+        /path/to/mytemplates/:
+        |-- fulldoc
+        |   |-- html
+        |   |   |-- css
+        |   |   |   |-- custom_full_menu.css
+        |   |   |-- js
+        |   |   |   |-- custom_full_menu.js
+
+
+  3. Override the methods `stylesheets_full_list` and `javascripts_full_list`
+     in the `setup.rb` file inside fulldoc/html.
+
+        def stylesheets_full_list
+          # Load the existing stylesheets while appending the custom one
+          super + %w(css/custom.css)
+        end
+
+        def javascripts_full_list
+          # Load the existing javascripts while appending the custom one
+          super + %w(js/custom.js)
+        end
+
+### Overriding Search Menus
+
+By default YARD's `fulldoc` template generates three search fields:
+
+  * Class List
+  * Method List
+  * File List
+
+Their contents are rendered in methods within the `fulldoc` template:
+
+  * `generate_class_list`
+  * `generate_method_list`
+  * `generate_file_list`
+  
+To override these lists you will need to:
+
+  1. Create a `setup.rb` in the `fulldoc` template directory and override the
+     particular method.
+     
+         /path/to/mytemplates/:
+         |-- fulldoc
+         |   |-- html
+         |   |   |-- setup.rb
+ 
+         def generate_method_list
+           @items = prune_method_listing(Registry.all(:method), false)
+           @items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? }
+   
+           # Here we changed the functionality to reverse the order of displayed methods
+           @items = @items.sort_by {|m| m.name.to_s }.reverse
+           @list_title = "Method List"
+           @list_type = "methods"
+           asset('method_list.html', erb(:full_list))
+         end
+
+### Adding Additional Search Menus
+
+By default YARD's `fulldoc` template generates three search fields:
+
+  * Class List
+  * Method List
+  * File List
+
+These are defined in the `layout` template method `menu_lists` and pulled into
+the `fulldoc` template through a similarly named method.
+
+To load an additional menu item:
+
+
+  1. Create a `setup.rb` in the `layout` template directory and override the methods 
+   `menu_lists`. The `type` informs the search field the name of the file.
+    The `title` is the name that appears above the section when viewed in frames.
+    The `search_title` is the name that appears in the search field tab on the page.
+   
+
+        /path/to/mytemplates/:
+        |-- layout
+        |   |-- html
+        |   |   |-- setup.rb
+
+        def menu_lists
+          # Load the existing menus
+          super + [ { :type => 'feature', :title => 'Features', :search_title => 'Feature List' } ]
+        end
+        
+  2. Create a `setup.rb` in the `fulldoc` template directory and create a method
+     to generate a menu for the specified `type`. 
+     The method `generate_assets` will look for a function with a signature prefixed
+     with `generate`, the type value specified, and the suffix `list`. Within that 
+     method you can configure and load the specific objects you wish to display.
+     
+         /path/to/mytemplates/:
+         |-- fulldoc
+         |   |-- html
+         |   |   |-- setup.rb
+
+         def generate_feature_list
+         
+           # load all the features from the Registry
+           @items = Registry.all(:feature)
+           @list_title = "Feature List"
+           @list_type = "feature"
+           
+           # optional: the specified stylesheet class
+           # when not specified it will default to the value of @list_type
+           @list_class = "class"
+           
+           # Generate the full list html file with named feature_list.html
+           # @note this file must be match the name of the type
+           asset('feature_list.html', erb(:full_list))
+         end
+
+
+  3. Define custom javascript to load the search fields and the keyboard shortcuts.
+  
+        function featureSearchFrameLinks() {
+            $('#feature_list_link').click(function() {
+                toggleSearchFrame(this, relpath + 'feature_list.html');
+            });
+        }
+
+        function featureKeyboardShortcuts() {
+          if (window.top.frames.main) return;
+          $(document).keypress(function(evt) {
+            if (evt.altKey || evt.ctrlKey || evt.metaKey || evt.shiftKey) return;
+            if (typeof evt.orignalTarget !== "undefined" &&  
+                (evt.originalTarget.nodeName == "INPUT" || 
+                evt.originalTarget.nodeName == "TEXTAREA")) return;
+            switch (evt.charCode) {
+              case 82: case 114: $('#feature_list_link').click(); break; // 'r'
+            }
+          });
+        }

data/docs/WhatsNew.md

@@ -1,5 +1,181 @@
-What's New in 0.6.x?
-====================
+# @title What's New?
+
+# What's New in 0.7.x?
+
+1. **Macro support and detection of DSL methods** (0.7.0)
+2. **Inherited attributes now show in HTML output** (0.7.0)
+3. **The 'app' directory is now parsed by default** (0.7.0)
+4. **Added support for metadata (@title, @markup) in extra files/readmes** (0.7.0)
+5. **Added `yard list` command (alias for `yardoc --list`)** (0.7.0)
+6. **Added Git support in `yard diff`** (0.7.0)
+7. **Added `{include:file:FILENAME}` syntax** (0.7.0)
+8. **Added `{render:OBJECT}` syntax to embed object docs in extra files** (0.7.0)
+9. **Added improved templates API for custom CSS/JS/menus** (0.7.0)
+10. **Added Ruby markup type (`-m ruby`)** (0.7.0)
+11. **Added state tracking variables to Parser/Handler architecture** (0.7.0)
+12. **Added before/after callbacks to SourceParser** (0.7.0)
+13. **Can now use `--yardopts FILE` to specify a custom yardopts file** (0.7.0)
+14. **Added new `-t guide` template for guide based docs** (0.7.0)
+
+## Macro support and detection of DSL methods (0.7.0)
+
+YARD will now automatically detect class level method calls, similar to the
+way it knows what an `attr_accessor` is. By simply adding documentation to
+your class level declarations, YARD can automatically detect them as methods
+or attributes in your class. Consider DataMapper's "property" declaration:
+
+    class Post
+      # @attribute
+      # @return [String] the title of the post
+      property :title, String
+    end
+    
+The above declaration would be created as the `Post#title`. The optional
+`@attribute` tag tells YARD that the property is an "attribute", and not just
+a regular method.
+
+In addition to basic DSL method detection, YARD also supports macros to create
+docstrings that can be copies to other objects; these macros can also be 
+"attached" to class level methods to create implicit documentation for macros.
+
+Macros and DSL method detection are discussed in much more detail in the 
+{file:docs/GettingStarted.md}, so you should read about them there if you're
+interested in this feature.
+
+## Inherited attributes now show in HTML output (0.7.0)
+
+Inherited attributes will now show up in HTML documentation using the default
+template in the same manner that inherited methods do.
+
+## The 'app' directory is now parsed by default (0.7.0)
+
+YARD tries to follow the "It Just Works" attitude in writing developer tools, 
+and therefore has added `app/**/*.rb` to the default list of globs that it
+searches for code in. You no longer need to create a `.yardopts` just to
+list your app directory when documenting your code on rubydoc.info. 
+We should have done this a while ago! And don't worry, YARD still checks
+lib and ext by default, too.
+
+## Added support for metadata (@title, @markup) in extra files/readmes (0.7.0)
+
+Extra files (READMEs, ChangeLogs, LICENSE files, and other guides) now support
+metadata tags, just like docstrings in code comments. By adding @tag values
+to the top of a file (no whitespace preceding it) inside of a `# comment` line,
+YARD will detect and parse these tags and store it for later usage. 
+
+Tags can contain arbitrary data as well as arbitrary tag names, however the 
+tag names @title and @markup are reserved to specify the document title and 
+markup format respectively. The title will be used in the file list menu,
+index page, as well as any linking of the file via the `{file:Filename}`
+syntax. An example of a document with metadata would be:
+
+    # @title The Best Project Ever!
+    # @markup rdoc
+    # @author Foo Bar (custom tag, does not display in templates)
+    
+    = This Project Rules
+    
+    == Contents
+    
+    ...
+
+Note that previous versions of YARD recommended specifying the markup of an
+extra file with the `#!markup` shebang, but the `@markup` metadata tag is now
+the "best practice" for specifying the markup format of an extra file.
+
+## Added `yard list` command (alias for `yardoc --list`) (0.7.0)
+
+The `yardoc --list` command is used to list objects that are parsed from
+a codebase. This can be used to grep methods/classes in a codebase from the
+command line. `yard list` now calls `yardoc --list` as a convenience command.
+
+Note that the `yardoc --list` command may eventually be replaced by a more 
+feature-filled `yard list` command, so `yard list` should be used instead of
+`yardoc --list` when possible.
+
+## Added Git support in `yard diff` (0.7.0)
+
+The `yard diff` command can now perform object diffing on git repositories.
+Provide the `--git` switch to `yard diff` with 2 commit/branches like so:
+
+    $ yard diff --git HEAD~5 HEAD
+    Added objects:
+
+      YARD::Parser::SourceParser#contents
+      YARD::Parser::SourceParser#globals
+      ...
+
+## Added `{include:file:FILENAME}` syntax (0.7.0)
+
+You can now use the `{include:file:FILENAME}` syntax to embed the contents
+of an extra file marked up in its markup format. This syntax supports embedding
+Ruby source files and performing syntax highlighting on the code.
+
+## Added `{render:OBJECT}` syntax to embed object docs in extra files (0.7.0)
+
+You can now use the `{render:Object}` syntax to embed the documentation 
+rendering of an entire object (method, class, module) inside of an extra file.
+This is useful when writing non-API based guides that might require listing
+a few helper methods or classes. The {file:docs/GettingStarted.md} discussed
+this syntax in more detail (with example usage).
+
+## Added improved templates API for custom CSS/JS/menus (0.7.0)
+
+Plugin & template developers can now more easily insert custom stylesheet
+or JavaScript files in their customized templates, thanks to an abstraction
+of the template API. This is documented in the {docs/Templates.md} document.
+In addition to custom CSS/JS, developers can also create custom menu tabs
+in both the framed and non framed version of the default theme.
+
+## Added Ruby markup type (`-m ruby`) (0.7.0)
+
+The Ruby markup type (`-m ruby`) will now use syntax highlighting for all
+formatting. This is probably not useful as a global switch, but can be used
+on individual extra files using the metadata markup specification discussed
+above.
+
+## Added state tracking variables to Parser/Handler architecture (0.7.0)
+
+The parser and handler architecture now contain state variables 
+{YARD::Handlers::Base#extra_state} and {YARD::Handlers::Processor#globals}
+to share data across handlers and the entire processing phase. `#extra_state`
+provided a place to store per-file data, while `#globals` gives the developer
+access to inter-file state when parsing multiple files at once.
+
+## Added before/after callbacks to SourceParser (0.7.0)
+
+The {YARD::Parser::SourceParser} class can now register callbacks to execute
+code before and after parsing of file globs, as well as before and after
+parsing of individual files. This allows plugin developers to perform
+setup/teardown (and set global state or update the {YARD::Registry}).
+
+See the documentation for the following methods:
+
+* {YARD::Parser::SourceParser.before_parse_list}
+* {YARD::Parser::SourceParser.after_parse_list}
+* {YARD::Parser::SourceParser.before_parse_file}
+* {YARD::Parser::SourceParser.after_parse_file}
+
+## Can now use `--yardopts FILE` to specify a custom yardopts file (0.7.0)
+
+The `yardoc` command now supports `--yardopts FILE` to specify custom .yardopts
+options files. This is useful if you have multiple documentation sets, such
+as a guide documentation set and an API documentation set.
+
+## Added new `-t guide` template for guide based docs (0.7.0)
+
+You can now write guide style documentation using a new 'guide' template that
+only generates documentation for extra files. You would use it in the form:
+
+    yardoc -t guide - README GettingStarted FAQ TroubleShooting LICENSE
+
+This creates the sections for the readme, a getting started, frequently asked
+questions, trouble shooting and license page.
+
+If you need to refer to class / method documentation, you can embed API documentation
+using the `{render:Object}` tag discussed above.
+
+# 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)