docapi 0.1.5

data/files/stylesheets/documentation/highlighter/zenburn.css

@@ -0,0 +1,113 @@
+/*
+
+Zenburn style from voldmar.ru (c) Vladimir Epifanov <voldmar@voldmar.ru>
+based on dark.css by Ivan Sagalaev
+
+*/
+
+pre code[class]:after {
+  content: 'highlight: ' attr(class);
+  display: block; text-align: right;
+  font-size: smaller;
+  color: #CCC; background: white;
+  border-top: solid 1px black;
+  padding-top: 0.5em;
+}
+
+pre code {
+  display: block;
+  background: #3F3F3F;
+  color: #DCDCDC;
+}
+
+.keyword,
+.tag,
+.django .tag,
+.django .keyword,
+.css .class,
+.css .id,
+.lisp .title {
+  color: #E3CEAB;
+}
+
+.django .template_tag,
+.django .variable,
+.django .filter .argument {
+  color: #DCDCDC;
+}
+
+.number,
+.date {
+  color: #8CD0D3;
+}
+
+.dos .envvar,
+.dos .stream,
+.variable,
+.apache .sqbracket {
+  color: #EFDCBC;
+}
+
+.dos .flow,
+.diff .change,
+.python .exception,
+.python .built_in,
+.literal {
+  color: #EFEFAF;
+}
+
+.diff .chunk,
+.ruby .subst {
+  color: #8F8F8F;
+}
+
+.dos .keyword,
+.python .decorator,
+.class .title,
+.function .title,
+.ini .title,
+.diff .header,
+.ruby .class .parent,
+.apache .tag {
+    color: #efef8f;
+}
+
+.dos .winutils,
+.ruby .symbol,
+.ruby .string,
+.ruby .instancevar {
+  color: #DCA3A3;
+}
+
+.diff .deletion,
+.string,
+.tag .attribute .value,
+.preprocessor,
+.built_in,
+.sql .aggregate,
+.javadoc,
+.smalltalk .class,
+.smalltalk .localvars,
+.smalltalk .array,
+.css .rules .value,
+.attr_selector,
+.pseudo,
+.apache .cbracket {
+  color: #CC9393;
+}
+
+.shebang,
+.diff .addition,
+.comment,
+.java .annotation,
+.template_comment,
+.pi,
+.doctype {
+  color: #7F9F7F;
+}
+
+.html .css,
+.html .javascript {
+  opacity: 0.5;
+}
+

data/files/stylesheets/documentation/layout.css

@@ -0,0 +1,161 @@
+body {
+/*	font-size: 16px;*/
+  color:black;
+  font-family:Lucida Grande,Verdana,Arial,Helvetica,sans-serif;
+  font-size:90%;
+	width: auto;
+	margin: auto;
+	padding: 20px 300px 20px 40px;
+}
+h1, h2, h3, h4, h5 {
+  position: relative;
+}
+h1 {
+  border-bottom: 1px solid #eee;
+  color:#0E3062;
+  font-size:1.8em;
+  margin:0.8em 0 0.3em;
+}
+h2 {
+  font-size: 1.4em;
+  font-family: 'Bitstream Vera Sans Mono', Monaco, monospace, courier, 'courier new';
+}
+h3 {
+  font-family: "Courier New";
+}
+pre
+{
+/*  margin: 0 0 10px 0;*/
+/*  padding: 10px;*/
+  font-size: 12px;
+  line-height: 150%;
+  font-family: 'Bitstream Vera Sans Mono', Monaco, monospace, courier, 'courier new';
+  background: #F8F8FF;
+  color: #111;
+/*  border: 1px solid #ddd;*/
+}
+pre.hidden {
+  cursor: pointer;
+}
+code, tt {
+  overflow: auto;
+  font-family: 'Bitstream Vera Sans Mono', Monaco, monospace, courier, 'courier new';
+  padding: 0 2px;
+  background: #f1f1f1;
+  font-size: .9em;
+  border-bottom: 1px solid #ddd;
+}
+
+pre.hidden:after {
+  content: 'hidden';
+  display: block; text-align: center;
+  font-size: smaller;
+  color: #000; background: white;
+  border-top: solid 1px #ccc;
+  padding-top: 0.5em;
+}
+
+pre code
+{
+  background: transparent;
+}
+
+table.code {
+  width: 100%;
+}
+
+div.code pre {
+  margin: 0;
+}
+p {
+  margin-top: 0px;
+  margin-bottom: 0.5em;
+}
+li > p:first-child:first-line {
+  background-color: #ffffe0;
+  padding: 0px 8px;
+}
+span.replace {
+  color: orange;
+}
+a > span.replace {
+  color: inherit;
+}
+
+p.page-title {
+  color: #880000;
+  font-weight: bold;
+  font-size: 2em;
+}
+.docapi-section {
+  margin-left: 15px;
+}
+.docapi-subsection {
+  padding: 5px;
+  margin-bottom: 20px;
+}
+.docapi-subsection .docapi-title {
+  padding: 3px 10px;
+  font-size: 1.4em;
+  background: #336699;
+  color: #fff;
+  margin-bottom: 10px;
+  font-weight: bold;
+  font-family: "Courier New";
+}
+.docapi-subsection .docapi-subtitle {
+  font-size: 1.1em;
+  font-weight: bold;
+  font-family: 'Bitstream Vera Sans Mono', Monaco, monospace, courier, 'courier new';
+  margin:20px 2px 5px 0px;
+  border-left: 5px solid orange;
+  padding-left: 5px;
+}
+table {
+  font-size: 0.8em;
+}
+
+/*#toc {
+  float: right;
+  font-size: 10pt;
+  width: 200px;
+  padding: 10px 10px 10px 20px;
+  background: #efffb1;
+  border: solid 1px #ccd136;
+  margin: 0 0 10px 15px;
+}*/
+
+
+
+#toc {
+	position: fixed;
+	top: 20px;
+  background: none;
+	border: none;
+	right: 20px;
+	border-left: solid 5px #ddd;
+  width: 260px;
+/*  bottom: 20px;*/
+  height: 100%;
+	-webkit-box-sizing: border-box;
+	-moz-box-sizing: border-box;
+}
+#toc li {
+  padding: 5px;
+}
+#toc a {
+  background: #efffb1;
+}
+a.toc-top-link {
+  -moz-background-clip:border;
+  -moz-background-inline-policy:continuous;
+  -moz-background-origin:padding;
+  background:#EEEEEE none repeat scroll 0 0;
+  font-size:8pt;
+  left:-40px;
+  padding:4px;
+  position:absolute;
+  text-align:center;
+  top:5px;
+  width:30px;
+}

data/lib/docapi.rb

@@ -0,0 +1,150 @@
+require 'pathname'
+require 'tempfile'
+require 'maruku'
+require 'fileutils'
+
+class Docapi
+  
+  FILES_TO_INCLUDE = {
+    :javascripts => ["./javascripts/documentation/highlight.pack.js", "./javascripts/documentation/jquery-1.3.2.min.js", "./javascripts/documentation/jquery.tableofcontents.min.js", "./javascripts/documentation/documentation.js"],
+    :stylesheets => ["./stylesheets/documentation/layout.css", "./stylesheets/documentation/syntax.css", "./stylesheets/documentation/highlighter/default.css"]
+  }
+  
+  def initialize
+    
+  end
+  
+  def merge(input_path, output_path, options = {})
+    input_dir = Pathname.new(input_path)
+    raise ArgumentError, "Input directory does not exist" unless input_dir.directory?
+    output_dir = Pathname.new(output_path || Pathname.getwd+"generated-doc")
+    output_dir.mkpath
+    output = File.open(output_dir+"index.html", "w+")
+    output << header(:title => options[:title])
+    output << convert_directory(input_dir)
+    output << footer
+    output.close
+    # copy stylesheets and javascripts files
+    FileUtils.cp_r(File.join(File.dirname(__FILE__), "..", "files", "."), output_dir)
+  end
+  
+  def convert_directory(dir, level = 1)
+    output = []
+    dir.entries.each do |entry|
+      next if entry.to_s =~ /^\./
+      path = dir+entry
+      title = File.basename(entry).gsub(/\d+-/, "").gsub(/\..+?$/, "")
+      output << "<div class='docapi-section #{title.downcase}'>"
+      if path.directory?
+        output << "<h#{level}>#{title.capitalize}</h#{level}>"
+        output << convert_directory(path, level+1)
+      else
+        output << convert_file(path)
+      end  
+      output << '</div>'
+    end
+    output.flatten
+  end
+  
+  def convert_file(file)
+    case file.extname
+    when ".md"
+      Maruku.new( File.read(file) ).to_html
+    when ".rb"
+      process_file_sections(file, 'ruby', [/^=begin (.*)$/, /^=end$/])
+    when ".py"
+      process_file_sections(file, 'python', [/^''' (.*)$/, /^'''$/])
+    when ".sh"
+      process_file_sections(file, 'bash', [/^<<ENDCOMMENT >\/dev\/null$/, /^ENDCOMMENT$/])
+    when ".html"
+      File.read(file)
+    end
+  end
+  
+  
+  def process_file_sections(file, language, regexps)
+    blocks = []
+    output = ["<div class='docapi-subsection'><div class='docapi-title'>#{File.basename(file).gsub(/^\d+-/, "")}</div>"]
+    File.open(file, "r").each do |line|
+      if line =~ regexps.first
+        output << write_block(blocks.pop)
+        blocks << {:content => "", :language => ($1 || "markdown")}
+      elsif line =~ regexps.last
+        output << write_block(blocks.pop)
+      else
+        blocks << {:content => "", :language => language} if blocks.last.nil?
+        blocks.last[:content] << line
+      end
+    end  
+    output << write_block(blocks.pop)
+    output << '</div>'
+  end
+  
+  def write_block(block)
+    if block
+      case block[:language]
+      when "markdown", "text"
+        Maruku.new( block[:content] ).to_html.gsub(/<pre class='(.+?)'><code>(.*?)<\/code><\/pre>/m, '<pre><code class="\1">\2</code></pre>')
+      else
+        '<pre><code class="'+block[:language]+'">'+block[:content]+'</code></pre>'
+      end
+    end
+  end
+  
+  def generate(input_paths, output_path, options = {})
+    require 'rdoc'
+    require 'rdoc/rdoc'
+    rdoc_options = %w{-f html --one-file --charset=UTF-8 -U}
+    rdoc_options.concat input_paths
+    output_dir = Pathname.new(output_path || Pathname.getwd+"documentation")
+    raise ArgumentError, "Output directory '#{output_dir}' does not exist" unless output_dir.directory?
+    rdoc_output = Tempfile.new("rdoc_output.html")
+    old_stdout = $stdout
+    begin
+      # redirect stdout to the file
+      $stdout = rdoc_output
+      RDoc::RDoc.new.document(rdoc_options)
+    ensure
+      $stdout = old_stdout
+    end
+    rdoc_output.rewind
+    documentation = rdoc_output.read
+    rdoc_output.close
+    date = documentation[/<tr><td>Modified:<\/td><td>(.*?)<\/td><\/tr>/, 1]
+    methods = documentation.split("<h4>  method: ")
+    methods.shift
+    methods.map!{ |m| 
+      ["<div class='docapi-subsection'>", m.gsub(/<blockquote><pre>.*/m, "").gsub(/<a name="(.+?)">(.*?)<br \/>\s*?<\/a>/m, "<div class='docapi-title'><a name=\"\\1\">\\2<a></div>").gsub(/<h2>(.*?)<\/h2>/m, "<div class='docapi-subtitle'>\\1</div>").gsub(/<pre>(.*?)<\/pre>/m, "<pre><code>\\1</code></pre>"), "</div>"].join("")
+    }
+
+    File.open(File.join(output_dir.realpath, "documentation.html"), "w+") do |f|
+      # sort methods by :call-seq: length ASC. A bit dirty but...
+      methods.sort_by{|m| method = m[/<div class='docapi-title'><a name=".*?">(.+?)<a><\/div>/, 1].length rescue 0}.each{ |method| f << method }
+    end
+  end
+  
+  
+  def header(options = {})
+    output = []
+    output << "<html><head><title>#{options[:title] || "Documentation"}</title>"
+    FILES_TO_INCLUDE[:javascripts].each do |file|
+      output << '<script type="text/javascript" src="'+file+'"></script>'
+    end
+    FILES_TO_INCLUDE[:stylesheets].each do |file|
+      output << '<link media="screen" type="text/css" href="'+file+'" rel="stylesheet"/>'
+    end
+    output << %Q{
+  	<!--[if IE]>
+  	<style type="text/css" media="screen">
+  		body {padding-right: 320px}
+  	</style>
+  	<![endif]-->}
+    output << "</head><body>"
+  end
+  def footer
+    output = []
+    output << "<div id='generation-date'>Generated at: <span class='date'>#{Time.now.to_s}</span></div>"
+    output << "</body></html>"
+  end
+  
+end

data/test/code/reference_api.rb

@@ -0,0 +1,141 @@
+require 'sinatra/base'
+
+module API
+  class ReferenceAPI < Sinatra::Base 
+
+    ##
+    # :method: get(/:grid5000-resource/versions[.:format])
+    #
+    # :call-seq:
+    #   GET /:grid5000-resource/versions[.:format]
+    # 
+    # Get the list of all versions of a particular resource.
+    #
+    # == URI parameters
+    # <tt>grid5000-resource</tt>:: the URI of the grid5000 resource.
+    # <tt>format</tt>:: the requested format [json,xml] if you do not use the <tt>Accept</tt> header in your HTTP request.
+    # 
+    # == Query parameters
+    # <tt>limit</tt>:: maximum number of versions to return.
+    #
+    # == Content-Types
+    # <tt>application/json</tt>:: JSON
+    # <tt>application/xml</tt>:: XML
+    #
+    # == Status codes
+    # <tt>200</tt>:: OK, the response contains the list of the versions of the requested grid5000 resource.
+    # <tt>404</tt>:: the requested grid5000 resource cannot be found.
+    # <tt>406</tt>:: the requested format is not available.
+    # 
+    # == Usage
+    # Get the 2 latest versions of the Rennes site:
+    #     GET /grid5000/sites/rennes/versions?limit=2 HTTP/1.1
+    #     Accept: application/json
+    #
+    #
+    #     HTTP/1.1 200 OK                                                                  
+    #     Date: Tue, 17 Mar 2009 13:41:45 GMT                                              
+    #     ETag: "0745dc6351cdd00919e8611f8f6952eb48fc9b56"                                 
+    #     Cache-Control: public, max-age=120                                               
+    #     Age: 0                                                                           
+    #     Content-Length: 496                                                              
+    #     Content-Type: application/json;charset=utf-8                                     
+    #     [                                                                                
+    #       {                                                                              
+    #         "message": "Added network interfaces to helios and azur clusters.",          
+    #         "uri": "\/sites\/versions\/29202872636a3f4023b956cc7bba38c15850ec9f",        
+    #         "date": "Tue, 17 Mar 2009 09:28:27 GMT",                                     
+    #         "id": "29202872636a3f4023b956cc7bba38c15850ec9f"                             
+    #       },                                                                             
+    #       {                                                                              
+    #         "message": "Added network interfaces to genepi nodes.",                      
+    #         "uri": "\/sites\/versions\/7edfbafddb08beb8251c543c5c96e5d736bf23fa",        
+    #         "date": "Tue, 17 Mar 2009 09:17:48 GMT",                                     
+    #         "id": "7edfbafddb08beb8251c543c5c96e5d736bf23fa"                             
+    #       }                                                                              
+    #     ]                                                                                
+    #
+    
+    #
+    get '*/versions.:format' do |resource_uri, format|
+
+    end
+    
+    ##
+    # :method: get(/:grid5000-resource/versions/:version[.:format])
+    # 
+    # :call-seq:
+    #   GET /:grid5000-resource/versions/:version[.:format]
+    # 
+    # Get info about a specific version.
+    #
+    # == URI parameters
+    # <tt>grid5000-resource</tt>:: the URI of the grid5000 resource.
+    # <tt>version</tt>:: the version id (40 characters long) or a UNIX timestamp.
+    #
+    # == Content-Types
+    # <tt>application/json</tt>:: JSON
+    # <tt>application/xml</tt>:: XML
+    # 
+    # == Status codes
+    # <tt>200</tt>:: OK.
+    # <tt>404</tt>:: the requested grid5000 resource cannot be found, or the requested version does not exist.
+    # <tt>406</tt>:: the requested format is not available.
+    #
+    
+    #
+    get '*/versions/:version.:format' do |resource_uri, version, format|     
+
+    end
+    
+    ##
+    # :method: get(/:grid5000-resource[.:format])
+    #
+    # :call-seq:
+    #   GET /:grid5000-resource[.:format]
+    # 
+    # Get a specific version of a Grid5000 resource.
+    #
+    # == URI parameters
+    # <tt>grid5000-resource</tt>:: the URI of the grid5000 resource.
+    #
+    # == Query parameters
+    # <tt>version</tt>:: the requested version. It can be a version id (40 characters), 
+    #                    or a UNIX timestamp [default=empty (most recent version is used)].
+    # <tt>depth</tt>:: the number of nested sub-resources to resolve [default=1].
+    # <tt>resolve</tt>:: a list of comma separated sub-resources names to resolve (to be used with the +depth+ parameter) [default=all].
+    #
+    # == Content-Types
+    # <tt>application/json</tt>:: JSON
+    # <tt>application/xml</tt>:: XML
+    # <tt>application/zip</tt>:: the ZIP format will return a zip archive containing the set of directories and files corresponding to the required data, with all its sub-resources.
+    # 
+    # == Status codes
+    # <tt>200</tt>:: OK, the response contains the description of the resource as it was at the requested version.
+    # <tt>404</tt>:: the requested grid5000 resource cannot be found, or the requested version does not exist.
+    # <tt>406</tt>:: Returns 406 if the requested format is not available.
+    #
+    
+    #
+    get '*.:format' do |resource_uri, format|
+
+    end
+    
+    private        
+    
+    def metadata_for_commit(commit, resource_uri)
+      { 
+        'uid' => commit.id,
+        'date' => commit.committed_date.httpdate,
+        'message' => commit.message,
+        'author' => commit.author,
+        'type' => 'version',
+        'links' => [
+          {'rel' => 'self', 'href' => "#{resource_uri}/versions/#{commit.id}"},
+          {'rel' => 'parent', 'href' => "#{resource_uri}?version=#{commit.id}"}
+        ] 
+      }
+    end
+    
+  end # class ReferenceAPI
+end # module API