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