thor_enhance 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6298d393beb8a380215c08bc6fa78c97cfd29b3d804159f97b361628b5dd4707
-  data.tar.gz: 15533218c1806a98998f3b66781a9543a22c231f60126c7b98b6a58bc5cf9cd6
+  metadata.gz: c35515a53e679dc8e52c1c615dc19c4c24214280fb75e1af513e257d831cf457
+  data.tar.gz: 68a91514f8b7dde6df20913f4ec8fdfce263c1a36e8700da80569d79fd3480d3
 SHA512:
-  metadata.gz: a85cdd00c9939a3f0165fdb41950c9578b56d806cd42cfff90a7058e384fcf33d46ca9f2f79eea35524f305a791a57ee1167e38818d7587fe0b5115112945c84
-  data.tar.gz: 38e8c731b8696c6abb82df29fdaabe2468e742ac69b222ac06796b989d0b6de119dfd56af82c6d2cf833522d06c2fdd0802cbb1f2fffce28b6c37c2ce62cb5d3
+  metadata.gz: 7cd3bda1a32242ad57a0f55f956d5e9780a1f5c22f9866718e1fc12944c40792f9aa89b2ae6ba885f7ffdb269890fa66056f2b8fac40c15bba64ef1a85288a9f
+  data.tar.gz: b30889ca39f92ef0e9851dd3c0b37930b472dd1db7a001bb1778a034c64904f216f5c3cc16ed71d590f96fd515052441eb649aa2856638ad29f6e2f4656f6679

data/CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.5.0]
+- Autogenerate Readme based on command options and method options
+
 ## [0.4.0]
 - Enable Enhancements on a klass basis
 - Add Enable/disable blocks for enhancements to allow for onboarding new tasks

data/Gemfile

@@ -9,4 +9,5 @@ gem "pry"
 gem "pry-byebug"
 gem "rspec", "~> 3.0"
 gem "rspec_junit_formatter"
-gem "simplecov", "~> 0.17.0", require: false
+gem "simplecov", require: false
+gem "ice_age"

data/Gemfile.lock

@@ -1,18 +1,39 @@
 PATH
   remote: .
   specs:
-    thor_enhance (0.3.0)
+    thor_enhance (0.5.1)
+      activesupport (>= 6)
       thor (~> 1.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (7.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      mutex_m
+      tzinfo (~> 2.0)
+    base64 (0.2.0)
+    bigdecimal (3.1.4)
     byebug (11.1.3)
     coderay (1.1.3)
+    concurrent-ruby (1.2.2)
+    connection_pool (2.4.1)
     diff-lcs (1.5.0)
     docile (1.4.0)
-    json (2.6.3)
+    drb (2.2.0)
+      ruby2_keywords
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    ice_age (0.2.0)
     method_source (1.0.0)
+    minitest (5.20.0)
+    mutex_m (0.2.0)
     pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
@@ -34,23 +55,30 @@ GEM
     rspec-support (3.12.1)
     rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
-    simplecov (0.17.1)
+    ruby2_keywords (0.0.5)
+    simplecov (0.22.0)
       docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
     thor (1.3.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
 
 PLATFORMS
   aarch64-linux
+  arm64-darwin-22
+  arm64-darwin-23
 
 DEPENDENCIES
+  ice_age
   pry
   pry-byebug
   rspec (~> 3.0)
   rspec_junit_formatter
-  simplecov (~> 0.17.0)
+  simplecov
   thor_enhance!
 
 BUNDLED WITH
-   2.4.22
+   2.5.1

data/README.md

@@ -31,10 +31,12 @@ Command option injection is very powerful. This allows add low level documentati
 
 [Command option documentation](docs/command.md)
 
-### [Future Plans] Automatic ReadMe Generation
+### Automatic ReadMe Generation
 The beauty of ThorEnhance is that it forces all your documentation to live with the code. As your code changes, the documentation naturally changes with it.
 
-In the near future, we plan to allow for automatic readme generation based on the enhanced commands provided.
+ThorEnhance can automatically generate your code bases Readme for you.
+
+[Autogenerate Readme](docs/autogenerate/Readme.md)
 
 
 ### Initialization

data/bin/thor_enhance

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require "rubygems"
+require "bundler/setup"
+require "pry"
+
+require "thor_enhance"
+
+ThorEnhance.configure do |c|
+  c.readme_enhance!(required: true) do |r|
+    r.custom_header(:how_does_this_help, repeatable: true)
+    r.custom_header(:when_should_i_use_this, required: true, question: true)
+  end
+end
+
+require "thor_enhance/sample"
+
+begin
+  ThorEnhance::Sample.start
+rescue Interrupt => e
+  $stdout.puts "\nThanks for using Better Dependabot 👋\n"
+end

data/docs/autogenerate/Readme.md

@@ -0,0 +1,166 @@
+# Autogenerate Readme
+
+A core component of `ThorEnhance` is the ability to autogenerate Readmes for your thor commands. This allows the code and the readme to be in lockstep without the worry of the Readme getting out of date.
+
+## How does this work?
+By building on top of [Command Method Injection](../command.md) and [Method Option Injection](../method_option.md), ThorEnhance allows Readme's to get autogenerated based on the description of the command and the methods.
+
+## How to use
+
+```ruby
+# thor_enhance_config.rb
+ThorEnhance.configure do |c|
+  c.readme_enhance!
+end
+```
+
+### Pro Tip
+The Readme's are generated based on the code. We suggest to enable the following in your `.gitattributes`
+```
+# .gitattributes
+...
+generated_readme/** linguist-generated=true
+...
+```
+`generated_readme/**` is the default location for ThorEnhance Readmes. The code above will tell github to ignore these files for code review. This will help in the process to ensure that only the code gets changes rather than the generated readme.
+
+## Default capabilities
+
+### Example Command Option
+When `readme_enhance` is enabled, by default the `example` command option is available on for every command.
+
+```ruby
+desc "sample", "This Sample command"
+example "sample", desc: "Basic invocation of the useless command"
+example "sample --boolean", desc: "Basic invocation of the useless command with a flag"
+method_option :boolean, type: :boolean, desc: "Just a normal boolean"
+def sample;end;
+```
+
+The example command signature expects:
+```ruby
+# remove basename and any submodules from command execution
+example "command execution", desc: "Description of what the command does"
+```
+
+By default, `example` is not required for every command. To make `example` required for every command, modify the configuration to:
+```ruby
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.example(required: true)
+  end
+end
+```
+
+### Header Command Option
+When `readme_enhance` is enabled, by default the `header` option is available on every command.
+
+```ruby
+desc "sample", "This Sample command"
+header name: "When should I use this?", desc: "To add additional commentary to your command"
+header name: "I can have many headers", desc: "Headers can be different per command"
+def sample;end;
+```
+
+By default, `header` is not required for every command. It is an additive command that is customizable per command
+
+### Title Command Option
+When `readme_enhance` is enabled, by default a the `title` option is available on every command.
+
+This optional command option gets used for the Readme title. Otherwise, the method name gets used
+
+```ruby
+desc "sample", "This Sample command"
+title "Useless Sample command"
+def sample;end;
+```
+
+By default, `title` is not required for every command. To make `title` required for every command, modify the configuration to
+```ruby
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.title(required: true)
+  end
+end
+```
+
+### Readme Method Option
+
+When `readme_enhance` is enabled, by default `readme` flag is available on every option.
+
+```ruby
+desc "sample", "This Sample command"
+method_option :boolean, type: :boolean, desc: "Just a normal boolean", readme: :important
+def sample;end;
+```
+
+The Default options for the value of `:readme` are [`:important`, `:advanced`, `:skip`].
+
+All methods flagged with `:important` will show up higher in the readme. Anything labled with `:skip`, will not show up on the readme.
+
+
+By default, `readme` is not required for every method.
+
+```ruby
+# This will require all method_options to have the `readme` flag
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.readme(required: true)
+  end
+end
+```
+
+```ruby
+# This will options without the `readme` flag to a group of :empty on the readme
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.readme(empty_group: :empty)
+  end
+end
+```
+
+```ruby
+# Setting enums will override the default readme groups
+# Only these values will be allowed as readme values
+# The order of the arry determines the order the group will be ouputted in the Readme
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    r.readme(enums: ["cool", :features, "live", "here".to_sym])
+  end
+end
+```
+
+### Custom Header Command Option
+
+Custom Headers must get manually added to the configuration.
+
+```ruby
+ThorEnhance.configure do |c|
+  c.readme_enhance! do |r|
+    # how_does_this_help will be required on every command
+    r.custom_header("how_does_this_help", required: true)
+    # when_should_i_use_this is a repeatable command
+    r.custom_header("when_should_i_use_this", repeatable: true)
+    # is_this_important is now a question. On the readme, `?` gets appened to the header
+    r.custom_header("is_this_important", question: true)
+  end
+end
+```
+
+The configuration enumerated above allows the ability to do the following:
+
+
+```ruby
+desc "sample", "This Sample command"
+how_does_this_help "This command will help enable additional configuration for each command. This will get appended to the Readme in the order it appears as originally configured", tag: "h4"
+when_should_i_use_this "Use this whenever you like"
+when_should_i_use_this "Or you dont ever have to use this", tag: "h2"
+is_this_important "Yes this is imporant. It even has a custom tag", tag: 1
+def sample;end;
+```
+
+Take special note of the `tag` option on the custom header. By default, header will output as an `<h2>` header tag. You can optionally change the header tag value to a numeric: `1|2|3|4` or you can use a header string: `h1|h2|h3|h4`
+
+# Example:
+
+ThorEnanhace has sample thor tasks defined in [ThorEnhance::Sample](/lib/thor_enhance/sample.rb). View the [AutoGenerated Commands here](/generated_readme/commands)

data/generated_readme/commands/Readme.md

@@ -0,0 +1,34 @@
+## [Subcommand for sample class](sub/Readme.md)
+Thor sub command validation for thor enhance
+
+```bash
+# Help Command
+thor_enhance sub <options>
+
+
+```
+
+## [sample](sample.md)
+This Sample command does a lot of nothing
+
+```bash
+# Help Command
+thor_enhance sample <options>
+
+thor_enhance sample
+thor_enhance sample --boolean
+```
+
+## [autobots](autobots.md)
+Command outputs what Optimus prime is thniking
+
+```bash
+# Help Command
+thor_enhance autobots <options>
+
+thor_enhance sample
+thor_enhance sample --boolean
+```
+
+> AutoGenerateted by [ThorEnhance](https://github.com/matt-taylor/thor_enhance) <br>
+> Regenerate readme files with: thor_enhance thor_enhance_autogenerate --apply

data/generated_readme/commands/autobots.md

@@ -0,0 +1,69 @@
+# Autobots
+
+Source code for this command can be found at: [ThorEnhance::Sample#autobots](/lib/thor_enhance/sample.rb#L51)
+
+## Description
+Command outputs what Optimus prime is thniking
+
+```bash
+# Base command for `autobots`
+thor_enhance autobots <options>
+```
+
+## When Should I Use This?
+
+Do you ever feel angry about how powerful the Decepticons are compared to the Autobots? It seems unfair.
+Trust...The autobots agree.
+
+
+
+
+---
+
+## Examples
+
+```bash
+# yo yo ma
+thor_enhance sample
+```
+
+```bash
+# yo yo ma
+thor_enhance sample --boolean
+```
+
+
+
+---
+
+
+## Method Options
+
+
+
+<details open>
+  <summary> <h3> Important options </h3> </summary>
+
+```bash
+# What: Enable bumblee bee flag
+# Type: boolean
+# Required: false
+--bumble | -b | --no-bumble
+
+```
+
+</details>
+
+
+
+
+
+
+
+
+
+---
+
+> AutoGenerateted by [ThorEnhance](https://github.com/matt-taylor/thor_enhance) <br>
+> Regenerate readme files with: thor_enhance thor_enhance_autogenerate --apply
+

data/generated_readme/commands/sample.md

@@ -0,0 +1,84 @@
+# Sample
+
+Source code for this command can be found at: [ThorEnhance::Sample#sample](/lib/thor_enhance/sample.rb#L39)
+
+## Description
+This Sample command does a lot of nothing
+
+```bash
+# Base command for `sample`
+thor_enhance sample <options>
+```
+
+#### How Does This Help
+
+Honestly, this does not help at all
+
+# How Does This Help
+
+But its cool because it is a repatable command
+
+## When Should I Use This?
+
+Have you ever wanted your code to be useless?
+Well, this command does absolutely nothing.
+This output is to say that this command does absolutely nothing
+
+
+
+
+---
+
+## Examples
+
+```bash
+# yo yo ma
+thor_enhance sample
+```
+
+```bash
+# yo yo ma
+thor_enhance sample --boolean
+```
+
+
+
+---
+
+
+## Method Options
+
+
+
+<details open>
+  <summary> <h3> Important options </h3> </summary>
+
+```bash
+# What: Just a normal boolean
+# Type: boolean
+# Required: false
+--boolean | -b | --no-boolean
+
+# What: How many times to output text
+# Type: numeric
+# Required: false
+# Allowed Inputs: [1, 2, 3, 4, 5]
+--count
+
+```
+
+</details>
+
+
+
+
+
+
+
+
+
+---
+
+> AutoGenerateted by [ThorEnhance](https://github.com/matt-taylor/thor_enhance) <br>
+> Regenerate readme files with: thor_enhance thor_enhance_autogenerate --apply
+

data/generated_readme/commands/sub/Readme.md

@@ -0,0 +1,37 @@
+# Subcommand For Sample Class
+
+
+
+## Description
+Thor sub command validation for thor enhance
+
+```bash
+# Base command for `sub`
+thor_enhance sub <options>
+```
+
+
+
+
+
+
+
+### [Innard command for Subtask Subcommand](innard.md)
+
+
+Wow, This longer description will take precedence over the desc above. This is what will be shown in the readme autogenerated page. Try me out!
+
+```bash
+thor_enhance sub innard <options>
+thor_enhance sub innard --count 5
+thor_enhance sub innard --count 35
+```
+
+
+
+
+---
+
+> AutoGenerateted by [ThorEnhance](https://github.com/matt-taylor/thor_enhance) <br>
+> Regenerate readme files with: thor_enhance thor_enhance_autogenerate --apply
+

data/generated_readme/commands/sub/innard.md

@@ -0,0 +1,46 @@
+# Innard Command For Subtask Subcommand
+
+Source code for this command can be found at: [ThorEnhance::Sample::SubCommand#innard](/lib/thor_enhance/sample.rb#L20)
+
+## Description
+Wow, This longer description will take precedence over the desc above. This is what will be shown in the readme autogenerated page. Try me out!
+
+```bash
+# Base command for `innard`
+thor_enhance sub innard <options>
+```
+
+## When Should I Use This?
+
+Use sub command task to validate that subocommands work as expected
+
+
+## Deprecation warning
+This command will get deprecated in the next major version
+
+
+---
+
+## Examples
+
+```bash
+# Innard sub command with a count of 5
+thor_enhance sub innard --count 5
+```
+
+```bash
+# Innard sub command with a count of 35
+thor_enhance sub innard --count 35
+```
+
+
+
+
+
+
+
+---
+
+> AutoGenerateted by [ThorEnhance](https://github.com/matt-taylor/thor_enhance) <br>
+> Regenerate readme files with: thor_enhance thor_enhance_autogenerate --apply
+