Merge pull request #13 from ellemenno/master

v3.2.1

README.md

@@ -65,7 +65,7 @@ Running `rake` in your project directory will execute the default task, which pr
  rake docs # shorthand for 'rake docs:build'
  rake docs:build # builds the GitHub pages documentation site, under 'docs/'
  rake docs:gen_api # creates api docs compatible with the programming pages template
- rake docs:install_template # downloads the latest programming pages release from GitHub,
+ rake docs:install_template # downloads the latest programming pages release from GitHub
  rake gui # shorthand for 'rake gui:run'
  rake gui:build # builds gui/bin/FooDemoGUI.loom for sprint34 SDK
  rake gui:run # launches gui/bin/FooDemoGUI.loom as a GUI app
@@ -81,16 +81,21 @@ Running `rake` in your project directory will execute the default task, which pr
  rake list_sdks # lists loom sdk versions available use
  rake sdk[id] # sets the provided SDK version in the config files of lib, cli, gui, and test
  rake template:update # downloads the latest release from GitHub, installing to DOC_TEMPLATE_DIR
+ rake template:version # reports installed and available versions of programming pages template
  rake test # shorthand for 'rake test:run'
  rake test:build # builds test/bin/FooTest.loom against sprint34 SDK
  rake test:ci # runs test/bin/FooTest.loom for CI
  rake test:run[seed] # runs test/bin/FooTest.loom for the console
  rake test:sdk[id] # sets the provided SDK version into test/loom.config
  rake version # reports loomlib version
- (using loomtasks v3.2.0)
+ (using loomtasks 3.2.0)
+ (using lsdoc 2.0.0)
+ (using programming-pages 0.5.6)
 
 If you are looking for more detail on any of the tasks, use `rake help`, e.g. `rake help test`.
 
+The [Programming Pages][programming-pages] template is not packaged with loomtasks releases. Running the `docs:install_template` task will download it from GitHub and extract it into your project.
+
 The Rake tasks are defined with dependencies and modification triggers, so you can just run `rake test` every time you edit a source file, and the library and test app will be rebuilt as needed automatically.
 
 ## conventions
@@ -125,19 +130,19 @@ Use of [lsdoc][lsdoc] is assumed.
 `doc/` contains config, a template, and source files to be converted into documentation. The documentation is not packaged with the loomlib; it is generated into a `docs/` directory for [GitHub pages][gh-pages] to render. Note that this requires an option be set for the source code repository (see [Publishing from a docs/ folder][gh-docs]).<br>
 
  └─doc
-  ├─lsdoc.config
   ├─src/
+  │ ├─_config.yml
   │ ├─examples/
   │ ├─guides/
   │ └─index.md
   └─template/
 
-* project level configuration for lsdoc is defined in `doc/lsdoc.config`
+* project level configuration for lsdoc is defined in `doc/src/_config.yml`
 * the documentation home page is written in markdown as `doc/src/index.md`
 * (optional) example pages are written under `doc/src/examples/`; they will have their own tab in the generated docs site
 * (optional) guide pages are written under `doc/src/guides/`; they will have their own tab in the generated docs site
-* the documentation template is stored under `doc/template/`. Use of [Programming Pages][programming-pages] is assumed.
-* [lsdoc][lsdoc] will use the data under `doc/` to create a site under `docs/` that GitHub Pages will render after it is pushed to your GitHub repository
+* the documentation template is stored under `doc/template/`. Use of [Programming Pages][programming-pages] is assumed
+* [lsdoc][lsdoc] will use the files under `doc/` to create a site under `docs/` that GitHub Pages will render after it is pushed to your GitHub repository
 
 #### demos
 

lib/tasks/loomlib.rake

@@ -47,11 +47,6 @@ def compile_demo(dir, build_file, demo_config)
  end
 end
 
-Dir.glob(File.join(File.dirname(__FILE__), 'rakefiles', '*.rake')).each do |rakefile|
- # don't load rakefiles for non-existent modules
- dir = File.basename(rakefile).match(/loomlib_(.*)\.rake/)[1]
- load rakefile if Dir.exists?(dir)
-end
 
 [File.join('releases', '**')].each { |f| CLEAN << f }
 Rake::Task[:clean].clear_comments()
@@ -76,7 +71,7 @@ task :list_targets => [:check_consts] do |t, args|
  b = "running on Ruby #{RUBY_VERSION}"
  puts "#{a} #{b}"
  system('rake -T')
- puts "(using loomtasks v#{LoomTasks::VERSION})"
+ puts "(using loomtasks #{LoomTasks::VERSION})"
 end
 
 task :check_consts do |t, args|
@@ -85,6 +80,13 @@ task :check_consts do |t, args|
 end
 
 
+Dir.glob(File.join(File.dirname(__FILE__), 'rakefiles', '*.rake')).each do |rakefile|
+ # don't load rakefiles for non-existent modules
+ dir = File.basename(rakefile).match(/loomlib_(.*)\.rake/)[1]
+ load rakefile if Dir.exists?(dir)
+end
+
+
 desc [
  "shows usage and project info, optionally for a specific command",
  "usage: rake help",

lib/tasks/rakefiles/loomlib_doc.rake

@@ -11,41 +11,34 @@ include LoomTasks
 @doc_config = nil
 
 def doc_config()
- @doc_config || (@doc_config = LoomTasks.parse_loom_config(doc_config_file))
+ @doc_config || (@doc_config = LoomTasks.parse_yaml_config(doc_config_file))
 end
 
 def doc_build_dir()
  File.join(Dir.pwd, 'docs-build')
 end
 
 def doc_config_file()
- File.join('doc', 'lsdoc.config')
+ File.join('doc', 'src', '_config.yml')
 end
 
 def write_doc_config(config)
- LoomTasks.write_loom_config(doc_config_file, config)
+ LoomTasks.write_yaml_config(doc_config_file, config)
 end
 
-def build_docs(config_path, in_dir, out_dir, template_dir)
+def build_docs(config_path, in_dir, out_dir)
  sdk_version = lib_config['sdk_version']
  sdk_dir = LoomTasks.sdk_root(sdk_version)
  processor = 'ghpages'
 
  options = [
  "-p #{processor}",
- "-t #{template_dir}",
+ "-c #{config_path}",
  "-l #{sdk_dir}/libs/#{LoomTasks.const_lib_name}.loomlib",
+ "-i #{in_dir}",
  "-o #{out_dir}",
- "-c #{config_path}",
- "-i #{in_dir}/index.md",
  ]
 
- examples_dir = File.join(in_dir, 'examples')
- guides_dir = File.join(in_dir, 'guides')
-
- options << "-e #{examples_dir}" if (Dir.exists?(examples_dir))
- options << "-g #{guides_dir}" if (Dir.exists?(guides_dir))
-
  cmd = "lsdoc #{options.join(' ')}"
  try(cmd, "failed to generate docs")
 end
@@ -61,16 +54,31 @@ LIB_DOC = 'docs'
 PP_RELEASE_API = 'https://api.github.com/repos/pixeldroid/programming-pages/releases/latest'
 PROJECT_ROOT = Dir.pwd
 DOC_TEMPLATE_DIR = File.join(PROJECT_ROOT, 'doc', 'template')
-DOC_SOURCE_DIR = doc_build_dir
+DOC_SOURCE_DIR = File.join(PROJECT_ROOT, 'doc', 'src')
+
+TOOL_ERRORS = {
+ :lsdoc => 'lsdoc not installed. See https://github.com/pixeldroid/lsdoc',
+ :progp => 'missing programming-pages.rake. try rake docs:install_template'
+}
+
+lsdoc_exe = LoomTasks.path_to_exe('lsdoc')
+if lsdoc_exe
+ lsdoc_version = %x(#{lsdoc_exe} -v 2>&1).chomp
+ Rake::Task['list_targets'].enhance { puts "(using #{lsdoc_version})" }
+else
+ Rake::Task['list_targets'].enhance { puts "(NOTE: #{TOOL_ERRORS[:lsdoc]})" }
+end
 
 unless Rake::Task.task_defined?('docs:build')
  begin
- load File.join(DOC_TEMPLATE_DIR, '_tasks', 'programming-pages.rake')
- Rake::Task['docs:build'].enhance ['docs:gen_api'] # add a pre-req
+ load(File.join(DOC_TEMPLATE_DIR, '_tasks', 'programming-pages.rake'))
+ Rake::Task['list_targets'].enhance { puts "(using programming-pages #{template_version})" } # template_version from programming-pages.rake
+ Rake::Task['docs:build'].enhance ['docs:gen_api', 'docs:cp_build_dir'] # add pre-reqs
  Rake::Task['docs:build'].enhance { Rake::Task['docs:rm_build_dir'].invoke() } # add a post-step
  rescue LoadError
  # silent failure here, since it's not fatal,
  # and the user needs to be given a chance to install the template
+ Rake::Task['list_targets'].enhance { puts "(NOTE: #{TOOL_ERRORS[:progp]})" }
  end
 end
 
@@ -91,8 +99,8 @@ end
 namespace :docs do
 
  task :check_tools do |t, args|
- LoomTasks.fail('lsdoc not installed. See https://github.com/pixeldroid/lsdoc') unless (LoomTasks.path_to_exe('lsdoc'))
- LoomTasks.fail('missing programming-pages.rake. try rake docs:install_template') unless Rake::Task.task_defined?('docs:build')
+ LoomTasks.fail(TOOL_ERRORS[:lsdoc]) unless LoomTasks.path_to_exe('lsdoc')
+ LoomTasks.fail(TOOL_ERRORS[:progp]) unless Rake::Task.task_defined?('docs:build')
  end
 
  task :update_version do |t, args|
@@ -105,7 +113,7 @@ namespace :docs do
  end
 
  desc [
- "downloads the latest programming pages release from GitHub,",
+ "downloads the latest programming pages release from GitHub",
  " installs to DOC_TEMPLATE_DIR",
  ].join("\n")
  task :install_template do |t, args|
@@ -117,7 +125,7 @@ namespace :docs do
  response = Net::HTTP.get_response(uri)
  LoomTasks.fail("#{response.code} - failed to access GitHub API at '#{PP_RELEASE_API}'") unless (response.code == '200')
  rescue SocketError
- ProgP.fail("failed to connect; is there network access?")
+ LoomTasks.fail("failed to connect; is there network access?")
  end
 
  result = JSON.parse(response.body)
@@ -170,15 +178,27 @@ namespace :docs do
  puts "[#{t.name}] emptying #{out_dir} to start clean"
  end
 
- build_docs(config_path, in_dir, out_dir, template_dir)
+ puts "[#{t.name}] generating api files..."
+ build_docs(config_path, in_dir, out_dir)
 
- puts "[#{t.name}] task completed, docs generated into #{out_dir}"
+ puts "[#{t.name}] task completed, api docs generated into #{out_dir}"
+ end
+
+ task :cp_build_dir do |t, args|
+ if (Dir.exists?(doc_build_dir))
+ target_dir = ghpages_dir # loaded from programming-pages.rake
+ puts "[#{t.name}] adding api files from #{doc_build_dir}..."
+ puts "[#{t.name}] to #{target_dir}..."
+ FileUtils.cp_r(File.join(doc_build_dir, '.'), target_dir)
+ else
+ puts "[#{t.name}] no api files found in #{doc_build_dir}"
+ end
  end
 
  task :rm_build_dir do |t, args|
  if (Dir.exists?(doc_build_dir))
- FileUtils.rm_rf(doc_build_dir)
  puts "[#{t.name}] removing temporary build dir #{doc_build_dir}"
+ FileUtils.rm_rf(doc_build_dir)
  end
  end
 

lib/tasks/rakefiles/support.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'rbconfig'
+require 'yaml'
 
 module LoomTasks
 
@@ -117,7 +118,15 @@ def parse_loom_config(file)
  end
 
  def write_loom_config(file, config)
- File.open(file, 'w') { |f| f.write("#{JSON.pretty_generate(config)}\n") }
+ IO.write(file, "#{JSON.pretty_generate(config)}\n")
+ end
+
+ def parse_yaml_config(file)
+ File.file?(file) ? YAML.load(File.read(file)) : {}
+ end
+
+ def write_yaml_config(file, config)
+ IO.write(file, "#{config.to_yaml}\n")
  end
 
  def const_find(name)

lib/tasks/scaffolding.rake

@@ -93,19 +93,19 @@ def demo_gui_template()
 end
 
 def doc_config_pathname()
- File.join(Dir.pwd, 'doc', 'lsdoc.config')
+ File.join(Dir.pwd, 'doc', 'src', '_config.yml')
 end
 
 def doc_config_template()
- File.join(template_dir, 'lsdoc.config.erb')
+ File.join(template_dir, 'lsdoc_config.erb')
 end
 
 def doc_index_pathname()
  File.join(Dir.pwd, 'doc', 'src', 'index.md')
 end
 
 def doc_index_template()
- File.join(template_dir, 'index.md.erb')
+ File.join(template_dir, 'lsdoc_index.erb')
 end
 
 def lib_testapp_pathname()

lib/tasks/templates/lsdoc_config.erb

@@ -0,0 +1,6 @@
+---
+project:
+ name: "<%= lib_name %>"
+ owner: "<project-owner>"
+ repo: "<project-repo>"
+ version: "1.0.0"