lono 4.0.0 → 4.0.1

data/lib/lono/help/upgrade4.md

@@ -0,0 +1,25 @@
+Lono version 4 changed a few things:
+
+* Simplified the [directory structure](http://lono.cloud/docs/directory-structure/) of a lono project.
+* Format of the [settings.yml](http://lono.cloud/docs/settings/) changed.
+* LONO_ENV are longer full names now.
+* Refer to the [CHANGELOG](https://github.com/tongueroo/lono/blob/master/CHANGELOG.md) for more details.
+
+This task helps you upgrade from lono version 3 to version 4.
+
+### Example Output
+
+    $ lono upgrade4
+    Upgrading structure of your current project to the new lono version 4 project structure
+    mv helpers app/helpers
+    mv params config/params
+    mv config/templates app/definitions
+    mv templates app/templates
+    mv app/templates/partial app/partials
+    mv app/partials/user_data app/user_data
+    Updating structure of config/variables
+    Updating structure of app/definitions
+    mv config/params/prod config/params/production
+    mv config/params/stag config/params/staging
+    Upgrade to lono version 4 complete!
+    $

data/lib/lono/help/user_data.md

@@ -1,3 +1,38 @@
 Generates user_data scripts in `app/user_data` so you can see it for debugging. Let's say you have a script in `app/user_data/bootstrap.sh`. To generate it:
 
-  lono user_data bootstrap
+    lono user_data bootstrap
+
+## Example Output
+
+Script:
+
+    #!/bin/bash -exu
+
+    <%= extract_scripts(to: "/opt") %>
+
+    SCRIPTS=/opt/scripts
+    $SCRIPTS/install_stuff.sh
+
+Running `ono user_data bootstrap` produces:
+
+    $ lono user_data bootstrap
+    Detected app/scripts
+    Tarballing app/scripts folder to scripts.tgz
+    => cd app && dot_clean .
+    => cd app && tar -c scripts | gzip -n > scripts.tgz
+    Tarball created at output/scripts/scripts-93b8b29b.tgz
+    Generating user_data for 'bootstrap' at ./app/user_data/bootstrap.sh
+    #!/bin/bash -exu
+
+    # Generated from the lono extract_scripts helper.
+    # Downloads scripts from s3, extract them, and setup.
+    mkdir -p /opt
+    aws s3 cp s3://mybucket/path/to/folder/development/scripts/scripts-93b8b29b.tgz /opt/
+    cd /opt
+    tar zxf /opt/scripts-93b8b29b.tgz
+    chmod -R a+x /opt/scripts
+    chown -R ec2-user:ec2-user /opt/scripts
+
+    SCRIPTS=/opt/scripts
+    $SCRIPTS/install_stuff.sh
+    $

data/lib/lono/help/xgraph.md

@@ -0,0 +1,16 @@
+## Example
+
+With more complex CloudFormation templates, the dependency get more difficult to follow.  Visualizing the dependencies is helpful.
+
+    lono import https://s3.amazonaws.com/solutions-reference/aws-waf-security-automations/latest/aws-waf-security-automations.template --name waf
+    lono inspect depends waf
+
+This above command generates a dependency chart.  The command uses the DependsOn attribute specified in each resource to figure this out.  It does not show implied dependencies that CloudFormaton automatically computes for us.  The chart looks like this:
+
+![](/img/tutorial/waf-chart.png){:.doc-photo}
+
+The chart is generated with [Graphviz](http://www.graphviz.org/). To install:
+
+    brew install graphviz
+
+Blog Post also covers this: [lono inspect depends Tutorial Introduction](https://blog.boltops.com/2017/09/20/lono-inspect-depends-tutorial-introduction)

data/lib/lono/help.rb

@@ -1,9 +1,16 @@
 module Lono::Help
   class << self
+    # namespaced_command: cfn/create or cfn:create
+    # both work.
     def text(namespaced_command)
       path = namespaced_command.to_s.gsub(':','/')
       path = File.expand_path("../help/#{path}.md", __FILE__)
       IO.read(path) if File.exist?(path)
     end
+
+    # Generates a markdown file for site docuemtation
+    def markdown
+
+    end
   end
 end

data/lib/lono/markdown/creator.rb

@@ -0,0 +1,65 @@
+require "active_support/core_ext/object"
+
+module Lono::Markdown
+  class Creator
+    cattr_accessor :mute
+
+    def self.create_all(command_class,  parent_command_name=nil)
+      clean unless parent_command_name
+      new(command_class, parent_command_name).create_all
+    end
+
+    def self.clean
+      FileUtils.rm_rf("docs/_reference")
+      FileUtils.rm_f("docs/reference.md")
+    end
+
+    # command_class is top-level CLI class.
+    def initialize(command_class, parent_command_name)
+      @command_class = command_class
+      @parent_command_name = parent_command_name
+    end
+
+    def create_all
+      create_index unless @parent_command_name
+
+      @command_class.commands.keys.each do |command_name|
+        page = Page.new(@command_class, command_name, @parent_command_name)
+        create_page(page)
+
+        if subcommand?(command_name)
+          subcommand_class = subcommand_class(command_name)
+          parent_command_name = command_name
+
+          say "Creating subcommands pages for #{parent_command_name}..."
+          Creator.create_all(subcommand_class, parent_command_name)
+        end
+      end
+    end
+
+    def create_page(page)
+      say "Creating #{page.path}..."
+      FileUtils.mkdir_p(File.dirname(page.path))
+      IO.write(page.path, page.doc)
+    end
+
+    def create_index
+      page = Index.new(@command_class)
+      FileUtils.mkdir_p(File.dirname(page.path))
+      say "Creating #{page.path}"
+      IO.write(page.path, page.doc)
+    end
+
+    def subcommand?(command_name)
+      @command_class.subcommands.include?(command_name)
+    end
+
+    def subcommand_class(command_name)
+      @command_class.subcommand_classes[command_name]
+    end
+
+    def say(text)
+      puts text unless self.class.mute
+    end
+  end
+end

data/lib/lono/markdown/index.rb

@@ -0,0 +1,36 @@
+module Lono::Markdown
+  class Index
+    def initialize(command_class)
+      @command_class = command_class
+    end
+
+    def path
+      "docs/reference.md"
+    end
+
+    def command_list
+      @command_class.commands.keys.sort.map.each do |command_name|
+        page = Page.new(@command_class, command_name)
+        link = page.path.sub("docs/", "")
+        # Example: [lono cfn]({% link _reference/lono-cfn.md %})
+        "* [lono #{command_name}]({% link #{link} %})"
+      end.join("\n")
+    end
+
+    def summary
+      <<-EOL
+Lono is a CloudFormation framework tool that helps you manage your templates. Lono handles the entire CloudFormation lifecycle. It starts with helping you develop your templates and helps you all the way to the infrastructure provisioning step.
+EOL
+    end
+
+    def doc
+      <<-EOL
+---
+title: CLI Reference
+---
+#{summary}
+#{command_list}
+EOL
+    end
+  end
+end

data/lib/lono/markdown/page.rb

@@ -0,0 +1,169 @@
+module Lono::Markdown
+  class Page
+    def initialize(command_class, command_name, parent_command_name=nil)
+      @command_class = command_class
+      @command_name = command_name
+      @parent_command_name = parent_command_name
+      @command = @command_class.commands[@command_name]
+    end
+
+    def usage
+      banner = @command_class.send(:banner, @command) # banner is protected method
+      invoking_command = File.basename($0) # could be rspec, etc
+      banner.sub(invoking_command, cli_name)
+    end
+
+    def description
+      @command.description
+    end
+
+    def options
+      shell = Shell.new
+      @command_class.send(:class_options_help, shell, nil => @command.options.values)
+      text = shell.stdout.string
+      return "" if text.empty? # there are no options
+
+      lines = text.split("\n")[1..-1] # remove first line wihth "Options: "
+      lines.map! do |line|
+        # remove 2 leading spaces
+        line.sub(/^  /, '')
+      end
+      lines.join("\n")
+    end
+
+    # Use command's long description as many description
+    def long_description
+      text = @command.long_description
+      return "" if text.nil? # empty description
+
+      lines = text.split("\n")
+      lines.map do |line|
+        # In the CLI help, we use 2 spaces to designate commands
+        # In Markdown we need 4 spaces.
+        line.sub(/^  \b/, '    ')
+      end.join("\n")
+    end
+
+    def cli_name
+      "lono"
+    end
+
+    def path
+      full_name = if @parent_command_name
+        "#{cli_name}-#{@parent_command_name}-#{@command_name}"
+      else
+        "#{cli_name}-#{@command_name}"
+      end
+      "docs/_reference/#{full_name}.md"
+    end
+
+    def subcommand?
+      @command_class.subcommands.include?(@command_name)
+    end
+
+    def subcommand_class
+      @command_class.subcommand_classes[@command_name]
+    end
+
+    # Note:
+    # printable_commands are in the form:
+    #  [
+    #    [command_form,command_comment],
+    #    [command_form,command_comment],
+    #  ]
+    #
+    # It is useful to grab the command form printable_commands as it shows
+    # the proper form.
+    def subcommand_list
+      return '' unless subcommand?
+
+      invoking_command = File.basename($0) # could be rspec, etc
+      command_list = subcommand_class.printable_commands
+        .sort_by { |a| a[0] }
+        .map { |a| a[0].sub!(invoking_command, cli_name); a } # replace with proper comand
+        .reject { |a| a[0].include?("help [COMMAND]") } # filter out help
+
+      # dress up with markdown
+      text = command_list.map do |a|
+        command, comment = a[0], a[1].sub(/^# /,'')
+        subcommand_name = command.split(' ')[2]
+        full_command_path = "#{cli_name}-#{@command_name}-#{subcommand_name}"
+        full_command_name = "#{cli_name} #{@command_name} #{subcommand_name}"
+        link = "_reference/#{full_command_path}.md"
+
+        # "* [#{command}]({% link #{link} %})"
+        # Example: [lono cfn delete STACK]({% link _reference/lono-cfn-delete.md %})
+        "* [#{full_command_name}]({% link #{link} %}) - #{comment}"
+      end.join("\n")
+
+      <<-EOL
+## Subcommands
+
+#{text}
+EOL
+    end
+
+    def doc
+      <<-EOL
+#{front_matter}
+#{usage_markdown}
+#{long_desc_markdown}
+#{subcommand_list}
+#{options_markdown}
+EOL
+    end
+
+    def front_matter
+      command = [cli_name, @parent_command_name, @command_name].compact.join(' ')
+      <<-EOL
+---
+title: #{command}
+reference: true
+---
+EOL
+    end
+
+    def usage_markdown
+      <<-EOL
+## Usage
+
+    #{usage}
+EOL
+    end
+
+    def desc_markdown
+      <<-EOL
+## Description
+
+#{description}
+EOL
+    end
+
+    # If the Thor long_description is empty then use the description.
+    def long_desc_markdown
+      return desc_markdown if long_description.empty?
+
+      <<-EOL
+## Description
+
+#{description}
+
+#{long_description}
+EOL
+    end
+
+    # handles blank options
+    def options_markdown
+      return '' if options.empty?
+
+      <<-EOL
+## Options
+
+```
+#{options}
+```
+EOL
+    end
+
+  end
+end

data/lib/lono/markdown/shell.rb

@@ -0,0 +1,11 @@
+require 'thor'
+
+module Lono::Markdown
+  # Override stdout as an @io object so we can grab the text written normally
+  # outputted to the shell.
+  class Shell < Thor::Shell::Basic
+    def stdout
+      @io ||= StringIO.new
+    end
+  end
+end

data/lib/lono/markdown.rb

@@ -0,0 +1,8 @@
+require 'thor'
+
+module Lono::Markdown
+  autoload :Creator, 'lono/markdown/creator'
+  autoload :Index, 'lono/markdown/index'
+  autoload :Page, 'lono/markdown/page'
+  autoload :Shell, 'lono/markdown/shell'
+end

data/lib/lono/param.rb

@@ -7,7 +7,7 @@ class Lono::Param < Lono::Command
   class_option :noop, type: :boolean
   class_option :mute, type: :boolean
 
-  desc "generate", "generate all parameter files to json format"
+  desc "generate", "Generate all parameter files to `output/params`."
   long_desc Lono::Help.text("param/generate")
   option :path, desc: "Name of the source that maps to the params txt file.  name -> params/NAME.txt.  Use this to override the params/NAME.txt convention"
   def generate

data/lib/lono/script.rb

@@ -4,13 +4,13 @@ module Lono
     autoload :Build, "lono/script/build"
     autoload :Upload, "lono/script/upload"
 
-    desc "build", "Builds output/scripts/scripts-md5sum.tgz from app/script folder"
+    desc "build", "Builds `output/scripts/scripts-md5sum.tgz` from `app/script` folder"
     long_desc Help.text("script/build")
     def build
       Build.new(options).run
     end
 
-    desc "upload", "Uploads output/scripts/scripts-md5sum.tgz to s3"
+    desc "upload", "Uploads `output/scripts/scripts-md5sum.tgz` to s3"
     long_desc Help.text("script/upload")
     def upload
       Upload.new(options).run

data/lib/lono/version.rb

@@ -1,3 +1,3 @@
 module Lono
-  VERSION = "4.0.0"
+  VERSION = "4.0.1"
 end

data/lib/lono.rb

@@ -33,6 +33,7 @@ module Lono
   autoload :Upgrade4, 'lono/upgrade4'
   autoload :Script, 'lono/script'
   autoload :UserData, 'lono/user_data'
+  autoload :Markdown, 'lono/markdown'
 
   extend Core
 end

data/spec/lib/lono/markdown_spec.rb

@@ -0,0 +1,99 @@
+describe Lono::Markdown::Page do
+  let(:page) { Lono::Markdown::Page.new(cli_class, command, parent_command_name) }
+  let(:cli_class) { Lono::CLI }
+  let(:parent_command_name) { nil }
+
+  context "MarkdownMaker.create_all" do
+    it "docs command" do
+      out = execute("rake docs")
+      expect(out).to include("Creating")
+    end
+
+    it "generates all docs pages" do
+      Lono::Markdown::Creator.mute = true
+      Lono::Markdown::Creator.create_all(cli_class)
+    end
+  end
+
+  context "generate" do
+    let(:command) { "generate" }
+
+    it "#usage" do
+      expect(page.usage).to eq "lono generate"
+    end
+
+    it "#summary" do
+      expect(page.summary).to eq "Generate both CloudFormation templates and parameters files"
+    end
+
+    it "#options" do
+      expect(page.options).to include("--clean")
+      # [--clean], [--no-clean]  # remove all output files before generating
+      #                          # Default: true
+      # [--quiet], [--no-quiet]  # silence the output
+    end
+
+    it "#description" do
+      expect(page.description).to include("    lono generate")
+    end
+
+    it "#doc" do
+      expect(page.doc).to include("# Summary")
+      # puts page.doc # uncomment to see generated page for debugging
+    end
+  end
+
+  # subcommand
+  context "cfn" do
+    let(:command) { "cfn" }
+
+    it "#usage" do
+      expect(page.usage).to eq "lono cfn SUBCOMMAND"
+    end
+
+    it "#summary" do
+      expect(page.summary).to eq "cfn subcommand tasks"
+    end
+
+    # Think it is better to hide subcommand options at the top-level.
+    # User will see the optoins once they click into the subcommand.
+    it "#options" do
+      expect(page.options).to include("")
+    end
+
+    it "#description" do
+      expect(page.description).to include("Examples")
+    end
+
+    it "#subcommand_list" do
+      expect(page.doc).to include("# Subcommands")
+      # puts page.subcommand_list # uncomment to see generated list for debugging
+    end
+
+    it "#doc" do
+      expect(page.doc).to include("# Summary")
+      # puts page.doc # uncomment to see generated page for debugging
+    end
+  end
+
+  ################
+  # rest are edge cases
+  context "summary" do
+    let(:command) { "summary" }
+
+    # empty options
+    it "#options" do
+      expect(page.options).to eq ""
+    end
+
+    # empty description
+    it "#description" do
+      expect(page.description).to eq ""
+    end
+
+    it "#doc" do
+      expect(page.doc).to include("# Summary")
+      # puts page.doc # uncomment to see generated page for debugging
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lono
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.0.1
 platform: ruby
 authors:
 - Tung Nguyen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-23 00:00:00.000000000 Z
+date: 2018-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -284,6 +284,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/bin/commit_docs.sh"
 - ".circleci/config.yml"
 - ".gitignore"
 - ".gitmodules"
@@ -328,25 +329,29 @@ files:
 - lib/lono/help/completion.md
 - lib/lono/help/completion_script.md
 - lib/lono/help/generate.md
-- lib/lono/help/hello.md
 - lib/lono/help/import.md
-- lib/lono/help/inspect.md
-- lib/lono/help/inspect/depends.md
-- lib/lono/help/inspect/summary.md
 - lib/lono/help/new.md
 - lib/lono/help/param.md
 - lib/lono/help/param/generate.md
 - lib/lono/help/script/build.md
 - lib/lono/help/script/upload.md
+- lib/lono/help/summary.md
 - lib/lono/help/template.md
 - lib/lono/help/template/bashify.md
 - lib/lono/help/template/generate.md
+- lib/lono/help/upgrade4.md
 - lib/lono/help/user_data.md
+- lib/lono/help/xgraph.md
 - lib/lono/importer.rb
 - lib/lono/inspector.rb
 - lib/lono/inspector/base.rb
 - lib/lono/inspector/graph.rb
 - lib/lono/inspector/summary.rb
+- lib/lono/markdown.rb
+- lib/lono/markdown/creator.rb
+- lib/lono/markdown/index.rb
+- lib/lono/markdown/page.rb
+- lib/lono/markdown/shell.rb
 - lib/lono/new.rb
 - lib/lono/new/helper.rb
 - lib/lono/new/message.rb
@@ -432,6 +437,7 @@ files:
 - spec/lib/lono/cli_spec.rb
 - spec/lib/lono/completion_spec.rb
 - spec/lib/lono/inspect_spec.rb
+- spec/lib/lono/markdown_spec.rb
 - spec/lib/lono/param/generator_spec.rb
 - spec/lib/lono/param_spec.rb
 - spec/lib/lono/setting_spec.rb
@@ -505,6 +511,7 @@ test_files:
 - spec/lib/lono/cli_spec.rb
 - spec/lib/lono/completion_spec.rb
 - spec/lib/lono/inspect_spec.rb
+- spec/lib/lono/markdown_spec.rb
 - spec/lib/lono/param/generator_spec.rb
 - spec/lib/lono/param_spec.rb
 - spec/lib/lono/setting_spec.rb

data/lib/lono/help/hello.md

@@ -1,5 +0,0 @@
-Examples:
-
-  lono hello
-  lono hello NAME
-  lono hello NAME --from me

data/lib/lono/help/inspect/depends.md

@@ -1,3 +0,0 @@
-Example:
-
-  lono inspect depends my-stack

data/lib/lono/help/inspect/summary.md

@@ -1,3 +0,0 @@
-Example:
-
-  lono inspect summary my-stack

data/lib/lono/help/inspect.md

@@ -1,4 +0,0 @@
-Examples:
-
-  lono inspect depends my-stack
-  lono inspect summary my-stack