Proposal: Render the bashly configuration using custom templates for documentation

[DannyBen]

Requests to be able to create documentation from the bashly.yml file were raised several times:

• Generate user documentation from bashly.yml #69
• shdoc integration #414
• Generate man pages from bashly.yml #421

Related PRs:

• Add ability to render documentation #417
• Add bashly add render_markdown library #419
• Refactor markdown template #420
• Add ability to render man pages and bashly add render_mandoc library #422
• Improve manpage template #423
• Refactor render command with RenderSource model #424

---

Since it could be quite complex to support all use cases, and all of bashly's features, I would like to propose this in order to gauge interest:

1. We will add a bashly render TEMPLATE command, which will accept a path to a user-provided template.
2. The template will have access all the data that bashly has (commands, args, flags)
3. The template will have the ability to use loops and conditions (in Ruby).
4. In addition, we will add a bashly add markdown-template and bashly add manpage-template that will provide a basic starting point for the developers to update as they see fit.

This will allow fully customizable output, for documentation, or anything else. It can even be used for generating scripts in other languages if someone chooses to do so...

The template will be in gtx format - the same format used by bashly itself.

Example Template

For orientation, anything that starts with > is an output, and anything else is Ruby code.

> # {{ name }}
>
> {{ help }}
>
> ## Commands
>

commands.each do |command|
  > ### {{ command.name }}
  >
  > {{ command.help }}
  >
  > Usage: `{{ command.usage_string }}`
  >
  > #### Arguments
  >
  > | Argument | Description 
  > |----------|-------------

  command.args.each do |arg|
    > | `{{ arg.name }}` | {{ arg.help }}
  end

  >
  > #### Flags
  >
  > | Flag | Description 
  > |------|-------------
  command.flags.each do |flag|
    > | `{{ flag.name }}` | {{ flag.help }}
  end
  >

end

Test script

This will be the code behind the future bashly render TEMPLATE command:

require 'bashly'

config = Bashly::Config.new 'bashly.yml'
command = Bashly::Script::Command.new config
view = 'template.gtx'
gtx = GTX.load_file view

result = gtx.parse command

puts result  

Sample output

Show markdown output

cli

Sample application

Commands

download

Download a file

Usage: cli download SOURCE [TARGET] [OPTIONS]

Arguments

Argument	Description
source	URL to download from
target	Target filename (default: same as source)

Flags

Flag	Description
--force	Overwrite existing files

upload

Upload a file

Usage: cli upload SOURCE [OPTIONS]

Arguments

Argument	Description
source	File to upload

Flags

Flag	Description
--user	Username to use for logging in
--password	Password to use for logging in

Any thoughts or suggestions are welcome.

[DannyBen]

Mission Impossible Accomplished.

This was quite a lot of work, but I am satisfied with the result. The changes are in master branch, and the edge version - it would be nice if someone else can test it to see see if it makes sense.

• People can now render markdown and man pages from their bashly.yml
  • by simply running bashly render :markdown docs or bashly render :mandoc docs
• Adding additional rendering templates is easy and flexible - the two built-in templates are here.
• If someone doesn't like the default output, they can easily "clone" the templates to their project and use the same bashly render command to render using their own version of the templates.
  • by running bashly add render_markdown or bashly add render_mandoc

This gives me peace of mind knowing that I do not need to update the templates based on every single user's opinion, and yet they can still achieve their optimum output if they choose to.

The unreleased documentation is here.

[DannyBen]

Bashly version 1.1.0 is released with support for:

• Rendering Markdown documentation.
• Rendering Mandoc documentation.
• Rendering custom documentation (or scripts) with user-defined templates.

Examples:

• Markdown
• Mandoc

👉 Documentation