proscribe 0.0.3 → 0.0.4

data/.gitignore

@@ -0,0 +1,2 @@
+doc
+/Gemfile.lock

data/Gemfile

@@ -0,0 +1 @@
+gemspec

data/HISTORY.md

@@ -1,3 +1,18 @@
+v0.0.4 - Aug 01, 2011
+---------------------
+
+### Changed:
+  * Upgrade Proton. This makes things so much faster.
+  * Improvements and stuff.
+
+### Added:
+  * support for 'Usage: xx'
+  * Inheritance via 'Inherits: {Classname}'
+
+### Fixed:
+  * Ensure that the page headers in generated files are YAML-parseable.
+  * Only make {linking} work for those without spaces around it.
+
 v0.0.2 - Jul 29, 2011
 ---------------------
 

data/Scribefile

@@ -0,0 +1,8 @@
+manual: 'manual'
+
+files:
+- source: lib/**/*.rb
+
+output: doc
+
+github: rstacruz/proscribe

data/data/default/_layouts/_subindex.haml

@@ -0,0 +1,18 @@
+-# Combine all childrens
+- from = [from]  unless from.is_a?(Array)
+- childrens = from.compact.map { |p| page_children(p) }
+- groups = childrens.inject({}) { |h, groups| groups.each { |k, v| h[k] ||= Array.new; h[k] += v }; h }
+- suffix ||= nil
+
+- groups.each do |type, children|
+  %h3
+    = type.to_s.gsub('_', ' ').capitalize
+    - if suffix
+      = suffix
+
+  %ul.section
+    - children.each do |method|
+      %li
+        %a{href: rel(method.path)}= method.title
+        - unless method.meta.brief.to_s.empty?
+          %span.brief= method.meta.brief

data/data/default/_layouts/default.haml

@@ -24,7 +24,7 @@
   %body
     #top
       %a#logo{href: rel('/')}
-        = Hyde::Page['/'].title
+        = Proton::Page['/'].title
 
     #area
       #content
@@ -44,18 +44,16 @@
               %h5= page.meta.brief
 
           .content
-            != yield
+            - if page.meta.usage
+              %h2 Usage
+              %pre= page.meta.usage
 
-            - groups = page_children(page)
-            - groups.each do |type, children|
-              %h3= type.to_s.gsub('_', ' ').capitalize
+            != yield
 
-              %ul.section
-                - children.each do |method|
-                  %li
-                    %a{href: rel(method.path)}= method.title
-                    - unless method.meta.brief.to_s.empty?
-                      %span.brief= method.meta.brief
+            != partial :_subindex, :from => page
+            - if page.meta.inherits
+              - pages = page.meta.inherits.split(' ').map { |path| Proton::Page[path] }
+              != partial :_subindex, :from => pages, :suffix => "(Inherited)"
 
             -# Source
             %section.footer

data/lib/proscribe/cli.rb

@@ -6,11 +6,14 @@ class ProScribe::CLI < Shake
   extend ProScribe::Helpers
 
   task(:build) do
+
     project.make
     pass project.dir  if ARGV.delete('-d') || ARGV.delete('--debug')
 
-    Dir.chdir(project.dir) {
-      system "proton build"
+    require 'proton'
+    pro = Proton::Project.new project.dir
+    pro.build { |file|
+      puts "* %-35s %-35s" % [ file, "(#{file.path})" ]
     }
 
     copy_files project.dir('_output'), project.root(project.config.output)

data/lib/proscribe/extractor.rb

@@ -4,17 +4,20 @@ require 'ostruct'
 require 'fileutils'
 
 module ProScribe
+  # Class: Extractor (ProScribe)
   # Extracts comments from list of files.
-  # Gets the ones with comment blocks starting with `[...]`
   #
-  # == Common usage
+  # ## Description
+  #    Gets the ones with comment blocks starting with `[...]`
   #
-  #   ex = Extractor.new(Dir['./**/*.rb'])
-  #   ex.blocks
+  # ## Common usage
   #
-  #   ex.blocks.map! { |b| b.file = "file: #{b.file}" }
+  #     ex = Extractor.new(Dir['./**/*.rb'])
+  #     ex.blocks
   #
-  #   ex.write!('manual/')       # Writes to manual/
+  #     ex.blocks.map! { |b| b.file = "file: #{b.file}" }
+  #
+  #     ex.write!('manual/')       # Writes to manual/
   #
   class Extractor
     def initialize(files, root, options={})
@@ -31,7 +34,8 @@ module ProScribe
       }
     end
 
-    # Returns an array of Extractor::Blocks.
+    # Method: blocks (ProScribe::Extractor)
+    # Returns an array of {Extractor::Block}s.
     def blocks
       @blocks ||= begin
         @files.map { |file|
@@ -60,16 +64,16 @@ module ProScribe
             :type => $1,
             :title => $2,
             :parent => $3,
-            :line => hash[:line] + block.size + 1,
-            :source => filename,
+            :source_line => hash[:line] + block.size + 1,
+            :source_file => filename,
             :body => (block[0..-2].join("\n") + "\n")
         elsif block.first =~ re
           Extractor::Block.new \
             :type => $1,
             :title => $2,
             :parent => $3,
-            :line => hash[:line] + block.size + 1,
-            :source => filename,
+            :source_line => hash[:line] + block.size + 1,
+            :source_file => filename,
             :body => (block[1..-1].join("\n") + "\n")
         end
       }.compact
@@ -99,20 +103,38 @@ module ProScribe
     attr_accessor :file
 
     def initialize(options)
-      title  = options[:title]
-      parent = options[:parent]
-      body   = options[:body]
-      type   = options[:type].downcase
-
-      source = options[:source]
-      line   = options[:line]
-
-      file = to_filename(title, parent)
-      brief, *body = body.split("\n\n")
-      body = "#{body.join("\n\n")}"
+      options[:type].downcase!
+      body = options.delete(:body)
+      type = options.delete(:type)
+      file = to_filename(options[:title], options[:parent])
+
+      # Build the hash thing.
+      header  = Hash[options.map { |(k, v)| [k.to_s, v] }]
+
+      # Extract the brief and other artifacts.
+      body = body.split("\n")
+      while true
+        line = body.first
+        if line.nil?
+          break
+        elsif line =~ /^(.*?): (.*?)$/
+          header[$1.downcase] = $2.strip
+          body.shift
+        elsif line.strip.empty?
+          body.shift
+        else
+          brief = body.shift
+          break
+        end
+      end
+      body = body.join("\n")
 
-      heading = "title: #{title}\npage_type: #{type}\nsource_file: #{source}\nsource_line: #{line}\nbrief: #{brief}\n"
-      heading += "--\n"
+      # Build the hash thing.
+      header['page_type'] = type
+      header['brief'] = brief
+      header['inherits'] = resolve(header['inherits']) { |fname, _, _| fname }  if header['inherits']
+      heading = YAML::dump(header).gsub(/^[\-\n]*/, '').strip
+      heading += "\n--\n"
 
       @file = file
       body  = Tilt.new(".md") { body }.render
@@ -121,13 +143,8 @@ module ProScribe
     end
 
   private
-    def fix_links(str, options={})
-      from = ("/" + options[:from].to_s).squeeze('/')
-      depth = from.to_s.count('/')
-      indent = (depth > 1 ? '../'*(depth-1) : './')[0..-2]
-
-      # First pass, {Helpers::content_for} to become links
-      str = str.gsub(/{([^}]*?)}/) { |s|
+    def resolve(str, &blk)
+      str.gsub(/{(?!\s)([^}]*?)(?<!\s)}/) { |s|
         s = s.gsub(/{|}/, '')
 
         m = s.match(/^(.*?)[:\.]+([A-Za-z_\(\)\!\?]+)$/)
@@ -137,7 +154,19 @@ module ProScribe
           name, context = s, nil
         end
 
-        s = "<a href='/#{to_filename(s, '', :ext => '.html')}'>#{name}</a>"
+        fname = to_filename(s, '', :ext => '.html')
+        yield fname, name, context
+      }
+    end
+
+    def fix_links(str, options={})
+      from = ("/" + options[:from].to_s).squeeze('/')
+      depth = from.to_s.count('/')
+      indent = (depth > 1 ? '../'*(depth-1) : './')[0..-2]
+
+      # First pass, {Helpers::content_for} to become links
+      str = resolve(str) { |fname, name, context|
+        s = "<a href='/#{fname}'>#{name}</a>"
         s += " <span class='context'>(#{context})</span>"  if context
         s
       }
@@ -151,6 +180,9 @@ module ProScribe
       }
     end
 
+    # Private method: to_filename (ProScribe::Extractor)
+    # Changes something to a filename.
+    #
     def to_filename(title, parent='', options={})
       extension = options[:ext] || '.erb'
       pathify = lambda { |s|

data/lib/proscribe/version.rb

@@ -6,6 +6,6 @@ module ProScribe
   #     ProScribe.version     #=> "0.0.2"
   #
   def self.version
-    "0.0.3"
+    "0.0.4"
   end
 end

data/lib/proscribe.rb

@@ -1,3 +1,4 @@
+require 'proton'
 require 'yaml'
 require 'fileutils'
 require 'tmpdir'

data/manual/config.ru

@@ -0,0 +1,3 @@
+gem 'proscribe', '~> 0.0.1'
+require 'proscribe'
+run ProScribe.rack_app

data/manual/index.md

@@ -0,0 +1,56 @@
+title: ProScribe manual
+brief: Crappy source documentation tool.
+--
+
+    $ gem install proscribe
+
+#### Enable ProScribe
+Make your code project ProScribe-able using `proscribe new`.
+
+    $ proscribe new
+      create   Scribefile
+      create   manual/
+      create   manual/index.md
+    </pre>
+
+#### Inline comments
+Now edit your files in `manual/` and inline comments in your source code. Use Markdown!
+
+    # Class: Adaptor
+    # Adapts insteads of dying.
+    #
+    # ## Usage
+    #
+    #     a = Adaptor.new(plug)
+    #
+    # ## Description
+    #
+    #   This is a great class.
+    #
+    class Adaptor
+      # ...
+    end
+    </pre>
+
+#### Build as HTML
+
+To build documentation HTML, use this. This builds HTML in `doc/` by default.
+
+    $ proscribe build
+      ...
+
+    $ ls doc/
+      index.html
+      style.css
+      ...
+
+#### Real-time previews
+You may also preview your changes in real time. Do this, then point your browser to `http://localhost:4833` to see your changes in real time.
+
+    $ proscribe start
+    * Starting server...
+    >> Thin web server (v1.2.11 codename Bat-Shit Crazy)
+    >> Maximum connections set to 1024
+    >> Listening on 0.0.0.0:4833, CTRL+C to stop
+
+[Source code](http://github.com/rstacruz/proscribe "Source code")

data/proscribe.gemspec

@@ -0,0 +1,20 @@
+require './lib/proscribe/version'
+
+Gem::Specification.new do |s|
+  s.name = "proscribe"
+  s.version = ProScribe.version
+  s.summary = %{Documentation generator.}
+  s.description = %Q{Build some documentation for your projects of any language.}
+  s.authors = ["Rico Sta. Cruz"]
+  s.email = ["rico@sinefunc.com"]
+  s.homepage = "http://github.com/rstacruz/proscribe"
+  s.files = `git ls-files`.strip.split("\n")
+  s.executables = Dir["bin/*"].map { |f| File.basename(f) }
+
+  s.add_dependency "hashie", "~> 1.0.0"
+  s.add_dependency "shake", "~> 0.1.2"
+  s.add_dependency "tilt", "~> 1.3.2"
+  s.add_dependency "proton", "~> 0.3.4"
+  s.add_dependency "fssm", "~> 0.2.7"
+  s.add_dependency "rdiscount", "~> 1.6.8"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: proscribe
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,12 +9,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-07-29 00:00:00.000000000 +08:00
+date: 2011-08-01 00:00:00.000000000 +08:00
 default_executable: 
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
-  requirement: &2158295020 !ruby/object:Gem::Requirement
+  requirement: &2154058100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,10 +22,10 @@ dependencies:
         version: 1.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2158295020
+  version_requirements: *2154058100
 - !ruby/object:Gem::Dependency
   name: shake
-  requirement: &2158294520 !ruby/object:Gem::Requirement
+  requirement: &2154057600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -33,32 +33,32 @@ dependencies:
         version: 0.1.2
   type: :runtime
   prerelease: false
-  version_requirements: *2158294520
+  version_requirements: *2154057600
 - !ruby/object:Gem::Dependency
   name: tilt
-  requirement: &2158294060 !ruby/object:Gem::Requirement
+  requirement: &2164403120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.2.2
+        version: 1.3.2
   type: :runtime
   prerelease: false
-  version_requirements: *2158294060
+  version_requirements: *2164403120
 - !ruby/object:Gem::Dependency
   name: proton
-  requirement: &2158293600 !ruby/object:Gem::Requirement
+  requirement: &2164402660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.3.3
+        version: 0.3.4
   type: :runtime
   prerelease: false
-  version_requirements: *2158293600
+  version_requirements: *2164402660
 - !ruby/object:Gem::Dependency
   name: fssm
-  requirement: &2158293140 !ruby/object:Gem::Requirement
+  requirement: &2164402200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -66,10 +66,10 @@ dependencies:
         version: 0.2.7
   type: :runtime
   prerelease: false
-  version_requirements: *2158293140
+  version_requirements: *2164402200
 - !ruby/object:Gem::Dependency
   name: rdiscount
-  requirement: &2158292680 !ruby/object:Gem::Requirement
+  requirement: &2164401740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -77,7 +77,7 @@ dependencies:
         version: 1.6.8
   type: :runtime
   prerelease: false
-  version_requirements: *2158292680
+  version_requirements: *2164401740
 description: Build some documentation for your projects of any language.
 email:
 - rico@sinefunc.com
@@ -86,16 +86,22 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- data/default/_extensions/helpers.rb
-- data/default/_layouts/_nav.haml
-- data/default/_layouts/default.haml
+- .gitignore
+- Gemfile
+- HISTORY.md
+- README.md
+- Scribefile
+- bin/proscribe
 - data/default/Gemfile
 - data/default/Gemfile.lock
-- data/default/proscribe.js
 - data/default/Protonfile
+- data/default/_extensions/helpers.rb
+- data/default/_layouts/_subindex.haml
+- data/default/_layouts/default.haml
+- data/default/proscribe.js
 - data/default/style.scss
 - data/rack/config.ru
-- bin/proscribe
+- lib/proscribe.rb
 - lib/proscribe/cli.rb
 - lib/proscribe/extractor.rb
 - lib/proscribe/helpers.rb
@@ -103,9 +109,9 @@ files:
 - lib/proscribe/rack_app.rb
 - lib/proscribe/version.rb
 - lib/proscribe/watcher.rb
-- lib/proscribe.rb
-- HISTORY.md
-- README.md
+- manual/config.ru
+- manual/index.md
+- proscribe.gemspec
 has_rdoc: true
 homepage: http://github.com/rstacruz/proscribe
 licenses: []

data/data/default/_layouts/_nav.haml

@@ -1,8 +0,0 @@
-- is_active = from == p
-- if p.html?
-  %li
-    %a{href: rel(p.path), class: ("active" if is_active)}= p
-  %ul{class: "level-#{level}"}
-    - p.children.each do |pp|
-      != partial :'_nav', from: from, p: pp, level: level+1
-