:toc: macro :toclevels: 5 :figure-caption!: = Rubysmith [link=http://badge.fury.io/rb/rubysmith] image::https://badge.fury.io/rb/rubysmith.svg[Gem Version] [link=https://www.alchemists.io/projects/code_quality] image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide] [link=https://circleci.com/gh/bkuhlmann/rubysmith] image::https://circleci.com/gh/bkuhlmann/rubysmith.svg?style=svg[Circle CI Status] Rubysmith is a command line interface for smithing Ruby projects. This gem is useful in situations in which you need something more sophisticated than a link:https://bundler.io/guides/bundler_in_a_single_file_ruby_script.html[Bundler Inline] script but less complicated than a link:https://www.alchemists.io/projects/gemsmith[Gemsmith] gem. Rubysmith is the foundation of Gemsmith and provides a lot of the same functionality as Gemsmith but solely tailored for pure Ruby projects. Again, this is a great tool for spiking quick Ruby implementations, sharing code snippets with others, or building full blown Ruby projects for collaboration with others. toc::[] == Features * Builds a Ruby project skeleton for custom design and development. * Uses link:https://www.alchemists.io/projects/runcom[Runcom] for resource configuration management. * Uses link:https://www.alchemists.io/projects/pragmater[Pragmater] for Ruby source pragma directives. * Supports link:https://github.com/amazing-print/amazing_print[Amazing Print]. * Supports link:https://github.com/rubymem/bundler-leak[Bundler Leak]. * Supports link:https://circleci.com[Circle CI]. * Supports link:https://github.com/ruby/debug[Debug]. * Supports link:https://git-scm.com[Git]. * Supports link:https://github.com[GitHub]. * Supports link:https://www.alchemists.io/projects/git-lint[Git Lint]. * Supports link:https://github.com/guard/guard[Guard]. * Supports link:https://github.com/ruby/rake[Rake]. * Supports link:https://github.com/troessner/reek[Reek]. * Supports link:https://www.alchemists.io/projects/refinements[Refinements]. * Supports link:https://rspec.info[RSpec]. * Supports link:https://github.com/rubocop-hq/rubocop[Rubocop]. * Supports link:https://docs.rubocop.org/rubocop-performance[Rubocop Performance]. * Supports link:https://github.com/rubocop-hq/rubocop-rake[Rubocop Rake]. * Supports link:https://github.com/rubocop-hq/rubocop-rspec[Rubocop RSpec]. * Supports link:https://github.com/simplecov-ruby/simplecov[SimpleCov]. * Supports link:https://github.com/fxn/zeitwerk[Zeitwerk]. * Supports common settings and a structured layout for building projects. * Provides common documentation: ** README ** CHANGES ** CODE OF CONDUCT ** CONTRIBUTING ** LICENSE // == Screencasts // [link=https://www.alchemists.io/screencasts/rubysmith] // image::https://www.alchemists.io/images/screencasts/rubysmith/cover.svg[Screencast,600,240,role=focal_point] == Requirements . A UNIX-based system. . link:https://www.ruby-lang.org[Ruby]. . link:https://rubygems.org[RubyGems]. . link:https://github.com/bundler/bundler[Bundler]. == Setup To install, run: [source,bash] ---- gem install rubysmith ---- == Usage === Command Line Interface (CLI) From the command line, type: `rubysmith --help` .... USAGE: -b, --build NAME [options] Build new project. -c, --config ACTION Manage gem configuration: edit or view. -h, --help Show this message. -v, --version Show gem version. BUILD OPTIONS: --[no-]amazing_print Add Amazing Print gem. Default: true. --[no-]bundler-leak Add Bundler Leak gem. Default: true. --[no-]changes Add CHANGES documentation. Default: true. --[no-]circle_ci Add Circle CI configuration and badge. Default: false. --[no-]conduct Add CODE_OF_CONDUCT documentation. Default: true. --[no-]console Add console script. Default: true. --[no-]contributions Add CONTRIBUTING documentation. Default: true. --[no-]debug Add Debug gem. Default: true. --[no-]git Add Git. Default: true. --[no-]git_hub Add GitHub templates. Default: false. --[no-]git-lint Add Git Lint gem. Default: true. --[no-]guard Add Guard gem. Default: true. --[no-]license Add LICENSE documentation. Default: true. --max Use maximum/enabled options. Default: false. --min Use minimum/disabled options. Default: false. --[no-]rake Add Rake gem. Default: true. --[no-]readme Add README documentation. Default: true. --[no-]reek Add Reek gem. Default: true. --[no-]refinements Add Refinements gem. Default: true. --[no-]rspec Add RSpec gem. Default: true. --[no-]rubocop Add Rubocop gems. Default: true. --[no-]setup Add setup script. Default: true. --[no-]simple_cov Add SimpleCov gem. Default: true. --[no-]zeitwerk Add Zeitwerk gem. Default: true. .... === Building The core functionality of this gem centers around the `--build` command with optional customization provided via build options. By default, all build options are enabled. Example: [source,bash] ---- rubysmith --build demo ---- Running the above will generate a new `demo` Ruby project with all options enabled. Should you wish to disable specific options, you can use the `--no-*` prefix. Example: [source,bash] ---- rubysmith --build demo --no-debug --no-guard ---- With the above example, both Debug and Guard support would have been disabled when building the `demo` project. Taking this a step further, you can also use the `--min` option to generate a project with bare minimum of options. Example: [source,bash] ---- rubysmith --build demo --min ---- The above is essentially the same as building with _all_ options disabled. This is handy in situations where you need to quickly script something up for sharing with others yet still want to avoid using a Bundler Inline script so gem dependencies are not installed each time the code is run. As shown earlier, you can combine options but be aware that order matters. Take the following, for example, where both minimum and maximum options are used in conjunction with other options: [source,bash] ---- rubysmith --build demo --min --zeitwerk rubysmith --build demo --max --no-debug ---- With the above examples, the first line will _disable_ all options except for Zeitwerk while the second line will _enable_ all options except for Debug. This can be a handy way to build a new project with all options either disabled or enabled with only a few select options modified. To have specific options enabled/disabled _every time_ you build a new Ruby project, you can edit your global configuration for making these settings permanent (see below for details). === Configuration This gem can be configured via a global configuration: .... $HOME/.config/rubysmith/configuration.yml .... It can also be configured via link:https://www.alchemists.io/projects/xdg[XDG] environment variables. The default configuration is as follows: [source,yaml] ---- :author: :name: :email: :url: :build: :amazing_print: true :bundler_leak: true :changes: true :circle_ci: false :conduct: true :console: true :contributions: true :debug: true :git: true :git_hub: false :git_lint: true :guard: true :license: true :maximum: false :minimum: false :rake: true :readme: true :reek: true :refinements: true :rspec: true :rubocop: true :setup: true :simple_cov: true :zeitwerk: true :builders: :pragmater: :comments: - "# frozen_string_literal: true" :includes: - "**/*.rb" - "**/*bin/console" - "**/*bin/guard" - "**/*bin/rubocop" - "**/*Gemfile" - "**/*Guardfile" - "**/*Rakefile" :documentation: :format: "md" :license: "mit" :git_hub: :user: ---- Feel free to take this default configuration, modify, and save as your own custom `configuration.yml`. ==== Author Author information is used when generating project documentation and is recommended you fill this information in before building a project. Example: :author: :name: Jill Smith :email: jsmith@example.com :url: https://www.exmaple.com/team/jsmith ==== Build Build options are booleans so can only be `true` or `false` by default. Should you want a different configuration than what is enabled/disabled by default, you'll want to customize these options as you see fit. When changing build options, they will dynamically show up when viewing usage (i.e. `rubysmith --help`). ==== Builders Builders are additional tooling which can be configured specifically for Rubysmith. At the moment, only link:https://www.alchemists.io/projects/pragmater[Pragmater] is supported so view the Pragmater project page to learn more. ==== Documentation Documentation can be configured as follows: * *Format*: Use `md` for Markdown or `adoc` for ASCCI Doc. * *License*: Use `mit` for MIT or `Apache` for Apache 2.0.0 license. No other licenses are supported at this time but might be expanded up on in the future. ==== GitHub Your GitHub user is whatever handle you setup when you creating your GitHub account. This information is used for documentation purposes and Circle CI badge association. If you don't define this information, Rubysmith will automatically fallback to pulling this information from your Git configuration (i.e. `github.user`). If all else fails, then nothing will be used. == Development To contribute, run: [source,bash] ---- git clone https://github.com/bkuhlmann/rubysmith.git cd rubysmith bin/setup ---- You can also use the IRB console for direct access to all objects: [source,bash] ---- bin/console ---- == Tests To test, run: [source,bash] ---- bundle exec rake ---- == Versioning Read link:https://semver.org[Semantic Versioning] for details. Briefly, it means: * Major (X.y.z) - Incremented for any backwards incompatible public API changes. * Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes. * Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes. == Code of Conduct Please note that this project is released with a link:CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By participating in this project you agree to abide by its terms. == Contributions Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details. == License Read link:LICENSE.adoc[LICENSE] for details. == History Read link:CHANGES.adoc[CHANGES] for details. Built with link:https://www.alchemists.io/projects/gemsmith[Gemsmith]. == Credits Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].