Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve app generator docs #45973

Merged
merged 1 commit into from
Sep 9, 2022

Conversation

gmcgibbon
Copy link
Member

@gmcgibbon gmcgibbon commented Sep 8, 2022

Motivation / Background

Improves the documentation for the app generator.

Detail

Before:

% bin/rails new -h
Usage:
  rails new APP_PATH [options]

Options:
          [--skip-namespace], [--no-skip-namespace]              # Skip namespace (affects only isolated engines)
          [--skip-collision-check], [--no-skip-collision-check]  # Skip collision check
  -r, [--ruby=PATH]                                              # Path to the Ruby binary of your choice
                                                                 # Default: /opt/rubies/3.1.0/bin/ruby
  -n, [--name=NAME]                                              # Name of the app
  -m, [--template=TEMPLATE]                                      # Path to some application template (can be a filesystem path or URL)
  -d, [--database=DATABASE]                                      # Preconfigure for selected database (options: mysql/postgresql/sqlite3/oracle/sqlserver/jdbcmysql/jdbcsqlite3/jdbcpostgresql/jdbc)
                                                                 # Default: sqlite3
  -G, [--skip-git], [--no-skip-git]                              # Skip git init, .gitignore and .gitattributes
          [--skip-keeps], [--no-skip-keeps]                      # Skip source control .keep files
  -M, [--skip-action-mailer], [--no-skip-action-mailer]          # Skip Action Mailer files
          [--skip-action-mailbox], [--no-skip-action-mailbox]    # Skip Action Mailbox gem
          [--skip-action-text], [--no-skip-action-text]          # Skip Action Text gem
  -O, [--skip-active-record], [--no-skip-active-record]          # Skip Active Record files
          [--skip-active-job], [--no-skip-active-job]            # Skip Active Job
          [--skip-active-storage], [--no-skip-active-storage]    # Skip Active Storage files
  -C, [--skip-action-cable], [--no-skip-action-cable]            # Skip Action Cable files
  -A, [--skip-asset-pipeline], [--no-skip-asset-pipeline]        # Indicates when to generate skip asset pipeline
  -a, [--asset-pipeline=ASSET_PIPELINE]                          # Choose your asset pipeline [options: sprockets (default), propshaft]
                                                                 # Default: sprockets
  -J, --skip-js, [--skip-javascript], [--no-skip-javascript]     # Skip JavaScript files
          [--skip-hotwire], [--no-skip-hotwire]                  # Skip Hotwire integration
          [--skip-jbuilder], [--no-skip-jbuilder]                # Skip jbuilder gem
  -T, [--skip-test], [--no-skip-test]                            # Skip test files
          [--skip-system-test], [--no-skip-system-test]          # Skip system test files
          [--skip-bootsnap], [--no-skip-bootsnap]                # Skip bootsnap gem
          [--skip-dev-gems], [--no-skip-dev-gems]                # Skip development gems (e.g., web-console)
          [--dev], [--no-dev]                                    # Set up the application with Gemfile pointing to your Rails checkout
          [--edge], [--no-edge]                                  # Set up the application with Gemfile pointing to Rails repository
  --master, [--main], [--no-main]                                # Set up the application with Gemfile pointing to Rails repository main branch
          [--rc=RC]                                              # Path to file containing extra configuration options for rails command
          [--no-rc], [--no-no-rc]                                # Skip loading of extra configuration options from .railsrc file
          [--api], [--no-api]                                    # Preconfigure smaller stack for API only apps
          [--minimal], [--no-minimal]                            # Preconfigure a minimal rails app
  -j, --js, [--javascript=JAVASCRIPT]                            # Choose JavaScript approach [options: importmap (default), webpack, esbuild, rollup]
                                                                 # Default: importmap
  -c, [--css=CSS]                                                # Choose CSS processor [options: tailwind, bootstrap, bulma, postcss, sass... check https://github.com/rails/cssbundling-rails]
  -B, [--skip-bundle], [--no-skip-bundle]                        # Don't run bundle install
          [--skip-decrypted-diffs], [--no-skip-decrypted-diffs]  # Don't configure git to show decrypted diffs of encrypted credentials

Runtime options:
  -f, [--force]                    # Overwrite files that already exist
  -p, [--pretend], [--no-pretend]  # Run but do not make any changes
  -q, [--quiet], [--no-quiet]      # Suppress status output
  -s, [--skip], [--no-skip]        # Skip files that already exist

Rails options:
  -h, [--help], [--no-help]        # Show this help message and quit
  -v, [--version], [--no-version]  # Show Rails version number and quit

Description:
    The 'rails new' command creates a new Rails application with a default
    directory structure and configuration at the path you specify.

    You can specify extra command-line arguments to be used every time
    'rails new' runs in the .railsrc configuration file in your home directory,
    or in $XDG_CONFIG_HOME/rails/railsrc if XDG_CONFIG_HOME is set.

    Note that the arguments specified in the .railsrc file don't affect the
    default values shown above in this help message.

Example:
    rails new ~/Code/Ruby/weblog

    This generates a skeletal Rails installation in ~/Code/Ruby/weblog.

After:

% bin/rails new -h
Usage:
  rails new APP_PATH [options]

Options:
          [--skip-namespace], [--no-skip-namespace]              # Skip namespace (affects only isolated engines)
          [--skip-collision-check], [--no-skip-collision-check]  # Skip collision check
  -r, [--ruby=PATH]                                              # Path to the Ruby binary of your choice
                                                                 # Default: /opt/rubies/3.1.0/bin/ruby
  -n, [--name=NAME]                                              # Name of the app
  -m, [--template=TEMPLATE]                                      # Path to some application template (can be a filesystem path or URL)
  -d, [--database=DATABASE]                                      # Preconfigure for selected database (options: mysql/postgresql/sqlite3/oracle/sqlserver/jdbcmysql/jdbcsqlite3/jdbcpostgresql/jdbc)
                                                                 # Default: sqlite3
  -G, [--skip-git], [--no-skip-git]                              # Skip git init, .gitignore and .gitattributes
          [--skip-keeps], [--no-skip-keeps]                      # Skip source control .keep files
  -M, [--skip-action-mailer], [--no-skip-action-mailer]          # Skip Action Mailer files
          [--skip-action-mailbox], [--no-skip-action-mailbox]    # Skip Action Mailbox gem
          [--skip-action-text], [--no-skip-action-text]          # Skip Action Text gem
  -O, [--skip-active-record], [--no-skip-active-record]          # Skip Active Record files
          [--skip-active-job], [--no-skip-active-job]            # Skip Active Job
          [--skip-active-storage], [--no-skip-active-storage]    # Skip Active Storage files
  -C, [--skip-action-cable], [--no-skip-action-cable]            # Skip Action Cable files
  -A, [--skip-asset-pipeline], [--no-skip-asset-pipeline]        # Indicates when to generate skip asset pipeline
  -a, [--asset-pipeline=ASSET_PIPELINE]                          # Choose your asset pipeline [options: sprockets (default), propshaft]
                                                                 # Default: sprockets
  -J, --skip-js, [--skip-javascript], [--no-skip-javascript]     # Skip JavaScript files
          [--skip-hotwire], [--no-skip-hotwire]                  # Skip Hotwire integration
          [--skip-jbuilder], [--no-skip-jbuilder]                # Skip jbuilder gem
  -T, [--skip-test], [--no-skip-test]                            # Skip test files
          [--skip-system-test], [--no-skip-system-test]          # Skip system test files
          [--skip-bootsnap], [--no-skip-bootsnap]                # Skip bootsnap gem
          [--skip-dev-gems], [--no-skip-dev-gems]                # Skip development gems (e.g., web-console)
          [--dev], [--no-dev]                                    # Set up the application with Gemfile pointing to your Rails checkout
          [--edge], [--no-edge]                                  # Set up the application with Gemfile pointing to Rails repository
  --master, [--main], [--no-main]                                # Set up the application with Gemfile pointing to Rails repository main branch
          [--rc=RC]                                              # Path to file containing extra configuration options for rails command
          [--no-rc], [--no-no-rc]                                # Skip loading of extra configuration options from .railsrc file
          [--api], [--no-api]                                    # Preconfigure smaller stack for API only apps
          [--minimal], [--no-minimal]                            # Preconfigure a minimal rails app
  -j, --js, [--javascript=JAVASCRIPT]                            # Choose JavaScript approach [options: importmap (default), webpack, esbuild, rollup]
                                                                 # Default: importmap
  -c, [--css=CSS]                                                # Choose CSS processor [options: tailwind, bootstrap, bulma, postcss, sass... check https://github.com/rails/cssbundling-rails]
  -B, [--skip-bundle], [--no-skip-bundle]                        # Don't run bundle install
          [--skip-decrypted-diffs], [--no-skip-decrypted-diffs]  # Don't configure git to show decrypted diffs of encrypted credentials

Runtime options:
  -f, [--force]                    # Overwrite files that already exist
  -p, [--pretend], [--no-pretend]  # Run but do not make any changes
  -q, [--quiet], [--no-quiet]      # Suppress status output
  -s, [--skip], [--no-skip]        # Skip files that already exist

Rails options:
  -h, [--help], [--no-help]        # Show this help message and quit
  -v, [--version], [--no-version]  # Show Rails version number and quit

Description:
    The `rails new` command creates a new Rails application with a default
    directory structure and configuration at the path you specify.

    You can specify extra command-line arguments to be used every time
    `rails new` runs in the .railsrc configuration file in your home directory,
    or in $XDG_CONFIG_HOME/rails/railsrc if XDG_CONFIG_HOME is set.

    Note that the arguments specified in the .railsrc file don't affect the
    default values shown above in this help message.

Examples:
    `rails new ~/Code/Ruby/weblog`

    This generates a new Rails app in ~/Code/Ruby/weblog.

    `rails new weblog --api`

    This generates a new Rails app in API mode in ./weblog.

    `rails new weblog --skip-action-mailer`

    This generates a new Rails app without Action Mailer in ./weblog.
    Any part of Rails can be skipped during app generation.

Additional information

Mainly the two big edits are:

  • Minor formatting changes
  • Adds more examples with common options

Checklist

Before submitting the PR make sure the following are checked:

  • This Pull Request is related to one change. Changes that are unrelated should be opened in separate PRs.
  • There are no typos in commit messages and comments.
  • Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: [Fix #issue-number]
  • Feature branch is up-to-date with main (if not - rebase it).
  • Pull request only contains one commit for bug fixes and small features. If it's a larger feature, multiple commits are permitted but must be descriptive.
  • Tests are added if you fix a bug or add a feature.
  • CHANGELOG files are updated for the changed libraries if there is a behavior change or additional feature. Minor bug fixes and documentation changes should not be included.
  • PR is not in a draft state.
  • CI is passing.

- Minor formatting changes
- Adds more examples with common options
@gmcgibbon gmcgibbon merged commit ed81896 into rails:main Sep 9, 2022
@gmcgibbon gmcgibbon deleted the improve_app_generator_docs branch September 9, 2022 21:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants