Merge pull request #933 from grails/restore-grails-shell-cli-docs

restore grails-shell cli command and profiles documentation

Author: jamesfredley

src/en/guide/REST/angularJsProfile.adoc

@@ -0,0 +1,94 @@
+Since Grails 3.1, Grails supports a profile for creating applications with AngularJS that provides a more focused set of dependencies and commands. The angular profile inherits from the REST profile and therefore has all of the commands and properties that the REST profile has.
+
+To get started with the AngularJS profile, create an application specifying `angularjs` as the name of the profile:
+
+[source,bash]
+----
+$ grails create-app my-api --profile angularjs
+----
+
+This will create a new Grails application that provides the following features:
+
+* Default set of commands for creating AngularJS artefacts
+* Gradle plugin to manage client side dependencies
+* Gradle plugin to execute client side unit tests
+* Asset Pipeline plugins to ease development
+
+By default the AngularJS profile includes GSP support in order to render the index page. This is necessary because the profile is designed around asset pipeline.
+
+The new commands are:
+
+* `create-ng-component`
+* `create-ng-controller`
+* `create-ng-directive`
+* `create-ng-domain`
+* `create-ng-module`
+* `create-ng-service`
+
+
+
+==== Project structure
+
+
+The AngularJS profile is designed around a specific project structure. The `create-ng` commands will automatically create modules where they do not exist.
+
+Example:
+[source,bash]
+----
+$ grails create-ng-controller foo
+----
+
+This will produce a `fooController.js` file in `grails-app/assets/javascripts/${default package name}/controllers`.
+
+NOTE: By default the angularjs profile will create files in the `javascripts` directory. You can change that behavior in your configuration with the key `grails.codegen.angular.assetDir`.
+
+[source,bash]
+----
+$ grails create-ng-domain foo.bar
+----
+
+This will produce a `Bar.js` file in `grails-app/assets/javascripts/foo/domains`. It will also create the "foo" module if it does not already exist.
+
+[source,bash]
+----
+$ grails create-ng-module foo.bar
+----
+
+This will produce a `foo.bar.js` file in `grails-app/assets/javascripts/foo/bar`. Note the naming convention for modules is different than other artefacts.
+
+[source,bash]
+----
+$ grails create-ng-service foo.bar --type constant
+----
+
+This will produce a `bar.js` file in `grails-app/assets/javascripts/foo/services`. It will also create the "foo" module if it does not already exist. The `create-ng-service` command accepts a flag `-type`. The types that can be used are:
+
+* service
+* factory _default_
+* value
+* provider
+* constant
+
+Along with the artefacts themselves, the profile will also produce a skeleton unit test file under `src/test/javascripts` for each create command.
+
+
+==== Client side dependencies
+
+
+The https://github.com/craigburke/bower-installer-gradle[Gradle Bower Plugin] is used to manage dependencies with bower. Visit the plugin documentation to learn how to use the plugin.
+
+
+==== Unit Testing
+
+
+The https://github.com/craigburke/karma-gradle[Gradle Karma Plugin] is used to execute client side unit tests. All generated tests are written with Jasmine. Visit the plugin documentation to learn how to use the plugin.
+
+
+==== Asset Pipeline
+
+
+The AngularJS profile includes several asset pipeline plugins to make development easier.
+
+* https://github.com/craigburke/js-closure-wrap-asset-pipeline[JS Closure Wrap Asset Pipeline] will wrap your Angular code in immediately invoked function expressions.
+* https://github.com/craigburke/angular-annotate-asset-pipeline[Annotate Asset Pipeline] will annotate your dependencies to be safe for minification.
+* https://github.com/craigburke/angular-template-asset-pipeline[Template Asset Pipeline] will put your templates into the `$templateCache` to prevent http requests to retrieve the templates.

src/en/guide/REST/angularProfile.adoc

@@ -0,0 +1,94 @@
+Since Grails 3.2.1, Grails supports a profile for creating applications with Angular that provides a more future facing setup.
+
+The biggest change in this profile is that the profile creates a multi project gradle build. This is the first profile to have done so. The Angular profile relies on the https://github.com/angular/angular-cli[Angular CLI] to manage the client side application. The server side application is the same as an application created with the `rest-api` profile.
+
+To get started with the Angular profile, create an application specifying `angular` as the name of the profile:
+
+[source,bash]
+----
+$ grails create-app my-app --profile angular
+----
+
+This will create a `my-app` directory with the following contents:
+
+[source]
+----
+client/
+gradle/
+gradlew
+gradlew.bat
+server/
+settings.gradle
+----
+
+The entire client application lives in the `client` folder and the entire server application lives in the `server` folder.
+
+==== Prerequisites
+
+To use this profile, you should have Node, NPM, and the Angular CLI installed. Node should be at least version 5 and NPM should be at least version 3.
+
+* https://docs.npmjs.com/getting-started/installing-node[Node && NPM]
+* https://github.com/angular/angular-cli#installation[Angular CLI]
+
+==== Project Structure
+
+The Angular profile is designed to be used with the https://github.com/angular/angular-cli[Angular CLI]. The CLI was used to create the client application side of the profile to start with. The CLI provides commands to do most of the things you would want to do with the client application, including creating components or services. Because of that, the profile itself provides no commands to do those same things.
+
+==== Running The App
+
+To execute the server side application only, you can execute the `bootRun` task in the `server` project:
+
+[source,bash]
+----
+./gradlew server:bootRun
+----
+
+The same can be done for the client application:
+
+[source,bash]
+----
+./gradlew client:bootRun
+----
+
+To execute both, you must do so in parallel:
+
+[source,bash]
+----
+./gradlew bootRun --parallel
+----
+
+NOTE: It is necessary to do so in parallel because by default Gradle executes tasks synchronously, and neither of the `bootRun` tasks will "finish".
+
+==== Testing
+
+The default client application that comes with the profile provides some tests that can be executed. To execute tests in the application:
+
+[source,bash]
+----
+./gradlew test
+----
+
+The `test` task will execute unit tests with Karma and Jasmine.
+
+[source,bash]
+----
+./gradlew integrationTest
+----
+
+The `integrationTest` task will execute e2e tests with Protractor.
+
+TIP: You can execute the `test` and `integrationTest` tasks on each of the sub-projects the same as you would `bootRun`.
+
+==== CORS
+
+Because the client side and server side will be running on separate ports, CORS configuration is required. By default the profile will configure the server side to allow CORS from all hosts via the following config:
+
+[source,yaml]
+.server/grails-app/conf/application.yml
+----
+grails:
+    cors:
+        enabled: true
+----
+
+See the section on link:theWebLayer.html#cors[CORS] in the user guide for information on configuring this feature for your needs.

src/en/guide/REST/jsonViews/jsonViewsSetup.adoc

@@ -1,4 +1,4 @@
-If you are using the REST application, then the JSON views plugin will already be included and you can skip the remainder of this section. Otherwise you will need to modify your `build.gradle` to include the necessary plugin to activate JSON views:
+If you are using the REST application or REST or AngularJS profiles, then the JSON views plugin will already be included and you can skip the remainder of this section. Otherwise you will need to modify your `build.gradle` to include the necessary plugin to activate JSON views:
 
 [source,groovy]
 ----

src/en/guide/REST/restProfile.adoc

@@ -1,5 +1,36 @@
 Since Grails 3.1, Grails supports a tailored profile for creating REST applications that provides a more focused set of dependencies and commands.
 
+To get started with the REST profile, create an application specifying `rest-api` as the name of the profile:
+
+[source,bash]
+----
+$ grails create-app my-api --profile rest-api
+----
+
+This will create a new REST application that provides the following features:
+
+* Default set of commands for creating and generating REST endpoints
+* Defaults to using JSON views for rendering responses (see the next section)
+* Fewer plugins than the default Grails plugin (no GSP, no Asset Pipeline, nothing HTML related)
+
+You will notice for example in the `grails-app/views` directory that there are `*.gson` files for rendering the default index page and as well as any 404 and 500 errors.
+
+If you issue the following set of commands:
+
+[source,bash]
+----
+$ grails create-domain-class my.api.Book
+$ grails generate-all my.api.Book
+----
+
+Instead of CRUD HTML interface a REST endpoint is generated that produces JSON responses. In addition, the generated functional and unit tests by default test the REST endpoint.
+
+
+
+
+
+Using Grails Forge, Grails supports a tailored profile for creating REST applications that provides a more focused set of dependencies and commands.
+
 To get started with a REST API-type application:
 
 [source,console]

src/en/guide/commandLine.adoc

@@ -1,4 +1,110 @@
-The Grails New Command-Line Interface (CLI) has undergone significant changes compared to its previous versions, primarily focusing on code generation. One notable alteration is the removal of APIs for invoking Gradle for tasks related to building using Gradle Tooling APIs. This shift in responsibility aligns with the framework's evolution and its integration with the Gradle build system.
+Grails 3.0's command line system differs greatly from previous versions of Grails and features APIs for invoking Gradle for build related tasks, as well as performing code generation.
+
+When you type:
+
+[source,groovy]
+----
+grails <<command name>>
+----
+
+Grails searches the http://bintray.com/grails/profiles[profile repository] based on the profile of the current application. If the profile is for a web application then commands are read from the web profile and the base profile which it inherits from.
+
+Since command behavior is profile specific the web profile may provide different behavior for the `run-app` command then say a profile for running batch applications.
+
+When you type the following command:
+
+[source,groovy]
+----
+grails run-app
+----
+
+It will first search the application, and then the profile for commands:
+
+* `PROJECT_HOME/src/main/scripts/run-app.groovy`
+* `<<profile>>/commands/run-app.groovy`
+* `<<profile>>/commands/run-app.yml`
+
+To get a list of all commands and some help about the available commands type:
+
+[source,bash]
+----
+grails help
+----
+
+which outputs usage instructions and the list of commands Grails is aware of:
+
+[source,bash]
+----
+grails <<environment>>* <<target>> <<arguments>>*'
+
+| Examples:
+$ grails dev run-app
+$ grails create-app books
+
+| Available Commands (type grails help 'command-name' for more info):
+| Command Name                          Command Description
+----------------------------------------------------------------------------------------------------
+clean                                   Cleans a Grails application's compiled sources
+compile                                 Compiles a Grails application
+...
+----
+
+NOTE: Refer to the Command Line reference in the Quick Reference menu of the reference guide for more information about individual commands
+
+=== Arguments
+
+The `grails` command is a front to a `gradle` invocation, because of this there can be unexpected side-effects.
+For example, when executing `grails -Dapp.foo=bar run-app` the `app.foo` system property won't be available to your application. This is because `bootRun` in your `build.gradle` configures the system properties.
+To make this work you can simply append all `System.properties` to `bootRun` in `build.gradle` like:
+
+[source,groovy]
+----
+bootRun{
+    systemProperties System.properties // Please note not to use '=', because this will override all configured systemProperties. This will append them.
+}
+----
+
+Or if you only want to pass through a limited set, you can prefix your system properties using an arbitrary prefix and configure `bootRun` like:
+
+[source,groovy]
+----
+bootRun{
+    bootRun {
+        systemProperties System.properties.inject([:]){acc,item-> item.key.startsWith('boot.')?acc << [(item.key.substring('boot.'.length())):item.value]:acc }
+    }
+}
+----
+
+In this example only system properties starting with `boot.` are passed through.
+
+Application and JVM arguments should be specified in `bootRun` as well.
+
+[source,groovy]
+----
+bootRun{
+    bootRun {
+        jvmArgs('-Dspring.output.ansi.enabled=always')
+        args('--app.foo=bar','--app.bar=foo') // Override the `app.foo` and `app.bar` config options (`grailsApplication.config`)
+    }
+}
+----
+
+
+=== non-interactive mode
+
+
+When you run a script manually and it prompts you for information, you can answer the questions and continue running the script. But when you run a script as part of an automated process, for example a continuous integration build server, there's no way to "answer" the questions. So you can pass the `\--non-interactive` switch to the script command to tell Grails to accept the default answer for any questions, for example whether to install a missing plugin.
+
+For example:
+
+[source,groovy]
+----
+grails war --non-interactive
+----
+
+
+
+The Grails Forge New Command-Line Interface (CLI) has undergone significant changes compared to its previous versions, primarily focusing on code generation. One notable alteration is the removal of APIs for invoking Gradle for tasks related to building using Gradle Tooling APIs. This shift in responsibility aligns with the framework's evolution and its integration with the Gradle build system.
 
 === Accessing the Grails CLI