Generators: Update descriptions (#1198)

Follow-up to #1187 Update descriptions so that they work well in the `README.md` generated by `suspenders:clean_up:generate_readme`. Also fixes a typo in `Suspenders::Cleanup::GenerateReadme`.
thoughtbot · Apr 26, 2024 · fc1c08e · fc1c08e
1 parent 2c8616a
commit fc1c08e
Show file tree

Hide file tree

Showing 19 changed files with 133 additions and 53 deletions.
diff --git a/lib/generators/suspenders/accessibility_generator.rb b/lib/generators/suspenders/accessibility_generator.rb
@@ -4,7 +4,12 @@ class AccessibilityGenerator < Rails::Generators::Base
       include Suspenders::Generators::APIAppUnsupported
 
       desc <<~MARKDOWN
-        Installs capybara_accessibility_audit and capybara_accessible_selectors"
+        Uses [capybara_accessibility_audit][] and
+        [capybara_accessible_selectors][] to encourage and enforce accessibility best
+        practices.
+
+        [capybara_accessibility_audit]: https://github.com/thoughtbot/capybara_accessibility_audit
+        [capybara_accessible_selectors]: https://github.com/citizensadvice/capybara_accessible_selectors
       MARKDOWN
 
       def add_capybara_gems

diff --git a/lib/generators/suspenders/advisories_generator.rb b/lib/generators/suspenders/advisories_generator.rb
@@ -3,10 +3,10 @@ module Generators
     class AdvisoriesGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/advisories", __FILE__)
       desc <<~MARKDOWN
-        Show security advisories during development.
+        Uses [bundler-audit][] to update the local security database and show
+        any relevant issues with the app's dependencies via a Rake task.
 
-        Uses the `bundler-audit` gem to update the local security database and
-        show any relevant issues with the app's dependencies via a Rake task.
+        [bundler-audit]: https://github.com/rubysec/bundler-audit
       MARKDOWN
 
       def add_bundler_audit

diff --git a/lib/generators/suspenders/ci_generator.rb b/lib/generators/suspenders/ci_generator.rb
@@ -6,7 +6,10 @@ class CiGenerator < Rails::Generators::Base
 
       source_root File.expand_path("../../templates/ci", __FILE__)
       desc <<~MARKDOWN
-        Creates CI files for GitHub Actions
+        Uses [GitHub Actions][] for CI, and [Dependabot][] for dependency updates.
+
+        [GitHub Actions]: https://docs.github.com/en/actions
+        [Dependabot]: https://docs.github.com/en/code-security/dependabot/working-with-dependabot
       MARKDOWN
 
       def ci_files

diff --git a/lib/generators/suspenders/email_generator.rb b/lib/generators/suspenders/email_generator.rb
@@ -3,13 +3,17 @@ module Generators
     class EmailGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/email", __FILE__)
       desc <<~MARKDOWN
-        Intercepts emails in non-production environments by setting `INTERCEPTOR_ADDRESSES`.
+        [Intercept][] emails in non-production environments by setting `INTERCEPTOR_ADDRESSES`.
 
         ```sh
         INTERCEPTOR_ADDRESSES="[email protected],[email protected]" bin/rails s
         ```
 
-        Configures `default_url_options` in `test` and `development`.
+        Configuration can be found at `config/initializers/email_interceptor.rb`.
+
+        Interceptor can be found at `app/mailers/email_interceptor.rb`.
+
+        [Intercept]: https://guides.rubyonrails.org/action_mailer_basics.html#intercepting-emails
       MARKDOWN
 
       def create_email_interceptor

diff --git a/lib/generators/suspenders/environments/development_generator.rb b/lib/generators/suspenders/environments/development_generator.rb
@@ -3,12 +3,10 @@ module Generators
     module Environments
       class DevelopmentGenerator < Rails::Generators::Base
         desc <<~MARKDOWN
-          Configures the development environment.
-
-          - Enables [raise_on_missing_translations][]
-          - Enables [annotate_rendered_view_with_filenames][]
-          - Enables [i18n_customize_full_message][]
-          - Enables [query_log_tags_enabled][]
+          - Enables [raise_on_missing_translations][].
+          - Enables [annotate_rendered_view_with_filenames][].
+          - Enables [i18n_customize_full_message][].
+          - Enables [query_log_tags_enabled][].
 
           [raise_on_missing_translations]: https://guides.rubyonrails.org/configuring.html#config-i18n-raise-on-missing-translations
           [annotate_rendered_view_with_filenames]: https://guides.rubyonrails.org/configuring.html#config-action-view-annotate-rendered-view-with-filenames

diff --git a/lib/generators/suspenders/environments/production_generator.rb b/lib/generators/suspenders/environments/production_generator.rb
@@ -3,9 +3,7 @@ module Generators
     module Environments
       class ProductionGenerator < Rails::Generators::Base
         desc <<~MARKDOWN
-          Configures the production environment.
-
-          - Enables [require_master_key][]
+          - Enables [require_master_key][].
 
           [require_master_key]: https://guides.rubyonrails.org/configuring.html#config-require-master-key
         MARKDOWN

diff --git a/lib/generators/suspenders/environments/test_generator.rb b/lib/generators/suspenders/environments/test_generator.rb
@@ -3,14 +3,8 @@ module Generators
     module Environments
       class TestGenerator < Rails::Generators::Base
         desc <<~MARKDOWN
-          Configures test environment.
-
-          ```
-          bin/rails g suspenders:test:environment
-          ```
-
-          - Enables [raise_on_missing_translations][]
-          - Disables [action_dispatch.show_exceptions][]
+          - Enables [raise_on_missing_translations][].
+          - Disables [action_dispatch.show_exceptions][].
 
           [raise_on_missing_translations]: https://guides.rubyonrails.org/configuring.html#config-i18n-raise-on-missing-translations
           [action_dispatch.show_exceptions]: https://edgeguides.rubyonrails.org/configuring.html#config-action-dispatch-show-exceptions

diff --git a/lib/generators/suspenders/factories_generator.rb b/lib/generators/suspenders/factories_generator.rb
@@ -5,18 +5,16 @@ class FactoriesGenerator < Rails::Generators::Base
 
       source_root File.expand_path("../../templates/factories", __FILE__)
       desc <<~MARKDOWN
-        Build test data with clarity and ease.
+        Uses [FactoryBot][] as an alternative to [Fixtures][] to help you define
+        dummy and test data for your test suite. The `create`, `build`, and
+        `build_stubbed` class methods are directly available to all tests.
 
-        This uses FactoryBot to help you define dummy and test data for your test
-        suite. The `create`, `build`, and `build_stubbed` class methods are directly
-        available to all tests.
+        Place FactoryBot definitions in `spec/factories.rb`, at least until it
+        grows unwieldy. This helps reduce confusion around circular dependencies and
+        makes it easy to jump between definitions.
 
-        We recommend putting FactoryBot definitions in one `spec/factories.rb` (or
-        `test/factories`) file, at least until it grows unwieldy. This helps reduce
-        confusion around circular dependencies and makes it easy to jump between
-        definitions.
-
-        Supports the default test suite and RSpec.
+        [FactoryBot]: https://github.com/thoughtbot/factory_bot
+        [Fixtures]: https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures
       MARKDOWN
 
       def add_factory_bot

diff --git a/lib/generators/suspenders/inline_svg_generator.rb b/lib/generators/suspenders/inline_svg_generator.rb
@@ -4,7 +4,11 @@ class InlineSvgGenerator < Rails::Generators::Base
       include Suspenders::Generators::APIAppUnsupported
       source_root File.expand_path("../../templates/inline_svg", __FILE__)
       desc <<~MARKDOWN
-        Render SVG images inline, as a potential performance improvement for the viewer.
+        Uses [inline_svg][] for embedding SVG documents into views.
+
+        Configuration can be found at `config/initializers/inline_svg.rb`
+
+        [inline_svg]: https://github.com/jamesmartin/inline_svg
       MARKDOWN
 
       def add_inline_svg_gem

diff --git a/lib/generators/suspenders/jobs_generator.rb b/lib/generators/suspenders/jobs_generator.rb
@@ -2,7 +2,13 @@ module Suspenders
   module Generators
     class JobsGenerator < Rails::Generators::Base
       desc <<~MARKDOWN
-        Installs Sidekiq for background job processing.
+        Uses [Sidekiq][] for [background job][] processing.
+
+        Configures the `test` environment to use the [inline][] adapter.
+
+        [Sidekiq]: https://github.com/sidekiq/sidekiq
+        [background job]: https://guides.rubyonrails.org/active_job_basics.html
+        [inline]: https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters/InlineAdapter.html
       MARKDOWN
 
       def add_sidekiq_gem

diff --git a/lib/generators/suspenders/lint_generator.rb b/lib/generators/suspenders/lint_generator.rb
@@ -5,7 +5,26 @@ class LintGenerator < Rails::Generators::Base
 
       source_root File.expand_path("../../templates/lint", __FILE__)
       desc <<~MARKDOWN
-        Creates a holistic linting solution that covers JavaScript, CSS, Ruby and ERB.
+        - Uses [@thoughtbot/eslint-config][] for JavaScript linting.
+        - Uses [@thoughtbot/stylelint-config][] for CSS linting.
+        - Uses [prettier][] for additional linting.
+        - Uses [better_html][], [erb_lint][], and [erblint-github][] for ERB linting.
+        - Uses [standard][] for Ruby linting.
+
+        **Available Commands**
+
+        - Run `yarn lint` to lint front-end code.
+        - Run `yarn fix:prettier` to automatically fix prettier violations.
+        - Run `bin/rails standard` to lint ERB and Ruby code.
+        - Run `bundle exec standardrb --fix` to fix standard violations.
+
+        [@thoughtbot/eslint-config]: https://github.com/thoughtbot/eslint-config
+        [@thoughtbot/stylelint-config]: https://github.com/thoughtbot/stylelint-config
+        [prettier]: https://prettier.io
+        [better_html]: https://github.com/Shopify/better-html
+        [erb_lint]: https://github.com/Shopify/erb-lint
+        [erblint-github]: https://github.com/github/erblint-github
+        [standard]: https://github.com/standardrb/standard
       MARKDOWN
 
       def check_package_json

diff --git a/lib/generators/suspenders/prerequisites_generator.rb b/lib/generators/suspenders/prerequisites_generator.rb
@@ -4,7 +4,7 @@ class PrerequisitesGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/prerequisites", __FILE__)
 
       desc <<~MARKDOWN
-        Configures prerequisites. Currently Node.
+        Creates `.node-version` file set to the current LTS version.
       MARKDOWN
 
       def node_version

diff --git a/lib/generators/suspenders/rake_generator.rb b/lib/generators/suspenders/rake_generator.rb
@@ -3,8 +3,13 @@ module Generators
     class RakeGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/rake", __FILE__)
       desc <<~MARKDOWN
-        Configures the default Rake task to audit and lint the codebase with
-        `bundler-audit` and `standard`, in addition to running the test suite.
+        Adds default Raketask wich is a wrapper for `suspenders:rake`.
+
+        This will do the following:
+
+          - Run the test suite.
+          - Run a Ruby and ERB linter.
+          - Scan the Ruby codebase for any dependency vulnerabilities.
       MARKDOWN
 
       def configure_default_rake_task

diff --git a/lib/generators/suspenders/setup_generator.rb b/lib/generators/suspenders/setup_generator.rb
@@ -3,11 +3,7 @@ module Generators
     class SetupGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/setup", __FILE__)
       desc <<~MARKDOWN
-        A holistic setup script.
-
-        ```sh
-        bin/setup
-        ```
+        Run `bin/setup` to install dependencies and seed development data.
       MARKDOWN
 
       def replace_bin_setup

diff --git a/lib/generators/suspenders/styles_generator.rb b/lib/generators/suspenders/styles_generator.rb
@@ -5,9 +5,26 @@ class StylesGenerator < Rails::Generators::Base
 
       source_root File.expand_path("../../templates/styles", __FILE__)
       desc <<~MARKDOWN
-        Configures application to use PostCSS via cssbundling-rails.
+        - Uses [PostCSS][] via [cssbundling-rails][].
+        - Uses [modern-normalize][] to normalize browsers' default style.
 
-        Adds modern-normalize, and style sheet structure.
+        Configuration can be found at `postcss.config.js`.
+
+        Adds the following stylesheet structure.
+
+        ```
+        app/assets/stylesheets/base.css
+        app/assets/stylesheets/components.css
+        app/assets/stylesheets/utilities.css
+        ```
+
+        Adds `app/assets/static` so that [postcss-url][] has a directory to copy
+        assets to.
+
+        [PostCSS]: https://postcss.org
+        [cssbundling-rails]: https://github.com/rails/cssbundling-rails
+        [modern-normalize]: https://github.com/sindresorhus/modern-normalize
+        [postcss-url]: https://github.com/postcss/postcss-url
       MARKDOWN
 
       def add_cssbundling_rails_gem

diff --git a/lib/generators/suspenders/tasks_generator.rb b/lib/generators/suspenders/tasks_generator.rb
@@ -3,9 +3,9 @@ module Generators
     class TasksGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/tasks", __FILE__)
       desc <<~MARKDOWN
-        Creates local Rake tasks for development
+        Creates `lib/tasks/dev.rake` which contains the following tasks:
 
-        bin/rails dev:prime # Sample data for local development environment
+        `bin/rails dev:prime` which loads sample data for local development.
       MARKDOWN
 
       def create_dev_rake

diff --git a/lib/generators/suspenders/testing_generator.rb b/lib/generators/suspenders/testing_generator.rb
@@ -3,7 +3,31 @@ module Generators
     class TestingGenerator < Rails::Generators::Base
       source_root File.expand_path("../../templates/testing", __FILE__)
       desc <<~MARKDOWN
-        Set up the project for an in-depth test-driven development workflow.
+        Uses [RSpec][] and [RSpec Rails][] in favor of the [default test suite][].
+
+        The test suite can be run with `bin/rails spec`.
+
+        Configuration can be found in the following files:
+
+        ```
+        spec/rails_helper.rb
+        spec/spec_helper.rb
+        spec/support/action_mailer.rb
+        spec/support/driver.rb
+        spec/support/i18n.rb
+        spec/support/should_matchers.rb
+        ```
+
+        - Uses [action_dispatch-testing-integration-capybara][] to introduce Capybara assertions into Request specs.
+        - Uses [should-matchers][] for simple one-liner tests for common Rails functionality.
+        - Uses [webmock][] for stubbing and setting expectations on HTTP requests in Ruby.
+
+        [RSpec]: http://rspec.info
+        [RSpec Rails]: https://github.com/rspec/rspec-rails
+        [default test suite]: https://guides.rubyonrails.org/testing.html
+        [action_dispatch-testing-integration-capybara]: https://github.com/thoughtbot/action_dispatch-testing-integration-capybara
+        [should-matchers]: https://github.com/thoughtbot/shoulda-matchers
+        [webmock]: https://github.com/bblimke/webmock
       MARKDOWN
 
       def add_gems

diff --git a/lib/generators/suspenders/views_generator.rb b/lib/generators/suspenders/views_generator.rb
@@ -3,10 +3,19 @@ module Generators
     class ViewsGenerator < Rails::Generators::Base
       include Suspenders::Generators::APIAppUnsupported
 
+      source_root File.expand_path("../../templates/views", __FILE__)
       desc <<~MARKDOWN
-        Configures flash messages, page titles and the document lang. Disables Turbo's InstantClick.
+        - A [partial][] for [flash messages][] is located in `app/views/application/_flashes.html.erb`.
+        - Sets [lang][] attribute on `<html>` element to `en` via `I18n.local`.
+        - Dynamically sets `<title>` via the [title][] gem.
+        - Disables Turbo's [Prefetch][] in an effort to reduce unnecessary network requests.
+
+        [partial]: https://guides.rubyonrails.org/layouts_and_rendering.html#using-partials
+        [flash messages]: https://guides.rubyonrails.org/action_controller_overview.html#the-flash
+        [lang]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang
+        [title]: https://github.com/calebhearth/title
+        [Prefetch]: https://turbo.hotwired.dev/handbook/drive#prefetching-links-on-hover
       MARKDOWN
-      source_root File.expand_path("../../templates/views", __FILE__)
 
       def install_gems
         gem "title"

diff --git a/lib/suspenders/cleanup/generate_readme.rb b/lib/suspenders/cleanup/generate_readme.rb
@@ -128,7 +128,7 @@ def local_development
           - Use `bin/rails default` to run the default Rake task. This will do the following:
             - Run the test suite.
             - Run a Ruby and ERB linter.
-            - Scan the Ruby codebase for any dependecy vulnerabilities.
+            - Scan the Ruby codebase for any dependency vulnerabilities.
 
           [database migrations]: https://edgeguides.rubyonrails.org/active_record_migrations.html#running-migrations
           [reversible]: https://edgeguides.rubyonrails.org/active_record_migrations.html#making-the-irreversible-possible