yard 0.9.29 → 0.9.30

data/docs/Templates.md

@@ -0,0 +1,496 @@
+# @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
+
+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,
+YARD splits up the rendering of code objects into small components, allowing
+template modification for smaller subsets of a full template without having to
+duplicate the entire template itself. This is necessary because of YARD's support
+for plugins. YARD is designed for extensibility by external plugins, and because
+of this, no one plugin can be responsible for the entire template because no
+one plugin knows about the other plugins being used. For instance, if an RSpec
+plugin was added to support and document specifications in class templates,
+this information would need to be transparently added to the template to work
+in conjunction with any other plugin that performed similar template modifications.
+The design goals can be summarized as follows:
+
+  1. Output should be able to be rendered for any arbitrary format with little
+     modification to YARD's source code. The addition of extra templates should
+     be sufficient.
+  2. The output rendered for an object should independently rendered data
+     from arbitrary sources. These independent components are called "sections".
+  3. Sections should be able to be inserted into any object without affecting
+     any existing sections in the document. This allows for easy modification
+     of templates by plugins.
+
+## 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
+
+The Engine class orchestrates the creation and rendering of Template modules and
+handles serialization or specific rendering scenarios (like HTML). To create
+a template, use the {YARD::Templates::Engine.template template} method. The two most
+common methods used to initiate output are the {YARD::Templates::Engine.render render}
+and {YARD::Templates::Engine.generate generate} methods which generate and
+optionally serialize output to a file. The latter, `#generate`, is used
+specially to generate HTML documentation and copy over assets that may be
+needed. For instance, an object may be rendered with:
+
+    YARD::Templates::Engine.render(:object => myobject)
+
+A set of objects may be rendered into HTML documentation by using:
+
+    # all_objects is an array of module and class objects
+    # options includes a :serializer key to copy output to the file system
+    YARD::Templates::Engine.generate(all_objects, options)
+
+Note that these methods should not be called directly. The {YARD::CodeObjects::Base}
+class has a {YARD::CodeObjects::Base#format #format} helper method to render an
+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
+
+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
+default options set the template style (`:template`), the output format (`:format`),
+and the serializer to use (`:serializer`). This options hash is modifiable
+from all methods seen above. For example, initializing a template to output as
+HTML instead of text can be done as follows:
+
+    myobject.format(:format => :html)
+
+## 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}
+and {YARD::Serializers::FileSystemSerializer FileSystemSerializer} class for
+outputting to console or to a file respectively. When endpoints with locations
+are used (like files or URLs), the serializer implements the {YARD::Serializers::Base#serialized_path #serialized_path}
+method. This allows the translation from a code object to its path at the endpoint,
+which enables inter-document linking.
+
+Rendered objects are automatically serialized using the object if present,
+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
+
+Templates are represented by a directory inside the {YARD::Templates::Engine.template_paths}
+on disk. A standard template directory looks like the following tree:
+
+    (Assuming templates/ is a template path)
+    templates
+    `-- default
+        |-- class
+        |   |-- dot
+        |   |   |-- setup.rb
+        |   |   `-- superklass.erb
+        |   |-- html
+        |   |   |-- constructor_details.erb
+        |   |   |-- setup.rb
+        |   |   `-- subclasses.erb
+        |   |-- setup.rb
+        |   `-- text
+        |       |-- setup.rb
+        |       `-- subclasses.erb
+        |-- docstring
+        |   |-- html
+        |   |   |-- abstract.erb
+        |   |   |-- deprecated.erb
+        |   |   |-- index.erb
+        |   |   `-- text.erb
+        |   |-- setup.rb
+        |   `-- text
+        |       |-- abstract.erb
+        |       |-- deprecated.erb
+        |       |-- index.erb
+        |       `-- text.erb
+
+The path `default` refers to the template style (:template key in options hash)
+and the directories at the next level (such as `class`) refer to template
+`:type` (options hash key) for a template. The next directory refers to the
+output format being used defined by the `:format` template option.
+
+As we saw in the above example, the format option can be set to `:html`, which
+would use the `html/` directory instead of `text/`. Finally, the individual .erb
+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
+
+Every template should have at least one `setup.rb` file that defines the
+{YARD::Templates::Template#init #init} method to set the
+{YARD::Templates::Template#sections #sections} used by the template. If
+a setup.rb is not defined in the template itself, there should be a template
+that is inherited (via parent directory or explicitly) that sets the sections
+on a newly created template.
+
+A standard setup.rb file looks like:
+
+    def init
+      sections :section1, :section2, :section3
+    end
+
+## Sections
+
+Sections are smaller components that correlate to template
+fragments. Practically speaking, a section can either be a template fragment
+(a conventional .erb file or other supported templating language), a method
+(which returns a String) or another {YARD::Templates::Template} (which in turn has its own
+list of 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
+lightweight solution is to nest a set of sub-sections as a list that follows
+a section, for example:
+
+    def init
+      sections :header, [:section_a, :section_b]
+    end
+
+The above example nests `section_a` and `section_b` within the `header` section.
+Practically speaking, these sections can be placed in the result by `yield`ing
+to them. A sample header.erb template might contain:
+
+    <h2>Header</h2>
+    <div id="contents">
+      <%= yieldall %>
+    </div>
+
+This template code would place the output of `section_a` and `section_b` within
+the above div element. Using `yieldall`, we can also change the object that is being
+rendered. For example, we may want to yield the first method of the class.
+We can do this like so:
+
+    <h2>First method</h2>
+    <%= yieldall :object => object.meths.first %>
+
+This would run the nested sections for the method object instead of the class.
+
+Note that `yieldall` yields to all subsections, whereas `yield` will yield
+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
+
+Parent directory templates are automatically inherited (or mixed in, to be
+more accurate) by the current template. This means that the 'default/class/html'
+template automatically inherits from 'default/class'. This also means that anything
+defined in 'default/class/setup.rb' can be overridden by 'default/class/html/setup.rb'.
+
+Since the Template module is a module, and not a class, they can be mixed in
+explicitly (via include/extend) from other templates, which allows templates
+to share erb files or helper logic. The 'default/class' template explicitly
+mixes in the 'default/module' template, since it uses much of the same sections.
+This is done with the helper {YARD::Templates::Template::ClassMethods#T T} method, which
+is simply a shorthand for {YARD::Templates::Engine.template Engine.template}.
+It can then override (using standard inheritance) the sections from the module
+template and insert sections pertaining to classes. This is one of the design
+goals described above.
+
+For instance, the first line in `default/class/html/setup.rb` is:
+
+    include T('default/module/html')
+
+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
+
+The ability to insert sections was mentioned above. The class template, for
+instance, will modify the #init method to insert class specific sections:
+
+    def init
+      super
+      sections.place(:subclasses).before(:children)
+      sections.delete(:children)
+      sections.place([:constructor_details, [T('method_details')]]).before(:methodmissing)
+    end
+
+Observe how sections has been modified after the super method was called (the
+super method would have been defined in `default/module/setup.rb`). The
+`sections` object is of the {YARD::Templates::Section} class and allows sections to be inserted
+before or after another section using {Array#place} by it's given name rather
+than index. This allows the overriding of templates in a way that does not
+depend on where the section is located (since it may have been overridden by
+another module).
+
+You can also use `sections[:name]` to find the first child section named `:name`.
+For instance, with the following sections declaration:
+
+    sections :a, [:b, :c, [:d]]
+
+You can get to the :d section with:
+
+    sections[:a][:c][:d]
+
+You can use this to insert a section inside a nested set without using indexed
+access. The following command would result in `[:a, [:b, :c, [:d, :e]]]`:
+
+    sections[:a][:c].place(:e).after(:d)
+
+There are also two methods, {Insertion#before_any} and {Insertion#after_any},
+which allow you to insert sections before or after the first matching section name
+recursively. The above example could simply be rewritten as:
+
+    sections.place(:e).after_any(:d)
+
+## 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
+to customize YARD templates will want to override existing behaviour without
+creating a template from scratch.
+
+YARD solves this problem by allowing other template paths to be registered.
+Because template modules are represented by a relative path such as 'default/class',
+they can be found within any of the registered template paths. A new template
+path is registered as:
+
+    YARD::Templates::Engine.register_template_path '/path/to/mytemplates'
+
+At this point, any time the 'default/class' template is loaded, the template
+will first be looked for inside the newly registered template path. If found,
+it will be used as the template module, with the modules from the other
+template paths implicitly mixed in.
+
+Therefore, by using the same directory structure as a builtin YARD template,
+a user can customize or override individual templates as if the old ones were
+inherited. A real world example would further modify the 'default/class' template
+seen above by creating such a path in our '/path/to/mytemplates' custom template
+path:
+
+    /path/to/mytemplates/:
+    |-- class
+    |   |-- html
+    |   |   |-- customsection.erb
+    |   |-- setup.rb
+
+The `setup.rb` file would look like:
+
+    def init
+      super
+      sections.push :customsection
+    end
+
+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