Merge pull request #424 from DannyBen/refactor/render-model

Refactor render command with RenderSource model

Author: DannyBen

.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
  LC_ALL: en_US.UTF-8 
 
  strategy:
- matrix: { ruby: ['3.0', '3.1', '3.2', head] }
+ matrix: { ruby: ['3.0', '3.1', '3.2'] }
 
  steps:
  - name: Checkout code

bashly.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
  s.add_dependency 'gtx', '~> 0.1'
  s.add_dependency 'lp', '~> 0.2'
  s.add_dependency 'mister_bin', '~> 0.7'
+ s.add_dependency 'tty-markdown', '~> 0.7'
 
  # Ruby 3.0 comes with Psych 3.3.0, which does not have the `unsafe_load`
  # ref: https://github.com/ruby/psych/commit/cb50aa8d3fb8be01897becff77b4922b12a0ab4c

lib/bashly.rb

@@ -16,6 +16,8 @@ module Bashly
  autoload :Library, 'bashly/library'
  autoload :LibrarySource, 'bashly/library_source'
  autoload :MessageStrings, 'bashly/message_strings'
+ autoload :RenderContext, 'bashly/render_context'
+ autoload :RenderSource, 'bashly/render_source'
  autoload :VERSION, 'bashly/version'
 
  autoload :AssetHelper, 'bashly/concerns/asset_helper'

lib/bashly/commands/render.rb

@@ -1,96 +1,93 @@
 require 'filewatcher'
-require 'date' # for use by templates
+require 'tty-markdown'
 
 module Bashly
  module Commands
  class Render < Base
  help 'Render the bashly data structure using cutsom templates'
 
  usage 'bashly render SOURCE TARGET [options]'
+ usage 'bashly render SOURCE --about'
+ usage 'bashly render --list'
  usage 'bashly render (-h|--help)'
 
  param 'SOURCE', <<~HELP
  An ID to an internal templates source, or a path to a custom templates directory.
 
- A leading colon (:) denotes an internal ID.
-
- Available IDs:
- - :markdown - render markdown documents for each command.
- - :mandoc - render man pages for each command.
+ A leading colon (:) denotes an internal ID (see `--list`).
  HELP
 
  param 'TARGET', 'Output directory'
 
  option '-w --watch', 'Watch bashly.yml and the templates source for changes and render on change'
+ option '-l --list', 'Show list of built-in templates'
+ option '-a --about', 'Show information about a given templates source'
 
+ example 'bashly render --list'
+ example 'bashly render :markdown --about'
  example 'bashly render :markdown docs --watch'
  example 'bashly render /path/to/templates ./out_path'
 
- attr_reader :watching, :source, :target
+ attr_reader :watching, :target, :source
 
  def run
- @source = source_path
- @target = args['TARGET']
- @watching = args['--watch']
-
- render
- watch if watching
+ if args['--list'] then show_list
+ elsif args['--about'] then show_about
+ else
+ start_render
+ end
  end
 
  private
 
- # This method is the single DSL method for the render script
- def save(filename, content)
- File.deep_write filename, content
- say "g`saved` #{filename}"
+ def show_list
+ RenderSource.internal.each_value do |source|
+ say "g`:#{source.selector.to_s.ljust 10}` #{source.summary}"
+ end
+ end
+
+ def show_about
+ puts TTY::Markdown.parse(render_source.readme)
  end
 
- def watch
- say "g`watching`\n"
+ def render_source
+ @render_source ||= begin
+ source = RenderSource.new selector
+ raise "Invalid render source: #{args['SOURCE']}" unless source.exist?
 
- Filewatcher.new(watchables).watch do
- reset
- render
- rescue Bashly::ConfigurationError => e
- say! "rib` #{e.class} `\n#{e.message}"
- ensure
- say "g`waiting`\n"
+ source
  end
  end
 
- def render
- with_valid_config { instance_eval render_script }
- end
+ def selector
+ return args['SOURCE'] unless args['SOURCE'].start_with? ':'
 
- def reset
- @config = nil
- @config_validator = nil
- @command = nil
+ args['SOURCE'][1..].to_sym
  end
 
- def command
- @command ||= Script::Command.new config
+ def start_render
+ @target = args['TARGET']
+ @watching = args['--watch']
+
+ render
+ watch if watching
  end
 
- def watchables
- @watchables ||= [Settings.config_path, source]
+ def render
+ render_source.render target
  end
 
- def source_path
- result = args['SOURCE']
+ def watch
+ say "g`watching`\n"
 
- if result.start_with? ':'
- id = result[1..]
- result = asset "libraries/render/#{id}"
+ Filewatcher.new(watchables).watch do
+ render
+ say "g`waiting`\n"
  end
-
- return result if Dir.exist? result
-
- raise "Invalid source.\nDirectory not found: #{result}"
  end
 
- def render_script
- @render_script ||= File.read "#{source}/render.rb"
+ def watchables
+ @watchables ||= [Settings.config_path, args['SOURCE']]
  end
  end
  end

lib/bashly/libraries/libraries.yml

@@ -60,6 +60,8 @@ render_markdown:
  help: Copy the markdown templates to your project, allowing you to customize the markdown documentation output.
  skip_src_check: true
  files:
+ - source: "render/markdown/README.md"
+ target: "templates/markdown/README.md"
  - source: "render/markdown/markdown.gtx"
  target: "templates/markdown/markdown.gtx"
  - source: "render/markdown/render.rb"
@@ -73,6 +75,8 @@ render_mandoc:
  help: Copy the mandoc templates to your project, allowing you to customize the man documentation output.
  skip_src_check: true
  files:
+ - source: "render/mandoc/README.md"
+ target: "templates/mandoc/README.md"
  - source: "render/mandoc/mandoc.gtx"
  target: "templates/mandoc/mandoc.gtx"
  - source: "render/mandoc/render.rb"

lib/bashly/libraries/render/mandoc/README.md

@@ -0,0 +1,23 @@
+# Render mandoc
+
+Render man pages for your script.
+
+Note that this renderer will render specially formatted markdown documents and
+will then use [pandoc](https://command-not-found.com/pandoc) to convert them.
+
+Setting the environment variable `PREVIEW` to the full command you wish to
+preview, will prompt the renderer to show the output using the `man` command
+after rendering.
+
+## Usage
+
+```bash
+# Generate all man pages to the ./docs directory
+$ bashly render :mandoc docs
+
+# .. and also preview the page for the "cli download" command
+$ PREVIEW="cli download" bashly render :mandoc docs
+
+# .. and also watch for changes
+$ PREVIEW="cli download" bashly render :mandoc docs --watch
+```

lib/bashly/libraries/render/mandoc/render.rb

@@ -1,14 +1,5 @@
 # render script - mandoc
-#
-# You may set the environment variable PREVIEW to the full command you wich 
-# to preview while generating. For example:
-#
-# PREVIEW="cli download" bashly render :mandoc docs --watch
-#
-# Alternatively, view any of the man pages with man:
-#
-# man docs/cli.1
-#
+require 'gtx'
 
 # Load the GTX template
 template = "#{source}/mandoc.gtx"

lib/bashly/libraries/render/mandoc/summary.txt

@@ -0,0 +1 @@
+Render man pages for your script

lib/bashly/libraries/render/markdown/README.md

@@ -0,0 +1,20 @@
+# Render markdown
+
+Render markdown documents for your script.
+
+## Usage
+
+```bash
+# Generate all documents to the ./docs directory
+$ bashly render :markdown docs
+```
+
+## Viewing your markdown documents
+
+In order to preview your markdown files, you can use the
+[Madness markdown server](https://madness.dannyb.co/):
+
+```bash
+$ gem install madness
+$ madness server docs
+```

lib/bashly/libraries/render/markdown/render.rb

@@ -1,11 +1,5 @@
 # render script - markdown
-#
-# In order to preview your markdown files, you can use the madness markdown
-# server <https://madness.dannyb.co/>:
-#
-# $ gem install madness
-# $ madness server docs
-#
+require 'gtx'
 
 # Load the GTX template
 template = "#{source}/markdown.gtx"