shomen 0.1.0

data/.ruby

@@ -0,0 +1,43 @@
+---
+authors:
+- name: Thomas Sawyer
+  email: transfire@gmail.com
+copyrights: []
+replacements: []
+conflicts: []
+requirements:
+- name: rdoc
+  version: 3~
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: reap
+  groups:
+  - build
+  development: true
+dependencies: []
+repositories:
+- uri: git://github.com/rubyworks/shomen.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubyworks.github.com/shomen
+  work: http://github.com/rubyworks/shomen
+  docs: http://github.com/rubyworks/shomen/wiki
+load_path:
+- lib
+extra:
+  manifest: MANIFEST
+source: []
+alternatives: []
+revision: 0
+name: shomen
+title: Shomen
+summary: Standardized Object-Oriented Documentation Model
+created: '2010-07-01'
+description: Shomen defines a standard API documentaiton format for object-oriented
+  software (Ruby programs in particular) which can be used by documentation interfaces,
+  e.g. Hypervisor, to render API documentation
+version: 0.1.0
+date: '2011-10-05'

data/.yardopts

@@ -0,0 +1,7 @@
+--private
+--protected
+-r README.rdoc
+lib/
+-
+[A-Z]*.*
+log/[A-Z].*

data/HISTORY.rdoc

@@ -0,0 +1,10 @@
+= RELEASE HISTORY
+
+== 0.1.0 | 2011-09-27
+
+This is the initial public release of Shomen.
+
+Changes:
+
+* Happy Release Day! You've been a long time in the making.
+

data/NOTES.rdoc

@@ -0,0 +1,5 @@
+= DEVELOPER NOTES
+
+== RDoc Dependency
+
+Though this could probably work with RDoc 2.4.2+, I have set the dependency to 2.5~.

data/README.rdoc

@@ -0,0 +1,68 @@
+= Shomen
+
+{Website}[http://rubyworks.github.com/shomen] |
+{User Manual}[http://github.com/rubyworks/shomen/wiki] |
+{Development}[http://github.com/rubyworks/shomen]
+
+
+== Description
+
+Shomen is an intermediary documentation model designed for documenting
+object-oriented programming languages, particularly Ruby. The specification
+is a flat mapping, without internal referencing, suitable for storage in both
+YAML and JSON formats.
+
+
+== Why?
+
+By using a standard intermediary format, documentation parsers need only concern
+themselves with a single output target. And documentation templates in turn only
+need to concern themselves with a single input format to use regardless of the
+parsing system that was used to generate it.
+
+
+== Features
+
+* Update a single portable file to update documentation.
+* Site disc footprint is extra small thanks to CDNs.
+* Personalize site design to best fit your project.
+* Test drive other's customizations with your own remote docs!
+
+
+== Learn
+
+To learn more about shomen please vist:
+
+* http://rubyworks.github.com/shomen
+* http://github.com/rubyworks/shomen/wiki
+
+
+== Usage
+
+Shomen currently supports parsing via RDoc and YARD. Specify the parser to
+use to the shomen command, e.g.
+
+  $ shomen rdoc lib [A-Z]*.* -m README.rdoc > site/doc.json
+
+If a `.document` file exists, of course, the file globs can be omitted.
+For yard it's basically the same deal.
+
+  $ shomen yard lib [A-Z]*.* -r README.rdoc > site/doc.json
+
+YARD will use `.yardopts` if it is present, so you genetally do not need to
+to specify any parameters, e.g.
+
+  $ shomen yard > site/doc.json
+
+Now that you have a Shomen documentation file for you project, you simply need 
+to pair it up with a viewer. Currently that means using {HyperVisor}[http://github.com/rubyworks/hypervisor].
+
+
+
+== Copying
+
+Copyright (c) 2010 Thomas Sawyer
+
+Shomen is distributed under the terms of the BSD-2-Clause license.
+
+See COPYING.rdoc for license details.

data/bin/shomen

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'shomen/cli'
+Shomen.cli(*ARGV)

data/lib/shomen.yml

@@ -0,0 +1,43 @@
+---
+authors:
+- name: Thomas Sawyer
+  email: transfire@gmail.com
+copyrights: []
+replacements: []
+conflicts: []
+requirements:
+- name: rdoc
+  version: 3~
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: reap
+  groups:
+  - build
+  development: true
+dependencies: []
+repositories:
+- uri: git://github.com/rubyworks/shomen.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubyworks.github.com/shomen
+  work: http://github.com/rubyworks/shomen
+  docs: http://github.com/rubyworks/shomen/wiki
+load_path:
+- lib
+extra:
+  manifest: MANIFEST
+source: []
+alternatives: []
+revision: 0
+name: shomen
+title: Shomen
+summary: Standardized Object-Oriented Documentation Model
+created: '2010-07-01'
+description: Shomen defines a standard API documentaiton format for object-oriented
+  software (Ruby programs in particular) which can be used by documentation interfaces,
+  e.g. Hypervisor, to render API documentation
+version: 0.1.0
+date: '2011-10-05'

data/lib/shomen/cli.rb

@@ -0,0 +1,22 @@
+module Shomen
+
+  # Command line interface. (YARD oriented for now).
+  def self.cli(*argv)
+    case cmd = argv.shift
+    when 'server'
+      require 'shomen/server'
+    when 'tomdoc'
+      require 'shomen/cli/tomdoc'
+      CLI::TomDocCommand.run(*argv)
+    when 'yard'
+      require 'shomen/cli/yard'
+      CLI::YARDCommand.run(*argv)
+    when 'rdoc'
+      require 'shomen/cli/rdoc'
+      CLI::RDocCommand.run(*argv)
+    else
+      abort "error: unrecognized command - #{cmd}"
+    end
+  end
+
+end

data/lib/shomen/cli/abstract.rb

@@ -0,0 +1,120 @@
+module Shomen
+
+  begin; gem 'json'; rescue; end
+
+  require 'optparse'
+  require 'yaml'
+  require 'json'
+
+  module CLI
+
+    # Command line interface base class.
+    #
+    class Abstract
+
+      #
+      def self.run(*arg)
+        new.run(*argv)
+      end
+
+      #
+      def parse(argv, *choices)
+        options = (Hash === choices.last ? choices.pop : {})
+        parser  = OptionParser.new
+
+        choices.each do |choice|
+          send("option_#{choice}", parser, options)
+        end
+        option_debug(parser, options)
+        option_warn(parser, options)
+        option_help(parser, options)
+
+        parser.parse!(argv)
+
+        return options
+      end
+
+=begin
+      #
+      def option_yaml(parser, options)
+        parser.on('-y', '--yaml', 'output YAML instead of JSON') do
+          options[:format] = 'yaml'
+        end
+      end
+
+      #
+      def option_json(parser, options)
+        parser.on('-j', '--json', 'output JSON instead of YAML (default)') do
+          options[:format] = 'json'
+        end
+      end
+=end
+
+      #
+      def option_format(parser, options)
+        parser.on('-f', '--format NAME') do |format|
+          options[:format] = format
+        end
+      end
+
+      #
+      def option_source(parser, options)
+        parser.on('-s', '--[no-]source', 'include full source in script documentation') do |bool|
+          Shomen.source = bool
+        end
+      end
+
+      #
+      def option_force(parser, options)
+        parser.on('-f', '--force') do
+          options[:force] = true
+        end
+      end
+
+      #
+      def option_debug(parser, options)
+        parser.on_tail('-D', '--debug', 'run with $DEBUG set to true') do
+          $DEBUG = true
+        end
+      end
+
+      #
+      def option_warn(parser, options)
+        parser.on_tail('-W', '--warn', 'run with $VERBOSE set to true') do
+          $VERBOSE = true
+        end
+      end
+
+      #
+      def option_help(parser, options)
+        parser.on_tail('--help') do
+          puts opt
+          exit 0
+        end
+      end
+
+      #
+      def root?
+        root = false
+        root = true if File.exist?('.ruby')
+        root = true if File.exist?('.yardoc')
+        root = true if File.exist?('.git')
+        root = true if File.exist?('.hg')
+        root
+      end
+
+    end
+
+  end
+
+  #
+  def self.source?
+    @source
+  end
+
+  #
+  def self.source=(bool)
+    @source = bool
+  end
+
+end

data/lib/shomen/cli/rdoc.rb

@@ -0,0 +1,122 @@
+module Shomen
+
+  begin; gem 'json'; rescue; end
+
+  require 'shomen/cli/abstract'
+  require 'tmpdir'
+  require 'json'
+
+  module CLI
+
+    # RDoc command line interface.
+    class RDocCommand < Abstract
+
+      #
+      def self.run(*argv)
+        new.run(argv)
+      end
+
+      # New RDoc command line interface.
+      def initialize
+        begin
+          gem 'rdoc'
+        rescue
+        end
+      end
+
+      #
+      def run(argv)
+        require 'shomen/rdoc'
+
+        defaults = {}
+        defaults[:format]  = :json
+        defaults[:force]   = false
+        defaults[:source]  = true
+
+        options = parse(argv, :format, :force, :visibility, :main, :source, defaults)
+
+        if !options[:force] && !root?
+          $stderr.puts "Not a project directory. Use --force to override."
+          exit -1
+        end
+
+        if argv.empty?
+          if File.exist?('.document')
+            files = File.read('.document').split("\n")
+            files = files.reject{ |f| f.strip == '' or f.strip =~ /^\#/ }
+            files = files.map{ |f| Dir[f] }.flatten
+          else
+            files = ['lib']
+          end
+        else
+          files = argv
+        end
+
+        tmpdir     = File.join(Dir.tmpdir, 'shomen-rdoc')
+        main       = options[:main] || Dir.glob('{README.*,README}').first
+        visibility = options[:visibility].to_s
+
+        # TODO: Any way to supress the cretion of the time stamp altogether?
+        # Options#update_output_dir for instance?
+
+        # TODO: Using the ::RDoc::Options doesn't seem to work.
+        # It complains about a template being nil in `rdoc/options.rb:760`.
+
+        #rdoc_options = ::RDoc::Options.new
+        #rdoc_options.generator = 'shomen'
+        #rdoc_options.main_page = Dir.glob('README*').first
+        ##rdoc_options.template  = 'shomen'
+        ##rdoc_options.template_dir = File.dirname(__FILE__)
+        #rdoc_options.op_dir    = 'tmp/rdoc'  # '/dev/null'
+        #rdoc_options.files     = files
+
+        rdoc_options  = []
+        rdoc_options += ['-q']
+        #rdoc_options += ['-t', title]
+        rdoc_options += ['-f', 'shomen']
+        rdoc_options += ['-m', main] if main
+        rdoc_options += ['-V', visibility]
+        rdoc_options += ['-o', tmpdir]  # '/dev/null'
+        rdoc_options += files
+
+        rdoc = ::RDoc::RDoc.new
+        rdoc.document(rdoc_options)
+
+        case options[:format]
+        when :yaml
+          $stdout.puts(rdoc.generator.shomen.to_yaml)
+        else
+          $stdout.puts(JSON.generate(rdoc.generator.shomen))
+        end
+      end
+
+      #
+      def option_visibility(parser, options)
+        parser.on('--private', 'include public, protected and private methods') do
+          options[:visibility] = :private
+        end
+        parser.on('--protected', 'include public and protected methods') do
+          options[:visibility] = :protected
+        end
+      end
+
+      #
+      #def option_document(parser, options)
+      #  parser.on('--document FILE') do |file|
+      #    options[:document] = file
+      #  end
+      #end
+
+      #
+      def option_main(parser, options)
+        parser.on('-m', '--main FILE') do |file|
+          options[:main] = file
+        end
+      end
+
+      # TODO: Add support for additional options supported by rdoc.
+    end
+
+  end
+
+end