[Yard] setup ripped from Dragonfly, thanks markevans/dragonfly

knewter · Oct 31, 2011 · 7cb1917 · 7cb1917
1 parent e18664a
commit 7cb1917
Show file tree

Hide file tree

Showing 21 changed files with 331 additions and 0 deletions.
diff --git a/.yardopts b/.yardopts
@@ -0,0 +1,17 @@
+--main README.md
+-e ./yard/setup.rb
+-
+extra_docs/GeneralUsage.md
+extra_docs/Configuration.md
+extra_docs/Models.md
+extra_docs/Controllers.md
+extra_docs/Views.md
+extra_docs/ViewHelpers.md
+extra_docs/Routes.md
+extra_docs/Plugins.md
+extra_docs/PluginDevelopment.md
+extra_docs/ActiveRecord.md
+extra_docs/Mongoid.md
+extra_docs/Dragonfly.md
+LICENSE
+History.md
diff --git a/History.md b/History.md
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Josh Adams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/extra_docs/ActiveRecord.md b/extra_docs/ActiveRecord.md
diff --git a/extra_docs/Configuration.md b/extra_docs/Configuration.md
diff --git a/extra_docs/Controllers.md b/extra_docs/Controllers.md
diff --git a/extra_docs/Dragonfly.md b/extra_docs/Dragonfly.md
diff --git a/extra_docs/GeneralUsage.md b/extra_docs/GeneralUsage.md
diff --git a/extra_docs/Models.md b/extra_docs/Models.md
diff --git a/extra_docs/Mongoid.md b/extra_docs/Mongoid.md
diff --git a/extra_docs/PluginDevelopment.md b/extra_docs/PluginDevelopment.md
diff --git a/extra_docs/Plugins.md b/extra_docs/Plugins.md
diff --git a/extra_docs/Routes.md b/extra_docs/Routes.md
diff --git a/extra_docs/ViewHelpers.md b/extra_docs/ViewHelpers.md
diff --git a/extra_docs/Views.md b/extra_docs/Views.md
diff --git a/yard/handlers/configurable_attr_handler.rb b/yard/handlers/configurable_attr_handler.rb
@@ -0,0 +1,38 @@
+class ConfigurableAttrHandler < YARD::Handlers::Ruby::Legacy::Base
+  handles(/^\s*configurable_attr/)
+
+  def process
+    namespace[:configurable_attributes] ||= []
+
+    attribute = token_to_object(statement.tokens[2])
+    comments = statement.comments.join(' ') if statement.comments
+
+    if statement.block
+    # e.g. configurable_attr :datastore do FileDataStore.new end
+      lazy_default_value = statement.block.to_s
+    else
+    # e.g. configurable_attr :fallback_mime_type, 'application/octet-stream'    
+      default_value = token_to_object(statement.tokens[5..-1])
+    end
+    namespace[:configurable_attributes] << {
+      :attribute => attribute,
+      :default_value => default_value,
+      :lazy_default_value => lazy_default_value,
+      :comments => comments
+    }
+  end
+
+  private
+
+  def token_to_object(token)
+    if token
+      if token.is_a?(YARD::Parser::Ruby::Legacy::TokenList)
+        eval(token.to_s)
+      else # is a single token
+        eval(token.text)
+      end
+    end
+  end
+
+end
+
diff --git a/yard/setup.rb b/yard/setup.rb
@@ -0,0 +1,16 @@
+this_dir = File.dirname(__FILE__)
+
+YARD::Templates::Engine.register_template_path(this_dir + '/templates')
+Dir[this_dir + '/handlers/*.rb'].each do |file|
+  require File.expand_path(file)
+end
+YARD::Parser::SourceParser.parser_type = :ruby18
+
+version = ENV['IMAGINE_VERSION']
+IMAGINE_VERSION = if version
+  puts "Setting the version in the docs to #{version}"
+  version
+else
+  require File.join(this_dir, '/../lib/imagine/version')
+  Imagine.version
+end
diff --git a/yard/templates/default/fulldoc/html/css/common.css b/yard/templates/default/fulldoc/html/css/common.css
@@ -0,0 +1,109 @@
+/* Overrides for yard documentation */
+
+/* Clearfix */
+.clearfix:after {
+	content: ".";
+	display: block;
+	clear: both;
+	visibility: hidden;
+	line-height: 0;
+	height: 0;
+}
+
+.clearfix {
+	display: inline-block;
+}
+
+html[xmlns] .clearfix {
+	display: block;
+}
+
+* html .clearfix {
+	height: 1%;
+}
+ /************/
+
+body {
+  font-family: "PT Sans",Verdana,Arial,sans-serif;
+  font-size: 14px;
+}
+
+pre, code, .code,
+#filecontents pre.code,
+.docstring pre.code,
+.source_code pre {
+  font-family: Inconsolata,Monaco,"Courier New","DejaVu Sans Mono","Bitstream Vera Sans Mono",monospace;
+}
+
+pre.code, code {
+  background:#F5F5FF;
+  overflow-x: auto;
+}
+#filecontents pre.code {
+  margin:10px 0;
+  padding:5px 12px;
+  border-radius:5px;
+  -webkit-border-radius:5px;
+  -moz-border-radius:5px;
+  border: 1px dotted #CCC;
+}
+
+code .val {
+  color:#036A07;
+}
+code .kw {
+  color:#0000FF;
+}
+code .symbol {
+  color:#C5060B;
+}
+
+ul.main_files {
+  list-style-type:none;
+  margin:0;
+  padding:0;
+  font-size:14px;
+}
+ul.main_files li {
+  margin:0;
+  padding:0;
+}
+
+ul.main_files li a {
+  margin: 0;
+  padding:3px 12px;
+  display:block;
+  cursor:pointer;
+}
+#content ul.main_files li a:hover {
+  background-color:#F4F9E4;
+}
+/* Layout */
+#header,
+#content,
+#footer {
+  margin:0 auto;
+  width:1000px;
+}
+#header #logo {
+  float:left;
+  width:50%;
+  font-size: 32px;
+  letter-spacing: -1px;
+  margin-top: 20px;
+}
+#header #search {
+  position:static;
+  float:right;
+}
+#content .col1 {
+  float:left;
+  width: 750px;
+}
+#content .col2 {
+  float:left;
+  margin: 0 0 0 20px;
+  padding: 0 0 0 20px;
+  width: 200px;
+  border-left: 1px dotted #D5D5D5;
+}
diff --git a/yard/templates/default/layout/html/layout.erb b/yard/templates/default/layout/html/layout.erb
@@ -0,0 +1,82 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <%= erb(:headers) %>
+    <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Inconsolata">
+    <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=PT+Sans">
+    <script type="text/javascript" charset="utf-8">
+      (function($){
+        // YARD automatically creates a table of contents
+        // Let's place it inside .col1, instead of #content
+        $(document).ready(function(){
+          $('#toc').prependTo($('.col1'));
+          <% if options[:file] == 'extra_docs/Index.md' %>
+            $('#toc').hide();
+          <% end %>
+        });
+      })(jQuery);
+    </script>
+  </head>
+  <body>
+    <!-- GOOGLE ANALYTICS -->
+    <script type="text/javascript">
+
+      var _gaq = _gaq || [];
+      _gaq.push(['_setAccount', 'UA-16382932-1']);
+      _gaq.push(['_trackPageview']);
+
+      (function() {
+        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+      })();
+
+    </script>
+    <!-- *************** -->
+
+    <script type="text/javascript" charset="utf-8">
+      if (window.top.frames.main) document.body.className = 'frames';
+    </script>
+
+    <div id="header" class="clearfix">
+      <%#= erb(:breadcrumb) %>
+      <div id="logo">Imagine (v <%= IMAGINE_VERSION %>)</div>
+      <%= erb(:search) %>
+    </div>
+
+    <div>
+      <iframe id="search_frame"></iframe>
+    </div>
+
+    <div id="content" class="clearfix">
+      <div class="col1">
+        <%= yieldall %>
+      </div>
+      <div class="col2">
+        <ul class="main_files clearfix">
+          <%= [
+            ['README', 'Home'],
+            ['GeneralUsage', 'General usage'],
+            ['Configuration', 'Configuration'],
+            ['Models', 'Models'],
+            ['Controllers', 'Controllers'],
+            ['Views', 'Views'],
+            ['ViewHelpers', 'View Helpers'],
+            ['Routes', 'Mount this app!'],
+            ['Plugins', 'Plugins'],
+            ['PluginDevelopment', 'Plugin Development'],
+            ['Mongoid', 'Mongoid'],
+            ['Dragonfly', 'Dragonfly'],
+            ['History', 'History'],
+          ].map{|(file, text)|
+            "<li>#{link_file(file, text)}</li>"
+          }.join
+          %>
+        </ul>
+      </div>
+    </div>
+
+    <%= erb(:footer) %>
+  </body>
+</html>
diff --git a/yard/templates/default/module/html/configuration_summary.erb b/yard/templates/default/module/html/configuration_summary.erb
@@ -0,0 +1,31 @@
+<% configurable_attributes = object[:configurable_attributes] || [] %>
+<% if configurable_attributes.any? %>
+<h2>Configuration Summary</h2>
+<h3>Configurable attributes</h3>
+Configurable attributes for an object in general <code>object</code> can be configured either by using something like
+<pre class="code">
+  object.configure <%= hl :do %> |c|
+    c.some_configurable_attribute = <%= hl 'some value' %>
+    c.some_other_configurable_attribute = <%= hl 42 %>
+    ...
+  <%= hl :end %>
+</pre>
+or
+<pre class="code">
+  object.some_configurable_attribute = <%= hl 'some value' %>
+</pre>
+<h4>Configurable attributes for instances of <%= object %></h4>
+<ul>
+  <% configurable_attributes.each do |attribute| %>
+  <li>
+    <code><%= attribute[:attribute] %></code>
+    <% if attribute[:lazy_default_value] %>
+     - default <code><%= hl attribute[:lazy_default_value] %></code> (evaluated lazily) 
+    <% else %>
+     - default <code><%= hl attribute[:default_value] %></code>
+    <% end %>
+    <%= '- ' + attribute[:comments] if attribute[:comments] %>
+  </li>
+  <% end %>
+</ul>
+<% end %>
diff --git a/yard/templates/default/module/setup.rb b/yard/templates/default/module/setup.rb
@@ -0,0 +1,17 @@
+def init
+  super
+  sections.place(:configuration_summary).before(:method_summary)
+end
+
+# Highlight stuff
+def hl(code)
+  case code
+  when :do, :end then %(<span class="kw">#{code}</span>)
+  when Symbol then %(<span class="symbol">#{code.inspect}</span>)
+  when Integer then %(<span class="integer val">#{code}</span>)
+  when String then %(<span class="string val">#{code.inspect}</span>)
+  when true, false then %(<span class="kw">#{code.inspect}</span>)
+  when nil then %(<span class="nil kw">#{code.inspect}</span>)
+  else code
+  end    
+end