The letter A styled as Alchemists logo. lchemists
Brooke Kuhlmann's Avatar Brooke Kuhlmann
Published September 27, 2020 Updated June 6, 2023
Rubysmith Icon

Rubysmith

4.9.0

Circe CI Status. Alchemists Style Guide. Git Badge Sponsor Badge

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 Bundler Inline script but less than a Gemsmith gem. Rubysmith is the foundation of Gemsmith and provides much of the same functionality as Gemsmith but is 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.

Features

  • Builds a Ruby project skeleton for custom design and development.

  • Uses Runcom for resource configuration management.

  • Uses Pragmater for Ruby source pragma directives.

  • Supports Amazing Print.

  • Supports Caliber.

  • Supports Circle CI.

  • Supports Citations (ORCID).

  • Supports console script for local development.

  • Supports Debug.

  • Supports Git.

  • Supports GitHub.

  • Supports Git Lint.

  • Supports Guard.

  • Supports Rake.

  • Supports Reek.

  • Supports Refinements.

  • Supports RSpec.

  • Supports setup script for project setup.

  • Supports SimpleCov.

  • Supports YARD.

  • Supports Zeitwerk.

  • Supports common settings and a structured layout for building projects.

  • Provides common documentation:

    • README

    • LICENSE

    • VERSIONS

    • Security

    • Code of Conduct

    • Contributions

    • Communities

Requirements

  1. A UNIX-based system.

  2. Ruby.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install rubysmith --trust-policy HighSecurity

To install without security, run:

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.
  -p, --publish VERSION                    Publish project.
  -v, --version                            Show gem version.

BUILD OPTIONS:
      --[no-]amazing_print                 Add Amazing Print gem. Default: true.
      --[no-]caliber                       Add Caliber gem. Default: true.
      --[no-]circle_ci                     Add Circle CI configuration and badge. Default: false.
      --[no-]citation                      Add citation documentation. Default: true.
      --[no-]community                     Add community documentation. Default: false.
      --[no-]conduct                       Add code of conduct documentation. Default: true.
      --[no-]console                       Add console script. Default: true.
      --[no-]contributions                 Add contributions documentation. Default: true.
      --[no-]debug                         Add Debug gem. Default: true.
      --[no-]funding                       Add GitHub funding configuration. Default: false.
      --[no-]git                           Add Git. Default: true.
      --[no-]git_hub                       Add GitHub templates. Default: false.
      --[no-]git_hub_ci                    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-]security                      Add security. Default: true.
      --[no-]setup                         Add setup script. Default: true.
      --[no-]simple_cov                    Add SimpleCov gem. Default: true.
      --[no-]versions                      Add version history. Default: true.
      --[no-]yard                          Add Yard gem. Default: false.
      --[no-]zeitwerk                      Add Zeitwerk gem. Default: true.

Build

The core functionality of this gem centers around the --build command and associated options (flags). The build options allow you to further customize the kind of project you want to build. Most build options are enabled by default. Example:

rubysmith --build demo

Running the above will generate a new demo Ruby project. Should you wish to disable specific options, you can use --no-* prefixes. Example:

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:

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:

rubysmith --build demo --min --zeitwerk
rubysmith --build demo --max --no-debug

With the above examples, the first line will disable all options except Zeitwerk while the second line will enable all options except 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).

There is a lot of flexibility when building a new project through the various build options. I’ll walk you through each so you can better understand why you’d want to enable or disable any one of them.

Amazing Print

The --amazing_print option allows you to build your project with the Amazing Print gem for debugging purposes and is a handy debugging tool when inspecting your Ruby objects and printing details in a quick to read format.

Caliber

The --caliber option allows you to build your project with the Caliber gem so you have an immediate working — and high quality — RuboCop configuration. Read the Caliber documentation for further customization.

Circle CI

The --circle_ci option allows you to build your project with Circle CI configured so you can get your project building as quickly as possible.

Citation

The --citation option allows you to add a citation file to your project so you can help the research community cite your work in their studies if your project is used.

Community

The --community option allows you to link to your open source community, organization, or group chat to help with community engagement of your work.

Code of Conduct

The --conduct option allows you to link to your Code of Conduct to encourage good community participation. Regardless of whether you have a community or not, the code of conduct is good to encourage in general.

Console

The --console option allows you to add a console script for local development. So instead of typing irb, you can type bin/console and get an IRB session with all of your project’s code loaded.

Contributions

The --contributions option allows you to link to contributing documentation so people know to contribute back to your work.

Debug

The --debug option allows you add the Debug gem to your project for debugging your code by setting breakpoints, remotely connecting to running code, and much more.

Funding

The --funding option allows you add a GitHub funding configuration to your project so you can attract sponsors. This option doesn’t require use of the --git_hub option but is encouraged.

Git

The --git option allows you add Git repository support. Includes Git Safe functionality so you don’t have to prefix commands with the bin/ path prefix. Instead, you can call the command directly (assuming you have configured your Dotfiles accordingly).

GitHub

The --git_hub option allows you add GitHub templates to your project for issues and pull requests.

GitHub CI

The --git_hub_ci option allows you to build your project with GitHub Actions configured so you can get your project building as quickly as possible.

Git Lint

The --git-lint option allows you to add the Git Lint gem to your project to ensure you are crafting your Git commits in a consistent and readable manner.

Guard

The --guard option allows you add the Guard gem to your project for rapid red, green, refactor development cycles.

License

The --license option ensures you build your project with a license.

Maximum

The --max option allows you to build your project with all options enabled. This is a quick way to build a new project with all options enabled without having to pick and choose.

Minimum

The --min option allows you to build your project with all options disabled. This is a quick way to build a new project with the bare minimum of support which is a one step above reaching for a Bundler Inline script.

Rake

The --rake option allows you to add the Rake gem for quickly crafting build scripts.

Readme

The --readme option allows you to add README documentation to your project.

Reek

The --reek option allows you add the Reek gem to your project for code smell and code quality support.

Refinements

The --refinements option allows you to add the Refinements gem to your project which enhances Ruby core objects without monkey patching your code.

RSpec

The --rspec option allows you add the RSpec gem to your project for defining your project specifications and have a framework for testing your code.

Setup

The --setup option allows you to configure you project with automated setup instructions so anyone new to your project can quickly get started by running the bin/setup script.

SimpleCov

The --simple_cov option allows you add the SimpleCov gem to your project to provide full analysis of what your quality of code is for the project.

Versions

The --versions option allows you add a VERSIONS file to your project to provide details about all published versions of your project.

YARD

The --yard option allows you add the YARD gem to your project so you can automate the generation of project documentation. Once your project is built, you can use rake yard to build documentation into the doc/yard folder. This folder is ignored by Git by default. Additional customization is possible via the YARD Rake task as found in the Rakefile.

Zeitwerk

The --zeitwerk option allows you add the Zeitwerk gem to your project so you can reduce the maintence burden of managing requirements when adding new objects to your project.

Publish

Rubysmith can be used to publish your Ruby projects. This is done via the --publish command. If, for example, you want to publish 0.1.0 of your demo project you could do that as follows:

cd demo
rubysmith --publish 0.1.0

This will publish (tag) your demo project as 0.1.0 both locally and on your remote Git repository. Rubysmith uses Milestoner to handle publishing of your project for you. You can use either but the convenience is built in for you.

Configuration

This gem can be configured via a global configuration:

$HOME/.config/rubysmith/configuration.yml

It can also be configured via XDG environment variables. The default configuration is as follows:

:author:
  :email:
  :family_name:
  :given_name:
  :url:
:build:
  :amazing_print: true
  :caliber: true
  :circle_ci: false
  :citation: true
  :cli: false
  :community: false
  :conduct: true
  :console: true
  :contributions: true
  :debug: true
  :funding: false
  :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
  :security: true
  :setup: true
  :simple_cov: true
  :versions: true
  :yard: false
  :zeitwerk: true
:citation:
  :affiliation:
  :message: Please use the following metadata when citing this project in your work.
  :orcid:
:documentation:
  :format: "adoc"
:extensions:
  :milestoner:
    :documentation:
      :format: "adoc"
    :prefixes:
      - Fixed
      - Added
      - Updated
      - Removed
      - Refactored
  :pragmater:
    :comments:
      - "# frozen_string_literal: true"
    :includes:
      - "**/*.rake"
      - "**/*.rb"
      - "*.gemspec"
      - "exe/*"
      - bin/console
      - bin/guard
      - bin/rubocop
      - config.ru
      - Gemfile
      - Guardfile
      - Rakefile
  :tocer:
    :includes:
      - "README.md"
    :label: "## Table of Contents"
:git_hub:
  :user:
:license:
  :label: Hippocratic
  :name: hippocratic
  :version: 2.1
:project:
  :url:
    :community:
    :conduct:
    :contributions:
    :download:
    :funding:
    :home:
    :issues:
    :license:
    :security:
    :source:
    :versions:
  :version: 0.0.0

Feel free to take this default configuration, modify, and save as your own custom configuration.yml.

By customizing your configuration, you can change Rubysmith’s default behavior when building projects. This is a great way to define your own specialized settings other than what is provide for you by default. This is also a handy way to provide additional information needed for some of the build options. I’ll walk you through each section of the configuration so you can learn more.

Author

Author information is used when generating project documentation and is recommended you fill this information in before building a project. Example:

:author:
  :email: jsmith@example.com
  :family_name: Smith
  :given_name: Jill
  :url: https://www.exmaple.com/team/jsmith

If your global Git configuration is properly configured, your given name; family name; and email will be used by default. Should you not want to defer to Git, you can supply custom values as desired. The URL is the only value that can’t be automatically computed for you.

Build

All build options accept booleans values only and can be customized as desired. When changing your build options, they will dynamically render when displaying usage (i.e. rubysmith --help). All of these options have been explained in greater detail in the Usage section.

ℹ️ The cli option is provided to support the Gemsmith gem but is not, currently, used by this project.

Citations

This section allows you to configure your ORCID citation information used by the research community. You should definitely fill this in. Your author information, detailed above, will be used as well.

Documentation

Use this section to define the kind of documentation you want generated for your project. The following options are available:

Extensions

Extensions are additional tooling which can be configured specifically for Rubysmith. The following extensions are currently supported and will override each extensions global configuration should you be using them individually for other purposes:

Follow the above links to learn more about each extension’s gem configuration.

GitHub

Your GitHub user is the handle you setup when creating your GitHub account. This information is used for template, funding, and/or URL construction purposes.

License

Use this section to define the license you want to use for your project. The following kinds of license are available:

  • Apache: Use apache as the name and then supply the appropriate label and version.

  • Hippocratic: Use hippocratic as the name and then supply the appropriate label and version.

  • MIT: Use mit as the name and then supply the appropriate label and version.

Project

There are two sub-categories within this section: URLs and version. The URLs allow you to link to specific documentation related to your project. You’ll want to customize these URLs since they are used for documentation, citations, and general project information. Some of the URLs are also used by the Gemsmith gem.

You can also use %project_name% as a placeholder anywhere in your URL and Rubysmith will ensure your place holder is replaced with your project name when generating a new project. Example:

# Configuration
https://www.example.com/%project_name%

# Command
rubysmith --build demo

# Actual (computed result)
https://www.example.com/demo

As for the version key, this defines the default version of newly created projects. 0.0.0 is the default but you can use a higher version number like 0.1.0 or even 1.0.0 if you are super confident in your work. That said, the lower the number is better when building your initial project.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/rubysmith
cd rubysmith
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Versions

Community

Credits