Document rendering improvements

examples/render-mandoc/test.sh

@@ -2,7 +2,7 @@
 
 rm -f ./src/*.sh
 
-set -x
+# set -x   # can't use this here, since the piped command appears in random order
 
 bashly render :mandoc docs
 

lib/bashly/commands/render.rb

@@ -6,7 +6,7 @@ module Commands
     class Render < Base
       help 'Render the bashly data structure using cutsom templates'
 
-      usage 'bashly render SOURCE TARGET [options]'
+      usage 'bashly render SOURCE TARGET [--watch --show PATH]'
       usage 'bashly render SOURCE --about'
       usage 'bashly render --list'
       usage 'bashly render (-h|--help)'
@@ -20,12 +20,21 @@ class Render < Base
       param 'TARGET', 'Output directory'
 
       option '-w --watch', 'Watch bashly.yml and the templates source for changes and render on change'
+      option '-s --show PATH', <<~USAGE
+        After rendering, show the result generated in PATH.
+
+        The provided PATH is treated as relative TARGET.
+
+        Note that this works only if the template source supports it.
+      USAGE
+
       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 :markdown docs --show "cli-download.1"'
       example 'bashly render /path/to/templates ./out_path'
 
       attr_reader :watching, :target, :source
@@ -50,21 +59,6 @@ def show_about
         puts TTY::Markdown.parse(render_source.readme)
       end
 
-      def render_source
-        @render_source ||= begin
-          source = RenderSource.new selector
-          raise "Invalid render source: #{args['SOURCE']}" unless source.exist?
-
-          source
-        end
-      end
-
-      def selector
-        return args['SOURCE'] unless args['SOURCE'].start_with? ':'
-
-        args['SOURCE'][1..].to_sym
-      end
-
       def start_render
         @target = args['TARGET']
         @watching = args['--watch']
@@ -74,7 +68,7 @@ def start_render
       end
 
       def render
-        render_source.render target
+        render_source.render target, show: args['--show']
       end
 
       def watch
@@ -86,6 +80,21 @@ def watch
         end
       end
 
+      def render_source
+        @render_source ||= begin
+          source = RenderSource.new selector
+          raise "Invalid render source: #{args['SOURCE']}" unless source.exist?
+
+          source
+        end
+      end
+
+      def selector
+        return args['SOURCE'] unless args['SOURCE'].start_with? ':'
+
+        args['SOURCE'][1..].to_sym
+      end
+
       def watchables
         @watchables ||= [Settings.config_path, render_source.path]
       end

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

@@ -10,30 +10,9 @@ will then use [pandoc](https://command-not-found.com/pandoc) to convert them.
 ```bash
 # Generate all man pages to the ./docs directory
 $ bashly render :mandoc docs
-```
-
-## Viewing the output
-
-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.
-
-```bash
-# Preview the page for the "cli download" command
-$ PREVIEW="cli download" bashly render :mandoc docs
-
-# .. and also watch for changes (after existing the man preview)
-$ PREVIEW="cli download" bashly render :mandoc docs --watch
-```
-
-In addition, you can use one of the following commands:
-
-```bash
-# View the man page interactively
-$ man docs/cli-download.1
 
-# Print the man page to stdout
-$ man docs/cli-download.1 | col -bx
+# Generate on change, and show one of the files
+$ bashly render :mandoc docs --watch --show cli-download.1
 ```
 
 ## Supported custom definitions

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

@@ -17,8 +17,6 @@
   raise "Failed running pandoc\nMake sure the following command succeeds and try again:\n\n  #{cmd}" unless success
 
   say "g`saved` #{manfile}"
-
-  system %[man "#{manfile}"] if ENV['PREVIEW'] == command.full_name
 }
 
 # Render the main command
@@ -28,3 +26,9 @@
 command.deep_commands.reject(&:private).each do |subcommand|
   save_manpage.call subcommand
 end
+
+# Show one of the files if requested
+if show
+  file = "#{target}/#{show}"
+  system "man #{file}" if File.exist?(file)
+end

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

@@ -7,16 +7,9 @@ Render markdown documents for your script.
 ```bash
 # Generate all documents to the ./docs directory
 $ bashly render :markdown docs
-```
-
-## Viewing the output
-
-In order to view your markdown files, you can use
-[Madness markdown server](https://madness.dannyb.co/):
 
-```bash
-$ gem install madness
-$ madness server docs
+# Generate on change, and show one of the files
+$ bashly render :markdown docs --watch --show index.md
 ```
 
 ## Supported custom definitions
@@ -37,3 +30,13 @@ x_markdown_footer: |-
 
   Report issues at <https://github.com/lanalang/smallville>
 ```
+
+## Markdown server
+
+In order to view your markdown files in a browser, you can use the
+[Madness markdown server](https://madness.dannyb.co/):
+
+```bash
+$ gem install madness
+$ madness server docs
+```

lib/bashly/libraries/render/markdown/markdown.gtx

@@ -94,7 +94,7 @@ if commands.any?
     > ## {{ group.gsub(/:$/, '') }}
     >
     commands.each do |subcommand|
-      > - [{{ subcommand.name }}]({{ subcommand.full_name }}) - {{ subcommand.summary.for_markdown }}
+      > - [{{ subcommand.name }}]({{ subcommand.full_name.gsub(' ', '%20') }}) - {{ subcommand.summary.for_markdown }}
     end
     >
   end

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

@@ -1,6 +1,9 @@
 # render script - markdown
 require 'gtx'
 
+# for previewing only (not needed for rendering)
+require 'tty-markdown'
+
 # Load the GTX template
 template = "#{source}/markdown.gtx"
 gtx = GTX.load_file template
@@ -12,3 +15,9 @@
 command.deep_commands.reject(&:private).each do |subcommand|
   save "#{target}/#{subcommand.full_name}.md", gtx.parse(subcommand)
 end
+
+# Show one of the files if requested
+if show
+  file = "#{target}/#{show}"
+  puts TTY::Markdown.parse_file(file) if File.exist?(file)
+end

lib/bashly/render_context.rb

@@ -5,11 +5,13 @@ module Bashly
   class RenderContext
     include Colsole
 
-    attr_reader :source, :target
+    attr_reader :source, :target, :show
+    attr_writer :config
 
-    def initialize(source, target)
+    def initialize(source:, target:, show: nil)
       @source = source
       @target = target
+      @show = show
     end
 
     def config

lib/bashly/render_source.rb

@@ -25,8 +25,9 @@ def initialize(selector)
       @selector = selector
     end
 
-    def render(target)
-      RenderContext.new(path, target).instance_eval render_script
+    def render(target, show: nil)
+      context = RenderContext.new source: path, target: target, show: show
+      context.instance_eval render_script
     end
 
     def internal?

spec/approvals/cli/render/about-markdown

@@ -1,34 +1 @@
-Render markdown
-
-Render markdown documents for your script.
-
-  Usage
-
-  # Generate all documents to the ./docs directory
-  $ bashly render :markdown docs
-
-  Viewing the output
-
-  In order to view your markdown files, you can use
-  Madness markdown server » https://madness.dannyb.co/:
-
-  $ gem install madness
-  $ madness server docs
-
-  Supported custom definitions
-
-  Add these definitions to your bashly.yml to render them in your
-  markdown:
-
-    Footer: x_markdown_footer
-
-    Add additional sections to your man pages. This field is expected
-    to be in markdown format.
-
-      Example
-
-      x_markdown_footer: |-
-        # ISSUE TRACKER
-
-        Report issues at <https://github.com/lanalang/smallville>
-
+Heading

spec/approvals/cli/render/help

@@ -1,7 +1,7 @@
 Render the bashly data structure using cutsom templates
 
 Usage:
-  bashly render SOURCE TARGET [options]
+  bashly render SOURCE TARGET [--watch --show PATH]
   bashly render SOURCE --about
   bashly render --list
   bashly render (-h|--help)
@@ -10,6 +10,13 @@ Options:
   -w --watch
     Watch bashly.yml and the templates source for changes and render on change
 
+  -s --show PATH
+    After rendering, show the result generated in PATH.
+
+    The provided PATH is treated as relative TARGET.
+
+    Note that this works only if the template source supports it.
+
   -l --list
     Show list of built-in templates
 
@@ -33,4 +40,5 @@ Examples:
   bashly render --list
   bashly render :markdown --about
   bashly render :markdown docs --watch
+  bashly render :markdown docs --show "cli-download.1"
   bashly render /path/to/templates ./out_path

spec/approvals/cli/render/watch

@@ -1,10 +1,4 @@
-saved spec/tmp/index.md
-saved spec/tmp/cli download.md
-saved spec/tmp/cli upload.md
 watching
 
-saved spec/tmp/index.md
-saved spec/tmp/cli download.md
-saved spec/tmp/cli upload.md
 waiting
 

spec/approvals/examples/render-mandoc

@@ -1,8 +1,5 @@
-+ bashly render :mandoc docs
 saved docs/download.md
 saved docs/download.1
-+ man docs/download.1
-+ col -bx
 download(1)                   Sample application                   download(1)
 
 NAME

spec/approvals/libraries/render/mandoc/render-1

@@ -0,0 +1,2 @@
+saved spec/tmp/download.md
+saved spec/tmp/download.1

spec/approvals/libraries/render/mandoc/render-1-download.1

@@ -0,0 +1,32 @@
+download(1)       Sample minimal application without commands      download(1)
+
+NAME
+       download - Sample minimal application without commands
+
+SYNOPSIS
+       download SOURCE TARGET OPTIONS
+
+DESCRIPTION
+       Sample minimal application without commands
+
+ARGUMENTS
+   SOURCE
+       URL to download from
+
+       • Required
+
+   TARGET
+       Target filename (default: same as source)
+
+OPTIONS
+   --force, -f
+       Overwrite existing files
+
+EXAMPLES
+
+              download example.com
+
+              download example.com ./output -f
+
+
+Version 0.1.0                     August 2023                      download(1)