diff --git a/README.md b/README.md
index 9f82af2..9d8ede2 100644
--- a/README.md
+++ b/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]).
└─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
diff --git a/lib/tasks/loomlib.rake b/lib/tasks/loomlib.rake
index ae51fc8..cb2f7c4 100644
--- a/lib/tasks/loomlib.rake
+++ b/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",
diff --git a/lib/tasks/rakefiles/loomlib_doc.rake b/lib/tasks/rakefiles/loomlib_doc.rake
index c045469..815f51d 100644
--- a/lib/tasks/rakefiles/loomlib_doc.rake
+++ b/lib/tasks/rakefiles/loomlib_doc.rake
@@ -11,7 +11,7 @@ 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()
@@ -19,33 +19,26 @@ def doc_build_dir()
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
diff --git a/lib/tasks/rakefiles/support.rb b/lib/tasks/rakefiles/support.rb
index 2b41245..c99c860 100644
--- a/lib/tasks/rakefiles/support.rb
+++ b/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)
diff --git a/lib/tasks/scaffolding.rake b/lib/tasks/scaffolding.rake
index 4e6fe48..b541903 100644
--- a/lib/tasks/scaffolding.rake
+++ b/lib/tasks/scaffolding.rake
@@ -93,11 +93,11 @@ 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()
@@ -105,7 +105,7 @@ def doc_index_pathname()
end
def doc_index_template()
- File.join(template_dir, 'index.md.erb')
+ File.join(template_dir, 'lsdoc_index.erb')
end
def lib_testapp_pathname()
diff --git a/lib/tasks/templates/lsdoc.config.erb b/lib/tasks/templates/lsdoc.config.erb
deleted file mode 100644
index 679e1dc..0000000
--- a/lib/tasks/templates/lsdoc.config.erb
+++ /dev/null
@@ -1,8 +0,0 @@
-{
- "project": {
- "name": "<%= lib_name %>",
- "repo": "",
- "owner": "",
- "version": "1.0.0"
- }
-}
diff --git a/lib/tasks/templates/lsdoc_config.erb b/lib/tasks/templates/lsdoc_config.erb
new file mode 100644
index 0000000..f93a0d9
--- /dev/null
+++ b/lib/tasks/templates/lsdoc_config.erb
@@ -0,0 +1,6 @@
+---
+project:
+ name: "<%= lib_name %>"
+ owner: ""
+ repo: ""
+ version: "1.0.0"
diff --git a/lib/tasks/templates/index.md.erb b/lib/tasks/templates/lsdoc_index.erb
similarity index 100%
rename from lib/tasks/templates/index.md.erb
rename to lib/tasks/templates/lsdoc_index.erb