atom-doc 0.1.0

data/README.textile

@@ -0,0 +1,150 @@
+h1. Atom
+
+Atom is a command suite for generating text-based documentation, and is loosely based on the "Darwin Information Typing Architecture":http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture (DITA). 
+
+DITA is XML-based, and content is created as small *topic* items rather than long books or chapters and listed in *maps* to produce a document. Topics should be __atomic__ in that they contain the smallest amount of information that makes sense with no further context. A DITA map contains links to topics, organized in the sequence (which may be hierarchical) in which they are intended to appear in finished documents.
+
+Instead of being XML-based, *atom* uses *textile* as the markup language. This avoids having to use a special editor or hand coding XML. It also allows the source documents to be read more easily by a human. It's open source and has a simple plug-in system that allows the content creator to create scripts that hook in to the processing stream.
+
+h2. The Basics
+
+Creating documentation is simple.
+
+# Initialize a repository with the @init@ command
+# Add version control with @git@ (optional)
+# Add *maps* and *topics* with the @new@ command
+# Edit your *maps* to include *topics*
+# Build your *maps* with the @build@ command
+
+h3. The Repository
+
+We can initialize a new repository by running the following command:
+
+bc. $ atom init docs
+>
+create  [Dir]: docs/source
+create  [Dir]: docs/source/topics
+create  [Dir]: docs/source/maps
+create  [Dir]: docs/config
+create  [Dir]: docs/temp
+create  [Dir]: docs/output
+create  [Dir]: docs/output/html
+create  [Dir]: docs/templates
+create  [Dir]: docs/plugins
+create [File]: docs/.atom
+create [File]: docs/.gitignore
+create [File]: docs/config/atom.yml
+create [File]: docs/templates/concept.textile
+create [File]: docs/templates/procedure.textile
+create [File]: docs/templates/map.textile
+create [File]: docs/templates/default.html
+
+This will create a series of directories and files that will be used as a framework to store and build your documentation. From inside the *docs* directory, you can run the rest of the *atom* commands.
+
+Note that several *template* files are created:
+
+* concept.textile
+* map.textile
+* procedure.textile
+* default.html
+
+These templates contain basic skeletons to generate documents from and are meant to be edited to suit the needs of the particular project. When you run the @new@ command, the files are generated from these templates.
+
+To generate a map, run:
+
+bc. $ atom new -m 'Working with Vagrant'
+>
+create [File]: source/maps/m_working_with_vagrant.textile
+
+The @new@ command takes a switch indicating the type of document you want to create [concept, procedure, map] and a title. It will create the document in the *source* directory, either under topics or maps. In the example above, a new *map* is created with a title of *Working with Vagrant*.
+
+Next we should create some topics to be included in the map:
+
+bc. $ atom new -c 'VirtualBox'
+>
+create [File]: source/topics/c_virtualbox.textile
+
+bc. $ atom new -p 'Installing VirtualBox'
+>
+create [File]: source/topics/p_installing_virtualbox.textile
+
+Notice that the @-c@ creates a *concept* and the @-p@ creates a *procedure* and that the respective files are prefixed witha a *c* and a *p* and placed in the @source/topics@ directory.
+
+Now that we have a few topics, we can include them in the map with the following lines:
+
+bc. =1 VirtualBox
+=2 Installing VirtualBox
+
+The @=@ sign includes the topic that matches the given title, and the number tells *atom* where this topic fits in the hierarchy with @0@ being the root and the default. Even though the @c_virtualbox.textile@ file has an @h1@ header, it will have an @h2@ in the final document.
+
+Now that we have some topics in our map, we can build it.
+
+bc. $ atom build 'Working with Vagrant'
+>
+create [File]: output/html/working_with_vagrant.html
+
+We now have an html document that contains our documentation.
+
+h2. Advanced Usage
+
+h3. Plugins
+
+*Atom* allows users to create plugins that hook in to the build process at two points. The first hook is after the map and subtopics have been assembeled into one document, but is still a textile document. The second hook is after the html document is created.
+
+To create a plugin, create a new file in the *plugins* directory. I'll create a file named *contents.rb*.
+
+bc. class Contents < Atom::Plugin
+  def run(text)
+    # logic here
+  end
+end
+
+Your class must inherit from @Atom::Plugin@ and override the @run@ method. You'll be passed the text of the file your hooking in to, which should be manipulated and returned.
+
+In order to run this plugin, you'll have to tell *atom* about it in the @config/atom.yml@ file. When you first start an *atom* project, no plugins will be configured to run and the yaml file will contain the following line:
+
+bc. plugins: { pre: [], post: [] }
+
+I want my plugin to run after the html has been generated, so I'll place the name of my plugin in the *post* array.
+
+bc. plugins: { pre: [], post: [contents] }
+
+Now let's modify the plugin to do something useful:
+
+bc.. require 'nokogiri'
+
+class Contents < Atom::Plugin
+  def run(text)
+    doc = Nokogiri::HTML.parse(text)
+    return create_table(doc, 4)
+  end
+  
+  def create_table(doc, depth=3)
+    # The following line creates an array like ["h1", "h2", "h3"]
+    hs = (1..depth).to_a.reduce([]) {|r, e| r << "h#{e}"}
+    table_node = Nokogiri::XML::Node.new('table', doc)
+    
+    doc.css(hs.join(',')).each_with_index do |h, i|
+      anchor_node = Nokogiri::XML::Node.new('a',doc)
+      link_node = Nokogiri::XML::Node.new('a',doc)
+      row_node = Nokogiri::XML::Node.new('tr', doc)
+      data_node = Nokogiri::XML::Node.new('td', doc)
+      
+      link_node['href'] = "##{i}"
+      anchor_node['name'] = "#{i}"
+      h.add_previous_sibling(anchor_node)
+      link_node.content = h.content
+      data_node.add_child(link_node)
+      row_node.add_child(data_node)
+      
+      table_node.add_child(row_node)
+    end
+    
+    body = doc.at_css "body"
+    body.children.first.add_previous_sibling(table_node)
+    
+    return doc
+  end
+end
+
+p. The above plugin will create a table listing all headings up to the depth specified with a link to each heading.

data/atom.rdoc

@@ -0,0 +1,5 @@
+= atom
+
+Generate this with
+    atom rdoc
+After you have described your command line interface

data/bin/atom

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+# 1.9 adds realpath to resolve symlinks; 1.8 doesn't
+# have this method, so we add it so we get resolved symlinks
+# and compatibility
+unless File.respond_to? :realpath
+  class File #:nodoc:
+    def self.realpath path
+      return realpath(File.readlink(path)) if symlink?(path)
+      path
+    end
+  end
+end
+$: << File.expand_path(File.dirname(File.realpath(__FILE__)) + '/../lib')
+require 'rubygems'
+require 'gli'
+require 'atom_version'
+require 'atom'
+
+include GLI
+
+program_desc 'tool for creating "atomic" text-based documentation'
+
+version Atom::VERSION
+
+# init command
+desc 'create a new document repository'
+arg_name 'list of repository names'
+skips_pre
+command :init do |c|
+
+  c.action do |global_options,options,args|
+    proj_names = args
+    
+    if args.length < 1
+      raise 'You must provide a project name'
+    elsif File.exist? '.atom'
+      raise 'This appears to be an atom directory'
+    end
+    
+    proj_names.each do |proj_name|
+      Atom::Scaffold.create(proj_name)
+    end
+  end
+end
+
+# new commmand
+desc 'create a new document'
+arg_name "'document title'"
+command :new do |c|
+  c.desc 'create concept document'
+  c.switch [:c, :concept]
+  
+  c.desc 'create map document'
+  c.switch [:m, :map]
+  
+  c.desc 'create procedure document'
+  c.switch [:p, :procedure]
+  
+  c.action do |global_options,options,args|
+    
+    if options[:c]
+      Atom::Generate.from_template('concept', args[0])
+    end
+    
+    if options[:m]
+      Atom::Generate.from_template('map', args[0])
+    end
+    
+    if options[:p]
+      Atom::Generate.from_template('procedure', args[0])
+    end
+  end
+end
+
+# build command
+desc 'output source map to html'
+arg_name "'document title'"
+command :build do |c|
+  c.action do |global_options,options,args|
+    temp_file = Atom::Generate.temp_file('map', args[0])
+
+    Atom::Plugger.load_plugins("#{Atom::PATH}/plugins", Atom::PLUGINS)
+    
+    Atom::Plugger.run(Atom::PRE_PLUGINS, temp_file)
+    
+    html_file = Atom::Generate.html(temp_file)
+    
+    Atom::Plugger.run(Atom::POST_PLUGINS, html_file)
+  end
+end
+
+pre do |global,command,options,args|
+  if command.name == :help # allow help command to run
+    true
+  elsif File.exist?('.atom')
+    Atom::load_config
+    
+    true
+  else
+    raise "This command needs to run in an atom directory"
+      
+    false
+  end
+end
+
+post do |global,command,options,args|
+  # Post logic here
+  # Use skips_post before a command to skip this
+  # block on that command only
+end
+
+on_error do |exception|
+  # Error logic here
+  # return false to skip default error handling
+  true
+end
+
+exit GLI.run(ARGV)

data/lib/atom.rb

@@ -0,0 +1,10 @@
+require 'fileutils'
+require 'mustache'
+require 'yaml'
+require 'redcloth'
+
+require 'atom/scaffold'
+require 'atom/generate'
+require 'atom/helpers'
+require 'atom/plugin'
+require 'atom/plugger'

data/lib/atom/generate.rb

@@ -0,0 +1,59 @@
+module Atom
+  class Generate
+    def self.from_template(type, title)
+      dest = type == 'map' ? "source/maps" : "source/topics"
+      file_name = Atom::name(type, title)
+      template = File.read("#{Atom::PATH}/templates/#{type}.textile")
+      
+      if File.exist?(File.join(dest, file_name))
+        raise "File already exists"
+      else
+        $stdout.puts "create [File]: #{File.join(dest, file_name)}"
+
+        Atom::write_file(
+          File.join(dest, file_name),
+          Mustache.render(
+            template, :title => title, :author => Atom::CONFIG[:author]
+          )
+        )
+      end
+    end
+    
+    def self.temp_file(type, title)
+      file_name = Atom::name(type, title)
+      
+      Atom::write_file(
+        "#{Atom::PATH}/temp/#{file_name}",
+        Atom::sub_topics(Atom::get_src_file_by_title(title, 'maps'))
+      )
+      
+      return "#{Atom::PATH}/temp/#{file_name}"
+    end
+    
+    def self.html(file)
+      out_file_name = "#{File.basename(file, ".textile").split('_')[1..-1].join('_')}.html"
+      out_file_path = File.join(Atom::PATH, "output/html")
+      out_file = File.join(out_file_path, out_file_name)
+      template = File.read(File.join(Atom::PATH, "templates/default.html"))
+      
+      doc = File.read(file)
+      rc = RedCloth.new(doc)
+      
+      if File.exist? out_file
+        $stdout.puts "overwrite [File]: output/html/#{out_file_name}"
+      else
+        $stdout.puts "create [File]: output/html/#{out_file_name}"
+      end
+      
+      Atom::write_file(
+        out_file,
+        Mustache.render(
+          template, :body => rc.to_html,
+          :title => File.basename(file)
+        )
+      )
+      
+      return out_file
+    end
+  end
+end

data/lib/atom/helpers.rb

@@ -0,0 +1,82 @@
+module Atom
+  def self.load_config
+    const_set(:PATH, Dir.pwd)
+    const_set(:CONFIG, YAML.load_file("#{PATH}/config/atom.yml"))
+    const_set(:PRE_PLUGINS, CONFIG['plugins']['pre'])
+    const_set(:POST_PLUGINS, CONFIG['plugins']['post'])
+    const_set(:PLUGINS, PRE_PLUGINS | POST_PLUGINS)
+    
+    unless CONFIG[:author]
+      begin
+        CONFIG[:author] = `git config --get user.name`.chomp
+      rescue
+        CONFIG[:author] = 'unknown'
+      end
+    end
+  end
+  
+  def self.read_yaml(content)
+    begin
+      if content =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
+        content = $'
+        data = YAML.load($1)
+      end
+    rescue => e
+      $stderr.puts "YAML Exception: #{e.message}"
+    end
+
+    data ||= {}
+    return [data, content]
+  end
+  
+  def self.sub_topics(file)
+    map_data, content = Atom::read_yaml(File.read(file))
+    new_file = ''
+
+    content.split("\n").each do |line|
+      if line.match(/^=/)
+        depth, title = line.match(/^=(\d)? (.*)/)[1..2]
+        depth ||= 0
+        data, content = Atom::read_yaml(
+          File.read(
+            Atom::get_src_file_by_title(title, 'topics')
+          ).gsub(/^h(\d)(.*)/) { "h#{($1.to_i + depth.to_i).to_s}#{$2}" }
+        )
+        
+        new_file += "<section class=\"#{data['class']}\" author=\"#{data['author']}\">\n"
+        new_file += "\n#{content}\n"
+        new_file += "</section>"
+        new_file += "\n"
+      else
+        new_file += "#{line}\n"
+      end
+    end
+      
+    return new_file
+  end
+  
+  def self.get_src_file_by_title(title, src_dir)
+    file_title = title.downcase.split.join('_')
+    result = Dir.glob("#{Atom::PATH}/source/#{src_dir}/?_#{file_title}.*")
+    if result.size == 1
+      result.first
+    elsif result.size == 0
+      raise "Title '#{title}' not found"
+    else 
+      raise "Ambiguous title '#{title}'"
+    end
+  end
+  
+  def self.name(type, title)
+    # TODO abastract file extension to accomodate markup choice
+    "#{type.split('').first}_#{title.chomp.downcase.split.join('_')}.textile"
+  end
+  
+  # Ensure files are written in a consistant manner
+  def self.write_file(path, content)
+    file = File.open(path, "w")
+    file.write(content)
+    file.flush
+    file.close
+  end
+end

data/lib/atom/plugger.rb

@@ -0,0 +1,20 @@
+module Atom
+  class Plugger
+    def self.load_plugins(plugin_path, plugins)
+      plugins.each do |plugin|
+        require File.join("#{plugin_path}", "#{plugin}.rb")
+      end
+    end
+    
+    def self.run(plugins, file_path)
+      text = File.read(file_path)
+      
+      plugins.each do |plugin|
+        classname = plugin.split('_').map(&:capitalize).join
+        text = Kernel.const_get(classname).new(text).to_s
+      end
+      
+      Atom::write_file(file_path, text)
+    end
+  end
+end

data/lib/atom/plugin.rb

@@ -0,0 +1,11 @@
+module Atom
+  class Plugin
+    def initialize(content)
+      @content = run(content)
+    end
+    
+    def to_s
+      @content
+    end
+  end
+end

data/lib/atom/scaffold.rb

@@ -0,0 +1,144 @@
+module Atom
+  class Scaffold
+    def self.create(root_dir)
+      dirs = [
+        'source',
+        ['source', 'topics'],
+        ['source', 'maps'],
+        'config',
+        'temp',
+        'output',
+        ['output', 'html'],
+        'templates',
+        'plugins'
+      ]
+      
+      if mkdirs(root_dir, dirs)
+        mk_dotatom(root_dir)
+        mk_dotgitignore(root_dir)
+        mk_atom(root_dir)
+        mk_concept(root_dir)
+        mk_procedure(root_dir)
+        mk_map(root_dir)
+        mk_html_skeleton(root_dir)
+      end
+    end
+    
+    def self.mk_dotatom(root_dir)
+      $stdout.puts "create [File]: #{root_dir}/.atom"
+      FileUtils.touch "#{root_dir}/.atom"
+    end
+    
+    def self.mk_dotgitignore(root_dir)
+      $stdout.puts "create [File]: #{root_dir}/.gitignore"
+      File.open("#{root_dir}/.gitignore", "w") do |file|
+        file.puts <<EOS
+config/
+output/
+temp/
+EOS
+      end
+    end
+    
+    def self.mk_atom(root_dir)
+      $stdout.puts "create [File]: #{root_dir}/config/atom.yml"
+      File.open("#{root_dir}/config/atom.yml", "w") do |file|
+        file.puts <<EOS
+markup: textile
+
+plugins: { pre: [], post: [] }
+
+EOS
+      end
+    end
+    
+    def self.mk_concept(root_dir)
+      $stdout.puts "create [File]: #{root_dir}/templates/concept.textile"
+      File.open("#{root_dir}/templates/concept.textile", "w") do |file|
+        file.puts <<EOS
+---
+author: {{author}}
+class: concept
+---
+
+h1(topic-title). {{title}}
+
+EOS
+      end
+    end
+    
+    def self.mk_procedure(root_dir)
+      $stdout.puts "create [File]: #{root_dir}/templates/procedure.textile"
+      File.open("#{root_dir}/templates/procedure.textile", "w") do |file|
+        file.puts <<EOS
+---
+author: {{author}}
+class: procedure
+---
+
+h1(topic-title). {{title}}
+
+p(preparation). Before you begin
+
+h2. Procedure
+
+# Step 1
+
+p(result). Result of procedure
+
+EOS
+      end
+    end
+    
+    def self.mk_map(root_dir)
+      $stdout.puts "create [File]: #{root_dir}/templates/map.textile"
+      File.open("#{root_dir}/templates/map.textile", "w") do |file|
+        file.puts <<EOS
+---
+author: {{author}}
+class: map
+---
+
+h1(map-title). {{title}}
+
+To include topics in this document, begin a line with @=@ followed by a space and the title of the topic. Like so:
+
+bc. = Title of My Topic
+
+EOS
+      end
+    end
+    
+    def self.mk_html_skeleton(root_dir)
+      $stdout.puts "create [File]: #{root_dir}/templates/default.html"
+      File.open("#{root_dir}/templates/default.html", "w") do |file|
+        file.puts <<EOS
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>{{title}}</title>
+</head>
+  <body>
+  {{{body}}}
+  </body>
+</html>
+EOS
+      end
+    end
+    
+    def self.mkdirs(root_dir, dirs)
+      if File.exist? root_dir
+        raise "'#{root_dir}' already exists"
+        return false
+      end
+      
+      FileUtils.mkdir root_dir
+      
+      dirs.each do |dir|
+        $stdout.puts "create  [Dir]: #{File.join(root_dir, dir)}"
+        FileUtils.mkdir "#{File.join(root_dir, dir)}"
+      end
+    end
+  end
+end

data/lib/atom_version.rb

@@ -0,0 +1,3 @@
+module Atom
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: atom-doc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Michael Wood
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: aruba
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.6
+- !ruby/object:Gem::Dependency
+  name: gli
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mustache
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: RedCloth
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: octant.coder@gmail.com
+executables:
+- atom
+extensions: []
+extra_rdoc_files:
+- README.textile
+- atom.rdoc
+files:
+- bin/atom
+- lib/atom_version.rb
+- lib/atom.rb
+- lib/atom/scaffold.rb
+- lib/atom/generate.rb
+- lib/atom/helpers.rb
+- lib/atom/plugin.rb
+- lib/atom/plugger.rb
+- README.textile
+- atom.rdoc
+homepage: http://github.com/octant/atom
+licenses: []
+post_install_message: 
+rdoc_options:
+- --title
+- atom
+- --main
+- README.rdoc
+- -ri
+require_paths:
+- lib
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Command line tool for generating text-based documentation
+test_files: []