nandoc 0.0.3 → 0.0.4

data/README

@@ -1,5 +1,4 @@
-<embed
-  style='position: absolute; right:0; top:0'
+<embed id='sunburst'
   src="svg/less-fonts.svg" width="150px" height="150px"
   type="image/svg+xml"
   pluginspage="http://www.adobe.com/svg/viewer/install/" />
@@ -9,7 +8,7 @@ this is a hack. this is nanDoc.
 
 ## Summary
 
-hack of [nanoc3](http://nanoc.stoneship.org) to generate a static site of your ruby project from your README etc.
+hack of [nanoc3](http://nanoc.stoneship.org) to generate a static site of your (command-line) ruby project from your README etc.
 
 ## Description
 
@@ -65,10 +64,12 @@ To hack, try something like this:
     ~/tmp/nandoc > gem install -n ~/bin pkg/nandoc-0.0.0.gem
     ~~~
 
+before actually trying to use it, if you get that far, please read this [proviso](/proviso).
+
 
 ## Usage Summary
 
-Start with  a markdown-formatted README file:
+Start with a markdown-formatted README file:
 
 (see: test.rb - "basic usage -- readme")
 

data/Rakefile

@@ -17,7 +17,7 @@ Jeweler::Tasks.new do |s|
   s.summary = NanDoc::ParseReadme.summary('README')
 
   s.add_dependency 'nanoc3', '~> 3.1.2'
-  s.add_dependency 'treebis', '~> 0.0.1'
+  s.add_dependency 'treebis', '~> 0.0.2'
   s.add_dependency 'syntax', '~> 1.0.0'
 end
 

data/bin/nandoc

@@ -1,5 +1,6 @@
 #!/usr/bin/env ruby
-$LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+# $LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+# above should be avoided when doing symlink hack
 
 require 'nandoc'
 

data/doc/FAQ.md

@@ -1,6 +1,9 @@
 # Frequently Asked Questions
 <span style='font-size: 0.9em'><em>I can't walk 2 blocks outside my home without some stranger coming up to me and asking me one or more of these questions.</em></span>
 
+## Q: What about other test frameworks?
+<p class='answer'>A: If you think you can patch nanDoc (SpecDoc) to work with your favorite testing framework, patches welcome!</p>
+
 ## Q: Why not jekyll?
 <p class='answer'>A: I started this knowing nothing about jekyll.  nanoc3 found me and i was already acquainted with its author and i liked what i saw so i just ran with it without doing a broad survey of other solutions.  At the time of this writing i still don't really know jekyll. @todo</p>
 

data/doc/PROVISO.md

@@ -0,0 +1,39 @@
+# nanDoc
+
+## proviso
+
+
+### nanDoc is not nandoc
+
+nanDoc is affiliated with nanoc by name only.  They are separate projects with separate authors.  Negative experiences with nan<em>Doc</em> should not inform your pre-judgement of nan<em>oc</em> and vice versa.  (Positive experiences, however, should ;)
+
+There is a uni-directional dependency upon nanoc by nanDoc.  In nature this is classified as a parasitic as opposed to symbiotic relationship.
+
+(-may 15, 2010)
+
+
+### nanDoc is alpha software
+
+nanDoc is an experimental means to an end.  I need a way to integrate code in my tests ("specs") with documentation generation to make sites like this for 4 or 5 of my gems.  (If others find it useful along the way, ponies.)
+
+breif discussions with the author of nanoc have lead me to believe that this use might be better served by looking at the `@example` tag available in YARD and [custom templates](http://gnuu.org/2009/11/18/customizing-yard-templates/) as opposed to going batshit insane with my wild hacks as i have thus far done;
+but i do not have time to get up to speed on YARD now, much less overhaul nanDoc.
+
+I find it equally likely that I won't like the YARD way and i will prefer the nanDoc way and i, like frank sinatra, will be glad i did it my way but this is all speculation at this point.  Unfortunately i have no way of knowing what future me will think of present me, except that he will be jealous of how much hair I had back then.
+
+i will to try to adhere to the [semantic versioning](http://semver.org/) standard for nanDoc versions.  Fortunately for me and nanDoc at this point,
+it states that:
+
+> Major version zero (0.y.z) is for initial development. Anything may change
+> at any time. The public API should not be considered stable.
+
+This holds especially true for nanDoc which is very experimental and very much in flux for the time being, and as such will be in major and minor version zero for at least the next few months.
+
+If, however, *anyone* uses nanDoc and finds some functionality of it *at all* useful, pls [email](<mailto:chip.malice@gmail.com>) me (or better yet ping `hipe` on [irc](irc://chat.freenode.net/#ruby-lang)) and I will very likely bake that functionality into what will ultimately become the public api for nanDoc.
+
+(-may 13, 2010)
+
+
+
+
+&#10087;

data/doc/commands/diff.md

@@ -0,0 +1,49 @@
+# NanDoc
+
+## Commands
+
+### `diff`
+
+The diffing command is intended primarily as an internal development tool for me, in order to push and pull assets between my compiled site (the `my-site/output` folder), my content files of my site, (the `my-site/content` folder), and the assests modeled in the nanDoc site prototypes.
+
+
+<div class='sidebar-right'>
+
+<h4>push and pull?</h4>
+
+<p>
+<code>push</code> and <code>pull</code> don't have the typicical frame of reference here since there's no central server, just nodes on your filesystem.  But their usage here corresponds to whether the direction in the flow of information is going <em>with</em> or <em>against</em> the "typical" direction.
+</p>
+
+<p>
+The typical direction is <em>from</em> the nandoc site prototype <em>to</em> your <code>my-site/content</code> directory (when you first create the nanDoc site), and then (with the nanoc3 <code>compile</code> command) <em>from</em> the content directory _to_ the output directory.  When you are changing files <em>down</em>on (or <em>later</em> in, or <em>to the right</em> of) this chain with new information from files <code>up</code> in this chain, i call it "<em>pushing</em>", else "<em>pulling</em>".  I think.
+</p>
+
+</div>
+
+
+However, end users may find this command useful for the following:
+
+* fix your css files in your output/ directory, then once you get them right, pull that change back into your content/ directory, so the next time you `nandoc co` (compile) it will create css files with this new css. (@todo what is the normal nanoc workflow for this?)
+
+* if you get a new version of nanDoc or somehow elsewise have a new site prototype, you can review and push changes from the new assets in the prototype to the assets in your `content/` directory.
+
+
+#### pulling css from output back to content folders
+
+This is most commonly what I use diffing for, so it is the easiest to type out, because the default destination node is the content directory, and the default subset node to compare is the css folder.
+
+<div class='clear'></div>
+
+
+For now, I must refer you to this jibber jabber:
+
+from the command line:
+~~~
+~/my-gem/my-site/ > nandoc help diff
+@todo
+~~~
+
+gotta go!
+
+&#10087;

data/doc/svg/less-fonts.svg

@@ -3,8 +3,8 @@
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
 <!-- Generated by hipe version 0.0.0 (20100126.1600)
  -->
-<svg width="175" height="175"
- viewBox="0.00 0.00 175.00 175.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<svg width="175" height="150"
+ viewBox="0.00 0.00 150.00 175.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
 <g id="blah1" class="whatevs" transform="scale(1 1) rotate(0) translate(0 0)">
 <title>this_some_awesome_thing</title>
 <polygon fill="white" stroke="white" points="5,140 5,0 140,0 140,140 5,140"/>

data/lib/nandoc/cli/README.md

@@ -0,0 +1,6 @@
+## hack free zone
+
+The intended audience of this document is developers of nanDoc, not developers using nanDoc.
+
+This tiny cli library is hereby declared as a `hack free zone`
+What that means will be defined in @todo link

data/lib/nandoc/cli/command-methods.rb

@@ -0,0 +1,38 @@
+module NanDoc
+  module Cli
+    module CommandMethods
+      # @depends none
+
+      def command_name
+        (/::([_a-z0-9]+)\Z/i =~ self.class.to_s and base = $1) or fail('no')
+        base.gsub(/([a-z])([A-Z])/){ "#{$1}-#{$2}" }.downcase
+      end
+      def invite_to_more_command_help
+        "see `nandoc help #{command_name}` for more information."
+      end
+      def command_path_assert name, *paths
+        paths.each do |p|
+          unless File.exist?(p)
+            command_abort("#{name} does not exist: #{p}")
+          end
+        end
+      end
+      def invocation_name
+        File.basename($PROGRAM_NAME)
+      end
+      def command_abort msg=nil
+        if msg.nil?
+          tail = 'Aborting.'
+        elsif msg.index("for more info") # not mr. right, mr. right now
+          tail = ''
+        else
+          last = msg[-1].chr
+          tail = ".?!".index(last) ? '  ' : ("\n"==last ? '' : '.  ')
+          tail << 'Aborting.'
+        end
+        $stderr.puts "nanDoc: #{msg}#{tail}"
+        exit 1
+      end
+    end
+  end
+end

data/lib/nandoc/cli/option-methods/exclusive-options.rb

@@ -0,0 +1,56 @@
+module NanDoc
+  module Cli
+    class ExclusiveOptions
+      include OptionMethods
+      def initialize &block
+        @exclusive_flag_keys = nil
+        @default_short = nil
+        @default_key = nil
+        @notice_stream = $stderr
+        instance_eval(&block)
+        fail('definition block needs at least flags()') unless
+          @exclusive_flag_keys
+      end
+      def flags * exclusive_flag_keys
+        @exclusive_flag_keys = exclusive_flag_keys
+      end
+      # params: [short_name_string] name_key
+      def default *a
+        if a.first.kind_of?(String)
+          @default_short = a.shift
+        end
+        if a.first.kind_of?(Symbol)
+          @default_key = a.shift
+        else
+          fail("bad args: #{a.first.inspect}")
+        end
+        fail("extra args: #{a.inspect}") if a.any?
+      end
+      def notice_stream mixed
+        @notice_stream = mixed
+      end
+      def parse cmd, opts
+        these = @exclusive_flag_keys & opts.keys
+        if these.empty? && @default_key
+          if @notice_stream
+            msg =
+            ["using default: "+unnormalize_opt_key(@default_key),
+              @default_short ? "(#{@default_short})" : nil
+            ].compact.join(' ')
+            @notice_stream.puts msg
+          end
+          these.push(@default_key)
+        end
+        if these.size > 1
+          flags = unnormalize_opt_keys(@exclusive_flag_keys)
+          cmd.command_abort <<-ABORT.gsub(/^  */,'')
+            #{flags.join(' and ')} are mutually exclusive.
+            usage: #{cmd.usage}
+            #{cmd.invite_to_more_command_help}
+          ABORT
+        end
+        these.first
+      end
+    end
+  end
+end

data/lib/nandoc/cli/option-methods/option-enum.rb

@@ -0,0 +1,64 @@
+require 'nandoc/support/string-methods'
+
+module NanDoc::Cli::OptionMethods
+  class OptionEnum
+
+    # @todo are we using this?
+
+    include NanDoc::StringMethods # oxford_comma
+
+    def initialize(&block)
+      instance_eval(&block)
+    end
+    def command cmd
+      @command = cmd
+    end
+    def default str
+      @default = str
+    end
+    def name name
+      @name = name
+    end
+    def parse opts
+      found = nil
+      if opts.key?(@name)
+        v = opts[@name]
+        re = /\A#{Regexp.escape(v)}/
+        founds = @values.grep(re)
+        case founds.size
+          when 0; invalid(v)
+          when 1; found = founds.first
+          else found = founds.detect{|f| f==v} or too_many(founds)
+        end
+      elsif(@default)
+        found = @default
+      else
+        found = nil
+      end
+      opts[@name] = found if found # normalize short versions
+      found
+    end
+    def values *v
+      v = v.first if v.size==1 && Array === v
+      @values = v
+    end
+  private
+    def coda
+      "usage: #{@command.usage}\n#{@command.invite_to_more_command_help}"
+    end
+    def invalid val
+      @command.command_abort("invalid value #{val.inspect} for "<<
+        "#{long_name}. #{valid_values_are}\n#{coda}")
+    end
+    def long_name
+      unnormalize_opt_key(@name)
+    end
+    def too_many these
+      @command.command_abort("did you mean " <<
+        oxford_comma(these,' or ', &quoted)<<" for #{long_name}?\n#{coda}")
+    end
+    def valid_values_are
+      "valid values are " << oxford_comma(@values,&quoted)
+    end
+  end
+end

data/lib/nandoc/cli/option-methods.rb

@@ -0,0 +1,35 @@
+module NanDoc
+  module Cli
+    module OptionMethods
+      #
+      # only call this if you are like a ::Cri::Command object with
+      # all the nanDoc hacks. ick.  This is a temprary hack.  Trollop et al
+      # do this better.
+      #
+      def exclusive_opt_flags opts, &block
+        require File.dirname(__FILE__)+'/option-methods/exclusive-options.rb'
+        ExclusiveOptions.new(&block).parse(self, opts)
+      end
+      def normalize_opts opts
+        opts = opts.dup
+        opts.keys.select{|x| x.to_s.index('-') }.each do |k|
+          opts[normalize_opt_key(k)] = opts.delete(k)
+        end
+        opts
+      end
+      def option_enum
+        require File.dirname(__FILE__)+'/option-methods/option-enum.rb'
+        OptionEnum
+      end
+      def normalize_opt_key k
+        k.to_s.gsub('-','_').to_sym
+      end
+      def unnormalize_opt_keys keys
+        keys.map{|x| unnormalize_opt_key(x)}
+      end
+      def unnormalize_opt_key key
+        "--#{key.to_s.gsub('_','-')}"
+      end
+    end
+  end
+end

data/lib/nandoc/cli.rb

@@ -0,0 +1,3 @@
+me = File.dirname(__FILE__)
+require me + '/cli/command-methods.rb'
+require me + '/cli/option-methods.rb'

data/lib/nandoc/commands/create-nandoc-site.rb

@@ -7,7 +7,8 @@ module NanDoc
     #
 
 
-    include OptsNormalizer, TaskCommon, CliCommandHelpers
+    include Cli::CommandMethods
+    include Cli::OptionMethods
 
     def name; 'create_nandoc_site' end
 
@@ -95,10 +96,10 @@ module NanDoc
       # not sure where to put this
       initiate_the_supreme_hack_of_the_standard_error_stream
 
-      task_abort("you can't have both -M and -m") if
+      command_abort("you can't have both -M and -m") if
         opts[:merge_hack] && opts[:merge_hack_reverse]
       if opts[:datasource]
-        task_abort <<-ABO.gsub(/\n */,"\n").strip
+        command_abort <<-ABO.gsub(/\n */,"\n").strip
         for now datasource is hardcoded to be nandoc.
         usage: #{usage}
         ABO
@@ -116,10 +117,6 @@ module NanDoc
       $stderr.puts(*a)
     end
 
-    def my_exit
-      exit(1);
-    end
-
     #
     # see SupremeStderrHack
     #
@@ -138,7 +135,7 @@ module NanDoc
     def prototype_determine opts
       proto_name = opts[:prototype] || 'default'
       require 'nandoc/support/treebis-extlib' # experimental
-      proto_path = "#{NanDoc::Root}/proto/#{proto_name}"
+      proto_path = "#{Config.proto_path}/#{proto_name}"
       @treebis_task = Treebis.dir_task(proto_path)
     end
 
@@ -159,18 +156,18 @@ module NanDoc
       if args.empty?
         err "missing <path> argument."
         err usage
-        my_exit
+        command_abort
       end
       if args.size > 1
         err "Too many arguments"
         err usage
-        my_exit
+        command_abort
       end
       path = args.first
       if File.exist?(path) && Dir[path+'/*'].any?
         err "folder already exists (no merge yet): #{path}"
         err usage
-        my_exit
+        command_abort
       end
       if ! File.exist?(path)
         fu = Config.file_utils
@@ -184,7 +181,7 @@ module NanDoc
     def site_already_exists opts, args
       path = args.first
       if ! (opts[:merge_hack] || opts[:merge_hack_reverse])
-        task_abort <<-FOO.gsub(/^ +/,'').chop
+        command_abort <<-FOO.gsub(/^ +/,'').chop
           A site at '#{path}' already exists.
           If you want to try and merge in changes from the site generator
           (this might just generate a diff), try the --merge-hack (-m) option.

data/lib/nandoc/commands/diff.rb

@@ -6,7 +6,10 @@ require support + '/site-methods.rb'
 module NanDoc::Commands
   class Diff < ::Cri::Command
     NanDoc.persistent_delegate_to(self) # persistent_set(), persistent_get()
-    include NanDoc::CliCommandHelpers, NanDoc::PathTardo, NanDoc::SiteMethods
+    include NanDoc::Cli::CommandMethods
+    include NanDoc::Cli::OptionMethods
+    include NanDoc::PathTardo
+    include NanDoc::SiteMethods
 
     def name; 'diff' end
 
@@ -95,7 +98,7 @@ module NanDoc::Commands
       path_src = deduce_subfolder_path site_path, src
       path_dst = deduce_subfolder_path site_path, dest
       if path_src == path_dst
-        task_abort("source and destination paths are the same. "<<
+        command_abort("source and destination paths are the same. "<<
         "did you forget -p or -P ?\nusage: #{usage}\n"<<
         invite_to_more_command_help)
       end
@@ -123,7 +126,7 @@ module NanDoc::Commands
 
     def deduce_layout_paths src, dest, site_path
       if [src, dest].index(:output)
-        task_abort "Sorry, it doesn't make sense to look at layout " <<
+        command_abort "Sorry, it doesn't make sense to look at layout " <<
         "in output directory because there is none.\n" <<
         "Please use -P or -p to compare layout btwn proto and <my-site>.\n"<<
         "usage: #{usage}\n#{invite_to_more_command_help}"
@@ -148,8 +151,8 @@ module NanDoc::Commands
         else; fail("unimplemented subset: #{subset}")
       end
       src_path, dest_path = paths
-      assert_path "source path",      src_path
-      assert_path "destination path", dest_path
+      command_path_assert "source path",      src_path
+      command_path_assert "destination path", dest_path
       [src_path, dest_path]
     end
 
@@ -182,7 +185,7 @@ module NanDoc::Commands
         when :diff_root_subset; diff_root_subset(src_path, dest_path)
       end
       if diff.error?
-        task_abort diff.error
+        command_abort diff.error
       end
       diff
     end
@@ -218,7 +221,7 @@ module NanDoc::Commands
 
     def subsets
       cmd = self
-      @subsets ||= OptEnum.new do |oe|
+      @subsets ||= option_enum.new do |oe|
         command cmd
         name :subset
         values %w(css layouts js root)
@@ -231,10 +234,10 @@ module NanDoc::Commands
       result = path_tardo(config, 'data_sources/[0]/site_prototype')
       if result.found?
         thing_in_config = result.value
-        full_path = "proto/#{thing_in_config}"
+        full_path = NanDoc::Config.proto_path+"/#{thing_in_config}"
         full_path
       else
-        task_abort(
+        command_abort(
           result.error_message + " in " + config_path_for_site_path(site_path)
         )
       end
@@ -244,7 +247,7 @@ module NanDoc::Commands
     def process_diff_opts opts
       if (bad = opts.keys & PatchPassThru).any?
         bads = bad.map{|x| unnormalize_opt_key(x)}.join('and')
-        task_abort "#{bads} cannot be used with diffing only patching.\n"<<
+        command_abort "#{bads} cannot be used with diffing only patching.\n"<<
           "usage: #{usage}\n#{invite_to_more_command_help}"
       end
     end
@@ -265,7 +268,7 @@ module NanDoc::Commands
     def process_patch_opts_for_directory switch_h, opts, src, dest, site_path
       return unless opts[:subset] == 'root'
       if ! opts[:proto_to_content]
-        task_abort("we need to test this for root patching for this target")
+        command_abort("we need to test this for root patching for this target")
       end
       # it's not explicitly an available pass-thru option
       fail("huh?") if switch_h['--directory'] ||

data/lib/nandoc/commands.rb

@@ -0,0 +1,9 @@
+me = File.dirname(__FILE__)
+require 'nandoc/cli'
+require me + '/commands/create-nandoc-site.rb'
+require me + '/commands/diff.rb'
+
+shared_base = Nanoc3::CLI::Base.shared_base
+shared_base.remove_command Nanoc3::CLI::Commands::CreateSite
+shared_base.add_command    NanDoc::CreateNanDocSite.new
+shared_base.add_command    NanDoc::Commands::Diff.new

data/lib/nandoc/{config.rb → core/config.rb}

@@ -2,18 +2,14 @@ module NanDoc
   module Config
     extend self
 
-    #
-    # this name etc etc
-    #
-
-    @orphan_surrogate_filename = Root + '/proto/misc/orphan-surrogate.md'
-    attr_accessor :orphan_surrogate_filename
-
+    # items appear alphabetically.  thought about using dsl for config like ramaze
+    # but nah. why bother.
 
     #
-    # in the future make this smarter.  i don't like now nanoc handles color
+    # Whether to output cli output in color. Without color probably doesn't work
+    # @todo in the future make this smarter.  i don't like now nanoc handles color
     # (a command line argument?) There should be an autodetect, and/or set
-    # last setting in sticky json file; or however it is it is done. @todo
+    # last setting in sticky json file; or however it is it is done.
     #
     def colorize?
       true
@@ -68,6 +64,19 @@ module NanDoc
         option_prefix_no_color
     end
 
+    root = ::Gem::GemPathSearcher.new.find('nandoc').full_gem_path
+
+    @orphan_surrogate_filename = root + '/proto/misc/orphan-surrogate.md'
+    attr_accessor :orphan_surrogate_filename
+
+    Treebis::PersistentDotfile.extend_to(NanDoc,
+      './nandoc.persistent.json',
+      :file_utils => self.file_utils
+    )
+
+    @proto_path = root + '/proto'
+    attr_accessor :proto_path
+
     #
     # other parts of the app include this module to get convenience methods
     # to some of the config nodes.

data/lib/nandoc/core/project.rb

@@ -0,0 +1,50 @@
+require 'singleton'
+module NanDoc
+  class Project
+    #
+    # manages figuring out where folders are for things like tests,
+    # and builds test framework proxies for running tests
+    #
+
+    include Singleton
+  private
+    def initialize
+    end
+  public
+
+    # not especially robust at all
+    def project_root
+      @project_root ||= begin
+        presumed_root = File.dirname(FileUtils.pwd)
+        thems = %w(spec test)
+        found = thems.detect{ |dir| File.directory?(presumed_root+'/'+dir) }
+        fail("couldn't find " <<
+          StringMethods.oxford_comma(thems,' or ', &quoted) <<
+          "in #{presumed_root}") unless found
+        presumed_root
+      end
+    end
+
+    def require_test_file testfile
+      path = testdir + '/' + testfile
+      fail("test file not found: #{path.inspect}") unless File.file?(path)
+      require path
+    end
+
+    def testdir
+      @testdir ||= begin
+        tries = [project_root+'/test', project_root+'/spec']
+        found = tries.detect{ |path| File.directory?(path) }
+        fail("Couldn't find test dir for gem at (#{tries*', '})") unless found
+        found
+      end
+    end
+
+    def test_framework_proxy_for_file path
+      @the_only_proxy ||= begin
+        require 'nandoc/spec-doc/test-framework/mini-test/proxy'
+        SpecDoc::TestFramework::MiniTest::Proxy.new
+      end
+    end
+  end
+end