docurium 0.0.1 → 0.0.2

data/README.md

@@ -4,30 +4,71 @@ Docurium is a lightweight Doxygen replacement.  It generates static HTML from th
 
 I built it to replace the Doxygen generated documentation for the libgit2 project, so I'm only currently testing it against that.  So, it is only known to include support for features and keywords used in that project currently.  If you have a C library project you try this on and something is amiss, please file an issue or better yet, a pull request.
 
+Though Docurium can generate your docs into a subdirectory, it is meant to be served from a webserver, not locally.  It uses XMLHttpRequest calls, which cannot be done locally, so you can't just open the index.html file locally and have it work - you need to either run a webserver in the output directory or push it to a website to view it properly.  I use Pow (pow.cx) or GitHub Pages.
+
 # Usage
 
 Run the `cm` binary and pass it your Docurium config file.
 
     $ cm doc api.docurium
-    * generating header based docs
-      - processing limit.h
-      - processing recess.h
+    * generating docs
+      - processing version v0.1.0
+      - processing version v0.2.0
+      - processing version v0.3.0
+      - processing version v0.8.0
+      - processing version v0.10.0
+      - processing version v0.11.0
+      - processing version v0.12.0
+      - processing version HEAD
+    * checking your api
+      - unmatched params in
+          git_commit_create
+          git_config_set_int
+          git_object_lookup_prefix
+      - signature changes in
+          git_index_get
+          git_repository_path
+          git_tree_entry_byindex
     * output html in docs/
 
-The Docurium config files looks like this:
+Docurium will tell you if you have unmatched @params entries in header docs and if you've changed signatures in functions in HEAD, just to help you know what's happening and if you've written your docs properly.
+
+The Docurium config file looks like this:
 
     {
      "name":   "libgit2",
      "github": "libgit2/libgit2",
      "input":  "include/git2",
      "prefix": "git_",
-     "output": "docs",
+     "branch": "gh-pages",
+     "examples": "examples",
      "legacy":  {
         "input": {"src/git": ["v0.1.0"],
                   "src/git2": ["v0.2.0", "v0.3.0"]}
       }
     }
 
+You can either have a `branch` or an `output` entry - `branch` will write your docs directly into a Git branch, `output` will write them to a subdirectory.
+
+# Installing
+
+    $ gem install docurium
+
+# Screenshots
+
+## Main Page
+
+![Main Page](https://img.skitch.com/20110614-c98pp6c9p9mn35jn4iskjim7hk.png)
+
+Each version of your app has a landing page that lists out all the functions available.  Functions that are new in that version from the previous version are highlighted in green, functions that have changed signatures are in orange.
+
+## Function Page
+
+![Func Page](https://img.skitch.com/20110614-mdasyhip3swxtngwxrce8wqy3h.png)
+
+Each function has a page showing all the relevant info for that function including metadata extracted from Doxygen-style comments.  I also list all the versions of the library that this function is included in and in which versions the signature changed.
+
+
 # Contributing
 
 If you want to fix or change something, please fork on GitHub, push your change to a branch named after your change and send me a pull request.
@@ -37,3 +78,4 @@ If you want to fix or change something, please fork on GitHub, push your change
 MIT, see LICENCE file
 
 
+# vim:ft=markdown

data/TODO.txt

@@ -1,19 +1,13 @@
 TODO
 
-* show unmatched params when compiling HEAD (-w?)
-
 * links to example usage from example docco'd code
 
 
-
-* write directly to branch
-
-* gem-ize
-
-* add to libgit2 project
-
+* fix to group chooser
 
 * only update certain tags / HEAD, force full update
 
+* doc other branches (specify in config file)
+
 * highlight menu item when selected
 

data/bin/cm

@@ -19,6 +19,16 @@ command :doc do |c|
   end
 end
 
+desc 'Generate Docurium config file template'
+long_desc 'Generate Docurium config file template'
+command :gen do |c|
+  c.action do |global_options,options,args|
+    file = args.first || 'api.docurium'
+    Docurium::CLI.gen(file)
+  end
+end
+
+
 pre { |global,command,options,args| true }
 
 post { |global,command,options,args| true }

data/docurium.gemspec

@@ -15,6 +15,8 @@ Gem::Specification.new do |s|
   s.rubyforge_project = 'docurium'
 
   s.add_dependency "version_sorter", "~>1.1.0"
+  s.add_dependency "mustache", ">= 0.99.4"
+  s.add_dependency "rocco", "= 0.7.0"
   s.add_development_dependency "bundler",   "~>1.0"
 
   s.files         = `git ls-files`.split("\n")

data/lib/docurium.rb

@@ -1,10 +1,12 @@
 require 'json'
 require 'tempfile'
 require 'version_sorter'
+require 'rocco'
+require 'docurium/layout'
 require 'pp'
 
 class Docurium
-  Version = VERSION = '0.0.1'
+  Version = VERSION = '0.0.2'
 
   attr_accessor :branch, :output_dir, :data
 
@@ -20,7 +22,7 @@ class Docurium
     @data[:prefix] = option_version(version, 'input', '')
   end
 
-  def option_version(version, option, default)
+  def option_version(version, option, default = nil)
     if @options['legacy']
       if valhash = @options['legacy'][option]
         valhash.each do |value, versions|
@@ -34,23 +36,64 @@ class Docurium
   end
 
   def generate_docs
-    puts "generating docs"
+    out "* generating docs"
     outdir = mkdir_temp
     copy_site(outdir)
     versions = get_versions
     versions << 'HEAD'
     versions.each do |version|
-      puts "generating docs for version #{version}"
+      out "  - processing version #{version}"
       workdir = mkdir_temp
       Dir.chdir(workdir) do
         clear_data(version)
         checkout(version, workdir)
-        puts "parsing headers"
         parse_headers
         tally_sigs(version)
-        File.open(File.join(outdir, "#{version}.json"), 'w+') do |f|
-          f.write(@data.to_json)
+      end
+
+      tf = File.expand_path(File.join(File.dirname(__FILE__), 'docurium', 'layout.mustache'))
+      if ex = option_version(version, 'examples')
+        workdir = mkdir_temp
+        Dir.chdir(workdir) do
+          with_git_env(workdir) do
+            `git rev-parse #{version}:#{ex} 2>&1` # check that it exists
+            if $?.exitstatus == 0
+              out "  - processing examples for #{version}"
+              `git read-tree #{version}:#{ex}`
+              `git checkout-index -a`
+
+              files = []
+              Dir.glob("**/*") do |file|
+                next if !File.file?(file)
+                files << file
+              end
+              files.each do |file|
+                out "    # #{file}"
+                rocco = Rocco.new(file, files, {:language => 'c'})
+                rocco_layout = Rocco::Layout.new(rocco, tf)
+                rocco_layout.version = version
+                rf = rocco_layout.render
+                rf_path = File.basename(file).split('.')[0..-2].join('.') + '.html'
+                rel_path = "ex/#{version}/#{rf_path}"
+                rf_path = File.join(outdir, rel_path)
+                FileUtils.mkdir_p(File.dirname(rf_path))
+                File.open(rf_path, 'w+') do |f|
+                  @data[:examples] ||= []
+                  @data[:examples] << [file, rel_path]
+                  f.write(rf)
+                end
+              end
+            end
+          end
         end
+
+        if version == 'HEAD'
+          show_warnings
+        end
+      end
+
+      File.open(File.join(outdir, "#{version}.json"), 'w+') do |f|
+        f.write(@data.to_json)
       end
     end
 
@@ -66,10 +109,26 @@ class Docurium
       end
     end
 
-    if @options['branch']
-      write_branch
+    if br = @options['branch']
+      out "* writing to branch #{br}"
+      ref = "refs/heads/#{br}"
+      with_git_env(outdir) do
+        psha = `git rev-parse #{ref}`.chomp
+        `git add -A`
+        tsha = `git write-tree`.chomp
+        puts "\twrote tree   #{tsha}"
+        if(psha == ref)
+          csha = `echo 'generated docs' | git commit-tree #{tsha}`.chomp
+        else
+          csha = `echo 'generated docs' | git commit-tree #{tsha} -p #{psha}`.chomp
+        end
+        puts "\twrote commit #{csha}"
+        `git update-ref -m 'generated docs' #{ref} #{csha}`
+        puts "\tupdated #{br}"
+      end
     else
       final_dir = File.join(@project_dir, @options['output'] || 'docs')
+      out "* output html in #{final_dir}"
       FileUtils.mkdir_p(final_dir)
       Dir.chdir(final_dir) do
         FileUtils.cp_r(File.join(outdir, '.'), '.') 
@@ -77,6 +136,32 @@ class Docurium
     end
   end
 
+  def show_warnings
+    out '* checking your api'
+
+    # check for unmatched paramaters
+    unmatched = []
+    @data[:functions].each do |f, fdata|
+      unmatched << f if fdata[:comments] =~ /@param/
+    end
+    if unmatched.size > 0
+      out '  - unmatched params in'
+      unmatched.sort.each { |p| out ("\t" + p) }
+    end
+
+    # check for changed signatures
+    sigchanges = []
+    @sigs.each do |fun, data|
+      if data[:changes]['HEAD']
+        sigchanges << fun
+      end
+    end
+    if sigchanges.size > 0
+      out '  - signature changes in'
+      sigchanges.sort.each { |p| out ("\t" + p) }
+    end
+  end
+
   def get_versions
     VersionSorter.sort(git('tag').split("\n"))
   end
@@ -116,11 +201,17 @@ class Docurium
   end
 
   def checkout(version, workdir)
+    with_git_env(workdir) do
+      `git read-tree #{version}:#{@data[:prefix]}`
+      `git checkout-index -a`
+    end
+  end
+
+  def with_git_env(workdir)
     ENV['GIT_INDEX_FILE'] = mkfile_temp
     ENV['GIT_WORK_TREE'] = workdir
     ENV['GIT_DIR'] = File.join(@project_dir, '.git')
-    `git read-tree #{version}:#{@data[:prefix]}`
-    `git checkout-index -a`
+    yield
     ENV.delete('GIT_INDEX_FILE')
     ENV.delete('GIT_WORK_TREE')
     ENV.delete('GIT_DIR')
@@ -398,11 +489,6 @@ class Docurium
     block.strip
   end
 
-  def write_branch
-    puts "Writing to branch #{@branch}"
-    puts "Done!"
-  end
-
   def mkdir_temp
     tf = Tempfile.new('docurium')
     tpath = tf.path
@@ -414,13 +500,11 @@ class Docurium
   def mkfile_temp
     tf = Tempfile.new('docurium-index')
     tpath = tf.path
-    tf.close
+    tf.unlink
     tpath
   end
 
-
   def copy_site(outdir)
-    puts "Copying site files to temp path (#{outdir})"
     here = File.expand_path(File.dirname(__FILE__))
     FileUtils.mkdir_p(outdir)
     Dir.chdir(outdir) do
@@ -429,7 +513,11 @@ class Docurium
   end
 
   def write_dir
-    puts "Writing to directory #{output_dir}"
-    puts "Done!"
+    out "Writing to directory #{output_dir}"
+    out "Done!"
+  end
+
+  def out(text)
+    puts text
   end
 end

data/lib/docurium/cli.rb

@@ -6,5 +6,22 @@ class Docurium
       doc.generate_docs
     end
 
+    def self.gen(file)
+
+temp = <<-TEMPLATE
+{
+ "name":   "project",
+ "github": "user/project",
+ "input":  "include/lib",
+ "prefix": "lib_",
+ "output": "docs"
+}
+TEMPLATE
+      puts "Writing to #{file}"
+      File.open(file, 'w+') do |f|
+        f.write(temp)
+      end
+    end
+
   end
 end

data/lib/docurium/layout.mustache

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>{{ title }}</title>
+  <link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
+</head>
+<body>
+<div id='container'>
+  <div id="background"></div>
+  <div id="jump_to">
+    Jump To &hellip;
+    <div id="jump_wrapper">
+      <div id="jump_page">
+        <a class="source" href="../../#{{ version }}">API Docs</a>
+        {{#sources}}
+          <a class="source" href="{{ url }}">{{ basename }}</a>
+        {{/sources}}
+      </div>
+    </div>
+  </div>
+  <table cellspacing=0 cellpadding=0>
+  <thead>
+    <tr>
+      <th class=docs><h1>{{ title }}</h1></th>
+      <th class=code></th>
+    </tr>
+  </thead>
+  <tbody>
+    {{#sections}}
+    <tr id='section-{{ section_id }}'>
+      <td class=docs>
+        <div class="pilwrap">
+          <a class="pilcrow" href="#section-{{ section_id }}">&#182;</a>
+        </div>
+        {{{ docs }}}
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>{{{ code }}}</pre></div>
+      </td>
+    </tr>
+    {{/sections}}
+  </table>
+</div>
+</body>

data/lib/docurium/layout.rb

@@ -0,0 +1,7 @@
+# adding some stuff I need
+class Rocco::Layout
+  attr_accessor :version
+  def version
+    @version
+  end
+end

data/site/index.html

@@ -53,7 +53,7 @@
   <div id="footer-wrapper">
     <div id="footer">
       <div class="left-col">
-        Powered by Docurium<br/>
+        Powered by <a href="https://github.com/schacon/docurium">Docurium</a><br/>
         Sponsored by GitHub<br/>
         <br/>
       </div>

data/site/js/docurium.js

@@ -482,6 +482,22 @@ $(function() {
       filelist.hide()
       menu.append(filelist)
 
+      // Examples List
+      if(data['examples'].length > 0) {
+        title = $('<h3><a href="#">Examples</a></h3>').click( this.collapseSection )
+        menu.append(title)
+        filelist = $('<ul>')
+        _.each(data['examples'], function(file) {
+          fname = file[0]
+          fpath = file[1]
+          flink = $('<a>').attr('href', fpath).append(fname)
+          fitem = $('<li>')
+          fitem.append(flink)
+          filelist.append(fitem)
+        }, this)
+        menu.append(filelist)
+      }
+
       list = $('#files-list')
       list.empty()
       list.append(menu)
@@ -603,6 +619,7 @@ $(function() {
     },
 
     changelog: function(version, tname) {
+      docurium.setVersion()
       docurium.showChangeLog()
     },
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: docurium
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: false
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Scott Chacon
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-13 00:00:00 -07:00
+date: 2011-06-14 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -35,9 +35,41 @@ dependencies:
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: bundler
+  name: mustache
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 411
+        segments: 
+        - 0
+        - 99
+        - 4
+        version: 0.99.4
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rocco
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        - 7
+        - 0
+        version: 0.7.0
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -48,7 +80,7 @@ dependencies:
         - 0
         version: "1.0"
   type: :development
-  version_requirements: *id002
+  version_requirements: *id004
 description: A simpler, prettier Doxygen replacement.
 email: 
 - schacon@gmail.com
@@ -68,6 +100,8 @@ files:
 - docurium.gemspec
 - lib/docurium.rb
 - lib/docurium/cli.rb
+- lib/docurium/layout.mustache
+- lib/docurium/layout.rb
 - site/css/style.css
 - site/images/search_icon.png
 - site/index.html