# Rendering Documentation

# Overview

Bashly is capable of rendering documentation for your script based on your bashly.yml configuration by using the bashly render command.

This command can generate any kind of output using either templates that are built in in Bashly (for example Markdown or man pages), or by using any custom templates.

# Built-in templates

Bashly comes with several documentation templates. In order to see a list of all templates, run:

$ bashly render --list

Some built in templates may have special optional features that let you customize the output. Learn more about each template by running:

$ bashly render SOURCE --about
# for example
$ bashly render :mandoc --about

# Example

Markdown Example Mandoc Example

# Custom templates

# Create your own

To create custom templates, it is recommended to use one of the built-in templates as a starting point. To copy the template source code to your project run:

$ bashly add render_markdown
# or
$ bashly add render_mandoc

Note

Creating custom templates requires some minimal understanding of Ruby.

# Template structure

Template directories are expected to:

Have a render.rb file
Will be executed when running bashly render.
Have a README.md file
Will be shown when running with --about.

The render.rb file will be executed when running bashly render and will have access to these variables and methods:

Variable	Description
`command`	The root command of your bashly script (`Bashly::Script::Command`).
`source`	A string containing the path to the template source directory.
`target`	A string containing the path to the target directory, as provided by the user at run time (`bashly render SOURCE TARGET`).
`show`	A string that will contain the value of `--show PATH` if provided by the user at runtime.

Method	Description
`save`	The method your script should call in order to save an output file.
`say`	Print a message with colors (see Colsole)

The render.rb script is executed with the Bashly::RenderContext context.

# Render script example

This approach allows you to use any template engine that is available in Ruby.

For example, this render.rb file uses GTX to render the markdown documentation:

render.rb
# 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

# Render the file for the main command
save "#{target}/index.md", gtx.parse(command)

# Render a file for each subcommand
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

See it on GitHub

# Custom properties

The bashly.yml allows the use of arbitrary properties. Any property that starts with x_ is ignored by the validation process, and is therefore allowed.

You can use this functionality to add properties that can be used in your rendering templates. See one of the built-in templates for usage example.