Generating docs requires no setup.

The build script will now: - Clone or pull joDoc into /packages/jodoc - Use markdown executable in /utils/markdown You still require Git, Ruby, and Perl.
i8ramin · Jan 13, 2011 · 5e00742 · 5e00742
1 parent e4895a2
commit 5e00742
Show file tree

Hide file tree

Showing 6 changed files with 1,852 additions and 25 deletions.
diff --git a/.gitignore b/.gitignore
@@ -9,4 +9,4 @@ lib/*
 *.rpmsave
 *.rej
 Thumbs.db
-	
+packages/jodoc
diff --git a/README.md b/README.md
@@ -27,23 +27,9 @@ Generating Documentation
 
 The documentation is generated from the inline comments in the source-code. [joDoc](https://github.com/davebalmer/jodoc) uses the comments to generate a set of HTML files.
 
-### Install joDoc ###
+To generate the documentation, you will need _Ruby_, _Perl_, and _Git_:
 
-    $ git clone http://github.com/davebalmer/joDoc.git
-    $ export PATH=$PATH:~/path/to/joDoc/
-
-You should add the export statement to `~/.bashrc` or `~/.profile` (or whatever you use), so that it exists across terminal sessions.
-
-### Install markdown ###
-
-    # Use your package manager to install the markdown CLI
-    brew install markdown
-    port install markdown
-    aptitude install markdown
-
-### Generate the XUI documentation ###
-
-    ./build --doc
+    ./build --generate-docs
 
 Source Tree
 -----------

diff --git a/build b/build
@@ -53,19 +53,35 @@ if minify
 end
 
 if docs
-  XUI_DIR  = File.expand_path(File.dirname(__FILE__))
-  SRC_DIR  = File.join(XUI_DIR, 'src')
-  DOC_DIR  = File.join(XUI_DIR, 'doc')
-  HTML_DIR = File.join(DOC_DIR, 'html')
-  EJS_DIR  = File.join(DOC_DIR, 'ejs')
+  PREFIX    = File.expand_path(File.dirname(__FILE__))
+  DOC_DIR   = File.join(PREFIX,    'doc')
+  PKG_DIR   = File.join(PREFIX,    'packages')
+  SRC_DIR   = File.join(PREFIX,    'src')
+  UTIL_DIR  = File.join(PREFIX,    'util')
+  HTML_DIR  = File.join(DOC_DIR,   'html')
+  EJS_DIR   = File.join(DOC_DIR,   'ejs')
+  JODOC_DIR = File.join(PKG_DIR,   'jodoc')
+  JODOC_GIT = File.join(JODOC_DIR, '.git')
+
+  MARKDOWN_BIN = File.join(UTIL_DIR, 'markdown', 'Markdown.pl')
+
+  def git_jodoc
+    if (File.directory?(JODOC_GIT))
+      puts "Updating joDoc..."
+      `git --git-dir=#{JODOC_GIT} pull -q origin master`
+    else
+      puts "Cloning joDoc from GitHub..."
+      `git clone git://github.com/davebalmer/joDoc.git #{JODOC_DIR}`
+    end
+  end
 
   def generate_documentation(output_directory)
     output_directory = File.expand_path(output_directory)
     FileUtils.mkdir_p(output_directory)
 
     FileUtils.cd(SRC_DIR) do
       files = Dir['**/*.js'].reject{ |f| (f =~ /ie\//) != nil }.join(' ')
-      `jodoc --title "XUI API Reference" --output #{output_directory} #{files}`
+      `jodoc --title "XUI API Reference" --markdown #{MARKDOWN_BIN} --output #{output_directory} #{files}`
     end
   end
 
@@ -93,23 +109,27 @@ if docs
       # Alter file content
       Dir['**/*'].each do |filename|
         data = File.read(filename)
-
         # Only save content of <body>
         data.sub!(/.*<body>(.*)<\/body>.*/mi, "\\1")
         # Update links to each filename
         rename.each { |o, n| data.gsub!(o, File.basename(n, '.ejs')) }
-
         File.open(filename, 'w') { |file| file.write(data) }
       end
     end
   end
 
+  # Prep-work to generate the documentation
+  git_jodoc
   FileUtils.rm_r(DOC_DIR) if File.exists?(DOC_DIR)
 
   # Generate HTML
+  puts "Generating HTML documentation..."
   generate_documentation(HTML_DIR)
 
   # Generate EJS
+  puts "Generating EJS documentation..."
   generate_documentation(EJS_DIR)
   html_to_ejs(EJS_DIR)
+
+  puts "Generated documentation at #{DOC_DIR}"
 end
diff --git a/util/markdown/License.text b/util/markdown/License.text
@@ -0,0 +1,30 @@
+Copyright (c) 2004, John Gruber  
+<http://daringfireball.net/>  
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+* Neither the name "Markdown" nor the names of its contributors may
+  be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+This software is provided by the copyright holders and contributors "as
+is" and any express or implied warranties, including, but not limited
+to, the implied warranties of merchantability and fitness for a
+particular purpose are disclaimed. In no event shall the copyright owner
+or contributors be liable for any direct, indirect, incidental, special,
+exemplary, or consequential damages (including, but not limited to,
+procurement of substitute goods or services; loss of use, data, or
+profits; or business interruption) however caused and on any theory of
+liability, whether in contract, strict liability, or tort (including
+negligence or otherwise) arising in any way out of the use of this
+software, even if advised of the possibility of such damage.