From f3f81627f632d87b71749de7ecbd02b1c6d2ed08 Mon Sep 17 00:00:00 2001 From: ellemenno Date: Mon, 12 Nov 2018 16:29:39 -0500 Subject: [PATCH 1/4] update docs to work with remote_theme version of programming pages --- lib/tasks/rakefiles/loomlib_doc.rake | 205 ------------------ lib/tasks/rakefiles/loomlib_docs.rake | 141 ++++++++++++ lib/tasks/scaffolding.rake | 40 +++- lib/tasks/templates/lsdoc/Gemfile | 6 + lib/tasks/templates/lsdoc/config.erb | 35 +++ .../{lsdoc_index.erb => lsdoc/index.erb} | 4 +- lib/tasks/templates/lsdoc_config.erb | 6 - 7 files changed, 212 insertions(+), 225 deletions(-) delete mode 100644 lib/tasks/rakefiles/loomlib_doc.rake create mode 100644 lib/tasks/rakefiles/loomlib_docs.rake create mode 100644 lib/tasks/templates/lsdoc/Gemfile create mode 100644 lib/tasks/templates/lsdoc/config.erb rename lib/tasks/templates/{lsdoc_index.erb => lsdoc/index.erb} (51%) delete mode 100644 lib/tasks/templates/lsdoc_config.erb diff --git a/lib/tasks/rakefiles/loomlib_doc.rake b/lib/tasks/rakefiles/loomlib_doc.rake deleted file mode 100644 index 815f51d..0000000 --- a/lib/tasks/rakefiles/loomlib_doc.rake +++ /dev/null @@ -1,205 +0,0 @@ -require 'fileutils' -require 'net/http' -require 'open-uri' -require 'tmpdir' -require 'uri' - -require File.join(File.dirname(__FILE__), 'support') -include LoomTasks - - -@doc_config = nil - -def doc_config() - @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', 'src', '_config.yml') -end - -def write_doc_config(config) - LoomTasks.write_yaml_config(doc_config_file, config) -end - -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}", - "-c #{config_path}", - "-l #{sdk_dir}/libs/#{LoomTasks.const_lib_name}.loomlib", - "-i #{in_dir}", - "-o #{out_dir}", - ] - - cmd = "lsdoc #{options.join(' ')}" - try(cmd, "failed to generate docs") -end - -def update_doc_version() - lib_version = LoomTasks.lib_version(LoomTasks.const_lib_version_file) - doc_config['project']['version'] = doc_version - write_doc_config(doc_config) -end - -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 = 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['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 - - -[ - File.join('docs', '**'), -].each { |f| CLEAN << f } -[ - 'docs', -].each { |f| CLOBBER << f } - -FileList[ - File.join('doc', 'src', '*.*'), -].each do |src| - file LIB_DOC => [src] -end - -namespace :docs do - - task :check_tools do |t, args| - 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| - lib_version = LoomTasks.lib_version(LoomTasks.const_lib_version_file) - - doc_config['project']['version'] = lib_version - write_doc_config(doc_config) - - puts "[#{t.name}] task completed, #{doc_config_file} updated with version #{lib_version}" - end - - desc [ - "downloads the latest programming pages release from GitHub", - " installs to DOC_TEMPLATE_DIR", - ].join("\n") - task :install_template do |t, args| - puts "[#{t.name}] asking GitHub for latest release.." - - uri = URI(PP_RELEASE_API) - - begin - 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 - LoomTasks.fail("failed to connect; is there network access?") - end - - result = JSON.parse(response.body) - asset_url = result['assets'].first['browser_download_url'] - puts "[#{t.name}] found asset at '#{asset_url}'" - - FileUtils.remove_dir(DOC_TEMPLATE_DIR) if (Dir.exists?(DOC_TEMPLATE_DIR)) - - Dir.mktmpdir do |tmp_dir| - Dir.chdir(tmp_dir) do - puts "[#{t.name}] starting download.." - uri = URI(asset_url) - filepath = File.join('.', File.basename(asset_url)) - IO.write(filepath, uri.open().read()) - puts "[#{t.name}] download complete" - - puts "[#{t.name}] unzipping template.." - cmd = "unzip -q #{filepath}" - try(cmd, "unzip failed") - - puts "[#{t.name}] copying template files to DOC_TEMPLATE_DIR" - FileUtils.cp_r(Dir.glob('*/').first, DOC_TEMPLATE_DIR) - end - end - - puts "[#{t.name}] task completed, template installed to #{DOC_TEMPLATE_DIR}" - end - - desc [ - "creates api docs compatible with the programming pages template", - " https://github.com/pixeldroid/programming-pages", - "requires programming pages template to be installed", - "requires lsdoc to be installed", - "generates into temp dir at #{doc_build_dir}", - "expects user-generated documentation to be at doc/src/,", - "expects programming-pages template to be at doc/template/,", - "sets the library version number into #{doc_config_file}", - " #{doc_config_file} is expected to have a project.version key", - "outputs GitHub pages compatible files at docs/", - ].join("\n") - task :gen_api => ['docs:check_tools', 'lib:install', 'docs:update_version'] do |t, args| - pwd = Dir.pwd - config_path = File.join(pwd, 'doc', 'lsdoc.config') - template_dir = File.join(pwd, 'doc', 'template') - in_dir = File.join(pwd, 'doc', 'src') - out_dir = doc_build_dir - - if (Dir.exists?(out_dir)) - FileUtils.rm_r(Dir.glob(File.join(out_dir, '*'))) - puts "[#{t.name}] emptying #{out_dir} to start clean" - end - - puts "[#{t.name}] generating api files..." - build_docs(config_path, in_dir, 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)) - puts "[#{t.name}] removing temporary build dir #{doc_build_dir}" - FileUtils.rm_rf(doc_build_dir) - end - end - -end diff --git a/lib/tasks/rakefiles/loomlib_docs.rake b/lib/tasks/rakefiles/loomlib_docs.rake new file mode 100644 index 0000000..4045129 --- /dev/null +++ b/lib/tasks/rakefiles/loomlib_docs.rake @@ -0,0 +1,141 @@ +require 'fileutils' +require 'pathname' +require 'tmpdir' + +require File.join(File.dirname(__FILE__), 'support') +include LoomTasks + + +@doc_config = nil + +def doc_config() + @doc_config || (@doc_config = LoomTasks.parse_yaml_config(doc_config_file)) +end + +def doc_root_dir() + File.join(Pathname.pwd, 'docs') +end + +def doc_api_dir() + File.join(doc_root_dir, '_api') +end + +def doc_config_file() + File.join(doc_root_dir, '_config.yml') +end + +def write_doc_config(config) + LoomTasks.write_yaml_config(doc_config_file, config) +end + +def jekyll_cmd(verb) + "bundle exec jekyll #{verb} --source #{doc_root_dir} --layouts #{doc_root_dir}/_layouts" +end + +def jekyll_build + jekyll_cmd('build') +end + +def jekyll_serve + jekyll_cmd('serve') +end + +def jekyll_serve_only + "bundle exec jekyll serve --skip-initial-build --no-watch" +end + +def build_api_docs(out_dir) + sdk_version = lib_config['sdk_version'] + sdk_dir = LoomTasks.sdk_root(sdk_version) + processor = 'ghpages' + + options = [ + "-p #{processor}", + "-l #{sdk_dir}/libs/#{LoomTasks.const_lib_name}.loomlib", + "-o #{out_dir}", + ] + + cmd = "lsdoc #{options.join(' ')}" + try(cmd, "failed to generate docs") +end + + +TOOL_ERRORS = { + :lsdoc => 'lsdoc not installed. See https://github.com/pixeldroid/lsdoc', + :bundler => 'gem dependencies not all resolved. Please run `bundle install`', +} + +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 + + +namespace :docs do + + task :check_tools do |t, args| + LoomTasks.fail(TOOL_ERRORS[:lsdoc]) unless LoomTasks.path_to_exe('lsdoc') + LoomTasks.fail(TOOL_ERRORS[:bundler]) unless (LoomTasks.exec_with_echo('bundle check') == LoomTasks::EXIT_OK) + end + + task :update_version do |t, args| + lib_version = LoomTasks.lib_version(LoomTasks.const_lib_version_file) + + doc_config['project']['version'] = lib_version + write_doc_config(doc_config) + + puts "[#{t.name}] task completed, #{doc_config_file} updated with version #{lib_version}" + end + + desc [ + "creates api docs compatible with the programming pages template", + " https://github.com/pixeldroid/programming-pages", + "outputs GitHub pages compatible files at docs/", + "requires lsdoc to be installed", + "sets the library version number into #{doc_config_file}", + " #{doc_config_file} is expected to have a project.version key", + ].join("\n") + task :gen_api => ['docs:check_tools', 'docs:update_version'] do |t, args| + + if (Dir.exists?(doc_api_dir)) + FileUtils.rm_r(Dir.glob(File.join(doc_api_dir, '*'))) + puts "[#{t.name}] emptying #{doc_api_dir} to start clean" + end + + puts "[#{t.name}] generating api files..." + build_api_docs(doc_root_dir) + + puts "[#{t.name}] task completed, api docs generated into #{doc_api_dir}" + end + + desc [ + "calls jekyll to [just] generate the docs site", + " cmd: #{jekyll_build}", + ].join("\n") + task :build_site => ['docs:gen_api'] do |t, args| + try(jekyll_build, 'unable to create docs') + puts "[#{t.name}] task completed, find updated docs in ./_site" + end + + desc [ + "calls jekyll to serve the docs site, without first building it", + " cmd: #{jekyll_serve_only}", + ].join("\n") + task :serve_site do |t, args| + begin # run jekyll + puts jekyll_serve_only + system(jekyll_serve_only) + rescue Exception => e # capture the interrupt signal from a quit app + puts ' (quit)' + end + end + +end + +desc [ + "builds and serves the documentation site", +].join("\n") +task :docs => ['docs:build_site', 'docs:serve_site'] diff --git a/lib/tasks/scaffolding.rake b/lib/tasks/scaffolding.rake index b541903..64e0861 100644 --- a/lib/tasks/scaffolding.rake +++ b/lib/tasks/scaffolding.rake @@ -92,20 +92,32 @@ def demo_gui_template() File.join(template_dir, 'LoomlibDemoGUI.ls.erb') end -def doc_config_pathname() - File.join(Dir.pwd, 'doc', 'src', '_config.yml') +def lsdoc_pathname() + File.join(Dir.home, '.loom', 'LSDoc') end -def doc_config_template() - File.join(template_dir, 'lsdoc_config.erb') +def docs_pathname() + File.join(Dir.pwd, 'docs') end -def doc_index_pathname() - File.join(Dir.pwd, 'doc', 'src', 'index.md') +def docs_gemfile() + File.join(template_dir, 'lsdoc', 'Gemfile') end -def doc_index_template() - File.join(template_dir, 'lsdoc_index.erb') +def docs_config_pathname() + File.join(docs_pathname, '_config.yml') +end + +def docs_config_template() + File.join(template_dir, 'lsdoc', 'config.erb') +end + +def docs_index_pathname() + File.join(docs_pathname, 'index.md') +end + +def docs_index_template() + File.join(template_dir, 'lsdoc', 'index.erb') end def lib_testapp_pathname() @@ -287,11 +299,15 @@ namespace :new do create_from_template(cli_wrapper_pathname, cli_wrapper_template, context) end - task :doc do |t, args| + task :docs do |t, args| context = template_context - create_from_template(doc_config_pathname, doc_config_template, context) - create_from_template(doc_index_pathname, doc_index_template, context) + copy_from_template(docs_pathname, docs_gemfile) + create_from_template(docs_config_pathname, docs_config_template, context) + create_from_template(docs_index_pathname, docs_index_template, context) + copy_from_template(docs_pathname, File.join(lsdoc_pathname, '_data')) + copy_from_template(docs_pathname, File.join(lsdoc_pathname, '_includes')) + copy_from_template(docs_pathname, File.join(lsdoc_pathname, '_layouts')) end task :gui do |t, args| @@ -325,7 +341,7 @@ namespace :new do create_from_template(lib_testspec_pathname, lib_testspec_template, context) end - task :scaffold => [:gitignore, :rakefile, :lib, :test, :cli, :gui, :doc] + task :scaffold => [:gitignore, :rakefile, :lib, :test, :cli, :gui, :docs] desc [ "scaffolds the directories and files for a new loomlib project", diff --git a/lib/tasks/templates/lsdoc/Gemfile b/lib/tasks/templates/lsdoc/Gemfile new file mode 100644 index 0000000..d3d8457 --- /dev/null +++ b/lib/tasks/templates/lsdoc/Gemfile @@ -0,0 +1,6 @@ +source 'https://rubygems.org' + +gem 'github-pages', '~> 192' + +gem 'bundler', '~> 1.16' +gem 'rake', '~> 12.0' diff --git a/lib/tasks/templates/lsdoc/config.erb b/lib/tasks/templates/lsdoc/config.erb new file mode 100644 index 0000000..f67d182 --- /dev/null +++ b/lib/tasks/templates/lsdoc/config.erb @@ -0,0 +1,35 @@ +--- +project: + name: "<%= lib_name %>" + owner: "" + repo: "" + version: "1.0.0" + +collections: + api: + output: true + ignore-page-order: true + permalink: "/:collection/:path/" + title: API + tab-order: 1 + examples: + output: true + permalink: "/:collection/:path/" + title: Examples + tab-order: 2 + guides: + output: true + permalink: "/:collection/:path/" + title: Guides + tab-order: 3 + +code_indent: " " +highlighter: rouge +permalink: pretty +sass: + style: compressed + +plugins: + - jemoji + - jekyll-remote-theme +remote_theme: pixeldroid/programming-pages diff --git a/lib/tasks/templates/lsdoc_index.erb b/lib/tasks/templates/lsdoc/index.erb similarity index 51% rename from lib/tasks/templates/lsdoc_index.erb rename to lib/tasks/templates/lsdoc/index.erb index 3b60126..2bb929b 100644 --- a/lib/tasks/templates/lsdoc_index.erb +++ b/lib/tasks/templates/lsdoc/index.erb @@ -9,7 +9,7 @@ this: "**<%= lib_name %>**" {{ page.this }} is a new library ready for documentation. > Edit `doc/index.md` to change what this page looks like. -> See [lsdoc][lsdoc] for feature and usage details +> See [programming pages] for feature and usage details -[lsdoc]: https://github.com/pixeldroid/lsdoc "an API docs generator for LoomScript" +[programming pages]: https://github.com/pixeldroid/programming-pages "a jekyll theme for publishing code documentation to GitHub pages" diff --git a/lib/tasks/templates/lsdoc_config.erb b/lib/tasks/templates/lsdoc_config.erb deleted file mode 100644 index f93a0d9..0000000 --- a/lib/tasks/templates/lsdoc_config.erb +++ /dev/null @@ -1,6 +0,0 @@ ---- -project: - name: "<%= lib_name %>" - owner: "" - repo: "" - version: "1.0.0" From c92b122654cd7de7bb587fd0bf5c9a441526f897 Mon Sep 17 00:00:00 2001 From: ellemenno Date: Mon, 12 Nov 2018 16:31:53 -0500 Subject: [PATCH 2/4] update version to 3.2.2 --- lib/tasks/rakefiles/support.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/tasks/rakefiles/support.rb b/lib/tasks/rakefiles/support.rb index c99c860..e18a9d0 100644 --- a/lib/tasks/rakefiles/support.rb +++ b/lib/tasks/rakefiles/support.rb @@ -6,7 +6,7 @@ module LoomTasks - VERSION = '3.2.0' + VERSION = '3.2.2' EXIT_OK = 0 From 620823a3d07f4e45318c45e8b01d256540f1851b Mon Sep 17 00:00:00 2001 From: ellemenno Date: Mon, 12 Nov 2018 16:35:50 -0500 Subject: [PATCH 3/4] update README with latest task list --- README.md | 72 +++++++++++++++++++++++++++---------------------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 9d8ede2..3507dd8 100644 --- a/README.md +++ b/README.md @@ -53,44 +53,42 @@ Then, enter your development cycle: Running `rake` in your project directory will execute the default task, which prints the list of available tasks and a short description of what they do: - Foo v1.2.3 Rakefile running on Ruby 2.4.1 - rake clean # removes intermediate files to ensure a clean build - rake cli[options] # shorthand for 'rake cli:run' - rake cli:build # builds cli/bin/FooDemoCLI.loom for sprint34 SDK - rake cli:install[b,p] # installs an executable copy of cli/bin/FooDemoCLI.loom on the system - rake cli:run[options] # executes cli/bin/FooDemoCLI.loom as a commandline app, with options, if provided - rake cli:sdk[id] # sets the provided SDK version into cli/loom.config - rake cli:uninstall[b,p] # uninstalls the system executable 'foo' - rake clobber # removes all generated artifacts to restore project to checkout-like state - 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 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 - rake gui:sdk[id] # sets the provided SDK version into gui/loom.config - rake help # shows usage and project info, optionally for a specific command - rake lib:build # builds Foo.loomlib for sprint34 SDK - rake lib:install # installs Foo.loomlib into sprint34 SDK - rake lib:release # prepares sdk-specific Foo.loomlib for release, and updates version in README - rake lib:sdk[id] # sets the provided SDK version into lib/loom.config - rake lib:show # lists libs installed for sprint34 SDK - rake lib:uninstall # removes Foo.loomlib from sprint34 SDK - rake lib:version[v] # sets the library version number into lib/src/Foo.build and lib/src/Foo.ls - 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 3.2.0) + $ rake + Foo v1.2.3 Rakefile running on Ruby 2.5.1 + rake clean # removes intermediate files to ensure a clean build + rake cli[options] # shorthand for 'rake cli:run' + rake cli:build # builds cli/bin/FooDemoCLI.loom for sprint34 SDK + rake cli:install[b,p] # installs an executable copy of cli/bin/FooDemoCLI.loom on the system + rake cli:run[options] # executes cli/bin/FooDemoCLI.loom as a commandline app, with options, if provided + rake cli:sdk[id] # sets the provided SDK version into cli/loom.config + rake cli:uninstall[b,p] # uninstalls the system executable 'foo' + rake clobber # removes all generated artifacts to restore project to checkout-like state + rake docs # builds and serves the documentation site + rake docs:build_site # calls jekyll to [just] generate the docs site + rake docs:gen_api # creates api docs compatible with the programming pages template + rake docs:serve_site # calls jekyll to serve the docs site, without first building it + 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 + rake gui:sdk[id] # sets the provided SDK version into gui/loom.config + rake help # shows usage and project info, optionally for a specific command + rake lib:build # builds Foo.loomlib for sprint34 SDK + rake lib:install # installs Foo.loomlib into sprint34 SDK + rake lib:release # prepares sdk-specific Foo.loomlib for release, and updates version in README + rake lib:sdk[id] # sets the provided SDK version into lib/loom.config + rake lib:show # lists libs installed for sprint34 SDK + rake lib:uninstall # removes Foo.loomlib from sprint34 SDK + rake lib:version[v] # sets the library version number into lib/src/Foo.build and lib/src/Foo.ls + 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 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 3.2.2) (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`. From 7bb269314bef27575eddd56c505b1e68015f5782 Mon Sep 17 00:00:00 2001 From: ellemenno Date: Mon, 12 Nov 2018 16:49:30 -0500 Subject: [PATCH 4/4] update README --- README.md | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 3507dd8..3d66dd7 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ Then, enter your development cycle: 1. Run `test` to see the auto-created library be built, the test harness run, and the first test fail: * `rake test` 1. Add new code and improved tests (in `lib/src/`, and `test/src/`) -1. Add new documentation (in `doc/src/`), and regenerate before commits back to GitHub: +1. Add new documentation (in `docs/`), and regenerate before commits back to GitHub: * `rake docs` ### more details @@ -92,7 +92,7 @@ Running `rake` in your project directory will execute the default task, which pr 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 [Programming Pages][programming-pages] theme is not packaged with loomtasks releases; it is leveraged via the `remote_theme` plugin for Jekyll. This is compatible with Github Pages. 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. @@ -106,7 +106,8 @@ The loomlib rake tasks make the following assumptions about the layout of a proj foo-loomlib $ ├─cli/ - ├─doc/ + ├─docs/ + ├─Gemfile ├─gui/ ├─lib/ ├─Rakefile @@ -114,7 +115,8 @@ The loomlib rake tasks make the following assumptions about the layout of a proj * library source is under `lib/` * source for a CLI demo is under `cli/`; the CLI demo app will consume the library and illustrate its use from the command line -* documentation source is under `doc/`; [lsdoc][lsdoc] is the supported doc generation tool +* documentation source is under `docs/`; [lsdoc][lsdoc] is the supported API doc generation tool +* the project uses a `Gemfile` for building and serving documentation locally with Jekyll and the Github Pages gem * source for a GUI demo is under `gui/`; the GUI demo app will consume the library and illustrate its use via a graphical user interface * the project uses a `Rakefile` for building, testing, and preparing releases * library test source is under `test/`; the test app will consume the library and exercise it @@ -125,22 +127,23 @@ The loomlib rake tasks make the following assumptions about the layout of a proj Support for docs tasks comes from [`loomlib_doc.rake`](lib/tasks/rakefiles/loomlib_doc.rake). 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]).
+`docs/` contains configuration and source files to be converted into documentation. The documentation is not packaged with the loomlib; it is generated into a site from `docs/` directory by [GitHub pages][gh-pages]. Note that this requires an option be set for the source code repository (see [Publishing from a docs/ folder][gh-docs]).
- └─doc - ├─src/ - │ ├─_config.yml - │ ├─examples/ - │ ├─guides/ - │ └─index.md - └─template/ + └─docs + ├─_api/ + ├─_config.yml + ├─_data/ + ├─_includes/ + ├─_layouts/ + ├─examples/ + ├─guides/ + └─index.md -* 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 files under `doc/` to create a site under `docs/` that GitHub Pages will render after it is pushed to your GitHub repository +* project level configuration for jekyll and the site theme is defined in `docs/_config.yml` +* the documentation home page is written in markdown as `docs/index.md` +* (optional) example pages are written under `docs/examples/`; they will have their own tab in the generated docs site +* (optional) guide pages are written under `docs/guides/`; they will have their own tab in the generated docs site +* [lsdoc][lsdoc] provides some files under `docs/_data/`, `docs/_includes/`, and `docs/_layouts/` to facilitate documentation generation. Use of [Programming Pages][programming-pages] is assumed #### demos @@ -166,7 +169,7 @@ Support for GUI demo tasks comes from [`loomlib_gui.rake`](lib/tasks/rakefiles/l `gui/` contains a functional graphical demonstration app.
└─gui - ├─assets + ├─assets/ ├─bin │ └─Main.loom ├─loom.config