add more detailed description when adding --help option to generator.

[yorzi]

Refers to: #159

Result as below:

rails g react_on_rails:install --help
Usage:
  rails generate react_on_rails:install [options]

Options:
  -R, [--redux], [--no-redux]                          # Install Redux gems and Redux version of Hello World Example. Default: false
  -S, [--server-rendering], [--no-server-rendering]    # Add necessary files and configurations for server-side rendering. Default: false
  -j, [--skip-js-linters], [--no-skip-js-linters]      # Skip installing JavaScript linting files. Default: false
  -L, [--ruby-linters], [--no-ruby-linters]            # Install ruby linting files, tasks, and configs. Default: false
  -H, [--heroku-deployment], [--no-heroku-deployment]  # Install files necessary for deploying to Heroku. Default: false
  -b, [--skip-bootstrap], [--no-skip-bootstrap]        # Skip integrating Bootstrap and don't initialize files and regarding configs. Default: false

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

Description:

The react_on_rails:install generator combined with the example pull requests of generator runs
will get you up and running efficiently. There's a fair bit of setup with integrating Webpack
with Rails. Defaults for options are such that the default is for the flag to be off. For example,
the default for -R is that redux is off, and the default of -b means that skip-bootstrap is off.

* Redux

    If you have used the --redux generator option, you will notice the familiar additional redux
    folders in addition to the aforementioned folders. The Hello World example has also been modified
    to use Redux.

    Note the organizational paradigm of "bundles". These are like application domains and are used
    for grouping your code into webpack bundles, in case you decide to create different bundles for
    deployment. This is also useful for separating out logical parts of your application. The concept
    is that each bundle will have it's own Redux store. If you have code that you want to reuse across
    bundles, including components and reducers, place them under /client/app/lib.

* Using Images and Fonts

    The generator has amended the folders created in client/assets/ to Rails's asset path. We recommend
    that if you have any existing assets that you want to use with your client code, you should move
    them to these folders and use webpack as normal. This allows webpack's development server to have
    access to your assets, as it will not be able to see any assets in the default Rails directories
    which are above the /client directory.

    Alternatively, if you have many existing assets and don't wish to move them, you could consider
    creating symlinks from client/assets that point to your Rails assets folders inside of app/assets/.
    The assets there will then be visible to both Rails and webpack.

* Bootstrap Integration

    React on Rails ships with Twitter Bootstrap already integrated into the build. Note that the
    generator removes require_tree in both the application.js and application.css.scss files. This
    is to ensure the correct load order for the bootstrap integration, and is usually a good idea
    in general. You will therefore need to explicitly require your files.

    How the Bootstrap library is loaded depends upon whether one is using the Rails server or the
    HMR development server.

    1. Bootstrap via Rails Server

        In the former case, the Rails server loads bootstrap-sprockets, provided by the bootstrap-sass
        ruby gem (added automatically to your Gemfile by the generator) via the
        `app/assets/stylesheets/_bootstrap-custom.scss` partial.

        This allows for using Bootstrap in your regular Rails stylesheets. If you wish to customize any
        of the Bootstrap variables, you can do so via the client/assets/stylesheets/_pre-bootstrap.scss partial.

    2. Bootstrap via Webpack Dev Server

        When using the webpack dev server, which does not go through Rails, bootstrap is loaded via the
        `bootstrap-sass-loader` which uses the `client/bootstrap-sass-config.js` file.

    3. Keeping Custom Bootstrap Configurations Synced

        Because the webpack dev server and Rails each load Bootstrap via a different file (explained in the
        two sections immediately above), any changes to the way components are loaded in one file must also
        be made to the other file in order to keep styling consistent between the two. For example, if an
        import is excluded in _bootstrap-custom.scss, the same import should be excluded in `bootstrap-sass-config.js`
        so that styling in the Rails server and the webpack dev server will be the same.

    4. Skip Bootstrap Integration

        Bootstrap integration is enabled by default, but can be disabled by passing the --skip-bootstrap flag
        (alias -b). When you don't need Bootstrap in your existing project, just skip it as needed.

* Linters

    The React on Rails generator can add linters and their recommended accompanying configurations to your project.
    There are two classes of linters: ruby linters and JavaScript linters.

* JavaScript Linters

    JavaScript linters are enabled by default, but can be disabled by passing the --skip-js-linters flag (alias j),
    and those that run in Node have been add to client/package.json under devDependencies.

* Ruby Linters

    Ruby linters are disabled by default, but can be enabled by passing the --ruby-linters flag when generating.
    These linters have been added to your Gemfile in addition to the the appropriate Rake tasks.

    We really love using all the linters! Give them a try.

* Running the Linters

    To run the linters (runs all linters you have installed, even if you installed both Ruby and Node):

    `rake lint`

    Run this command to see all the linters available

    `rake -T lint`

    Here's the list:
    ==========================================================
    rake lint               # Runs all linters
    rake lint:eslint        # eslint
    rake lint:js            # JS Linting
    rake lint:jscs          # jscs
    rake lint:rubocop[fix]  # Run Rubocop lint in shell
    rake lint:ruby          # Run ruby-lint as shell
    rake lint:scss          # See docs for task 'scss_lint'
    ==========================================================

More Details:

    `https://github.com/shakacode/react_on_rails#generator`

[justin808]

@yorzi How do you feel about keeping the width to 80 chars?

[yorzi]

Defaults for options are such that the default is for the flag to be off. For example,
the default for -R is that redux is off, and the default of -b means that skip-bootstrap is off.

Change this to:

Defaults for options are such that mean to add (when `true`) or to NOT add (when `false`) the option by default. For example,
the default (`false`) for -R option is that `--redux` or `-R` is not added by default, and the default (`false`) of -b means that `--skip-bootstrap` or `-b` is not added by default.

cc @justin808

[justin808]

@robwise will be the rewording master!

[justin808]

The single character options are off by default. Thus, if you specify -R, you will add Redux.

[justin808]

@yorzi this sounds fine

[yorzi]

@justin808 80 chars sounds good. let me update it.

[yorzi]

@robwise please help to review wordings in this PR. Thanks.

[robwise]

"setup involved when with integrating"

[robwise]

"Defaults for options are such that the default is for the flag to be off."

@justin808 I still think the defaults thing is self-explanatory from running the rake descriptions. I'd at least change this sentence as it's super confusing.

[robwise]

@justin808 Also, a lot of this information, both the generators and linters information, is completely redundant and is already inside of the Readme. We should not have documentation for the same exact thing twice. The last thing we need to do is add more stuff to read. Let's either use the README version or this version, but not both? Then we delete what's in the README so that we only have to update this info in a single place from now on.

[robwise]

@yorzi @justin808 I added a bunch of editing-related comments. Sorry Andy, I know a lot of these are about things that weren't your fault but were already in the Readme like that because Justin or I wrote them that way!

On that note, I think we should maintain a single source of truth and try to write our documentation in a way that minimizes the need for future updating whenever possible. Misinformation is worse than no information. Therefore, I think what we should do is change the sections in the Readme that are covered here to simply point to this file and delete the text in the README.

Otherwise it's just too likely that we will forget to update one of the two.

Lastly, Andy, have you double checked that this stuff actually shows up when you run the help command? Is it just automatically included if you called the file USAGE or something?

[yorzi]

@robwise I will follow up your comments later. Thanks.

And, YES, it just shows up when I run generator with a --help option in real case.
The convention is here: https://github.com/rails/rails/blob/7f18ea14c893cb5c9f04d4fda9661126758332b5/railties/lib/rails/generators/base.rb#L364

So, to define source_root and add one USAGE file in correct path are the tricks.

[robwise]

@yorzi cool, I didn't know that!!

[justin808]

Hi @yorzi and @robwise! I trust Rob's edits. Rob, it might be easier for you to apply many of the changes. In terms of avoiding duplication, there's no easy way around this. For example, suppose our README refers to the help output, but then one has to install the gem. If the help refers to the README, that's a bit better. Also, the README can have formatting, the output doesn't. One thing we could do is to save the --help output to a file and have the README refer to that.

[robwise]

@justin808 The help output is saved to a file in a way—lib/generators/USAGE! That's what I was saying, have the README link to the online location of this file?

[justin808]

@robwise @yorzi Can we merge this?

[robwise]

@justin808 We never got a final decision on my comment

[justin808]

@yorzi Did you get a chance to make that change? Let's get this merged.

[yorzi]

@justin808 @robwise sorry for the delay, I've update the wording that Rob points out.