Initiate ref guide overhaul

See gh-392

initializr-docs/pom.xml

@@ -103,6 +103,7 @@
 										<docinfo>true</docinfo>
 										<spring-initializr-version>${project.version}</spring-initializr-version>
 										<spring-initializr-docs-version>${project.version}</spring-initializr-docs-version>
+										<spring-boot-docs-version>${spring.boot.version}</spring-boot-docs-version>
 										<snippets>${snippets.location}</snippets>
 										<github-tag>${github-tag}</github-tag>
 									</attributes>
@@ -192,25 +193,7 @@
 									</postProcess>
 								</configuration>
 							</execution>
-							<execution>
+							
-								<id>pdf</id>
-								<goals>
-									<goal>generate-pdf</goal>
-								</goals>
-								<phase>prepare-package</phase>
-								<configuration>
-									<foCustomization>${basedir}/src/main/docbook/xsl/pdf.xsl</foCustomization>
-									<targetDirectory>${basedir}/target/docbook/pdf</targetDirectory>
-									<postProcess>
-										<copy todir="${basedir}/target/contents/reference">
-											<fileset dir="${basedir}/target/docbook">
-												<include name="**/*.pdf" />
-											</fileset>
-										</copy>
-										<move file="${basedir}/target/contents/reference/pdf/index.pdf" tofile="${basedir}/target/contents/reference/pdf/initializr-reference.pdf" />
-									</postProcess>
-								</configuration>
-							</execution>
 							<execution>
 								<id>epub</id>
 								<goals>

initializr-docs/src/main/asciidoc/configuration-guide.adoc

@@ -0,0 +1,387 @@
+[[configuration-guide]]
+= Configuration Guide
+
+[partintro]
+--
+This section describes how you can create your own instance of the service and tune it for
+your needs. You'll also find some advanced tips to make sure the available options are
+consistent with the chosen Spring Boot generation.
+--
+
+
+
+[[create-instance]]
+== Creating your own instance
+Spring Initializr is split in three main modules:
+
+* `initializr-generator`: standalone project generation library that can be reused in
+many environments (including embedded in your own project)
+* `initializr-web`: REST endpoints and web interface
+* `initializr-actuator`: optional module to provide statistics and metrics on project
+generation
+
+Because it contains several auto-configurations, creating your own instance is quite easy,
+actually you could get started using Spring Initializr itself!
+
+Create a new project with the `web` dependency and add the following dependency:
+
+[source,xml,indent=0,subs="verbatim,attributes"]
+----
+	<dependency>
+		<groupId>io.spring.initializr</groupId>
+		<artifactId>initializr-web</artifactId>
+		<version>{spring-initializr-version}</version>
+	</dependency>
+----
+
+Or if you are using Gradle:
+
+[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
+----
+compile("io.spring.initializr:initializr-web:{spring-initializr-version}")
+----
+
+If you start the application, you'll see the familiar interface but none of the drop down
+lists have values (except the one for the Spring Boot version, we will
+<<create-instance-boot-versions,come back to that later>>). In the rest of this section,
+we will configure those basic settings.
+
+[TIP]
+====
+Most of the settings are configured via `application.properties` using the `initializr`
+namespace. Because the configuration is highly hierarchical, we recommend using the yaml
+format that is more readable for such structure. If you agree, go ahead and rename
+`application.properties` to `application.yml`.
+====
+
+
+
+[[create-instance-basic-settings]]
+=== Configuring basic settings
+Most of the drop-down lists are configured via a simple list-based structure where each
+entry has an `id`, a `name` and whether that entry is the default or not. If no `name` is
+provided, the `id` is used instead.
+
+Let's configure the languages and the Java versions we want to support:
+
+[source,yaml,indent=0]
+----
+	initializr:
+	  javaVersions:
+		- id: 9
+		  default: false
+		- id: 1.8
+		  default: true
+	  languages:
+		- name: Java
+		  id: java
+		  default: true
+		- name: Kotlin
+		  id: kotlin
+		  default: false
+----
+
+If you click on the "Switch to the full version" link, the two drop down lists now offer
+the options and default values defined above.
+
+Spring Initializr supports `java`, `groovy` and `kotlin` and additional languages can be
+added in your own customization.
+
+The available packagings are also configurable that way:
+
+[source,yaml,indent=0]
+----
+	initializr:
+	  packagings:
+		- name: Jar
+		  id: jar
+		  default: true
+		- name: War
+		  id: war
+		  default: false
+----
+
+These two packaging types are the only one explicitly supported at the moment.
+
+
+
+[[create-instance-boot-versions]]
+=== Configuring available Spring Boot versions
+If you look at http://projects.spring.io/spring-boot[the project home page for Spring
+Boot], the latest versions are displayed. And you've probably noticed that they match
+the drop down list that you automatically get with a default instance. The reason for that
+is that Spring Initializr requests an API on spring.io to retrieve the latest versions
+automatically. This makes sure that you always get the latest available versions.
+
+If that's not what you want, you need to override the `InitializrMetadataProvider` bean
+that is responsible to provide the metadata of the service. For instance, you could swap
+to an implementation that always returns the content of your configuration file:
+
+[source,java,indent=0]
+----
+	@Bean
+	public InitializrMetadataProvider initializrMetadataProvider(
+			InitializrProperties properties) {
+		InitializrMetadata metadata = InitializrMetadataBuilder
+				.fromInitializrProperties(properties).build();
+		return new SimpleInitializrMetadataProvider(metadata);
+	}
+----
+
+The thing to remember is that, by default, you don't have to worry about upgrading your
+instance when a new Spring Boot version is released. However, you may need to
+<<create-instance-advanced-config-caching,configure caching>> to avoid requesting that
+service too often.
+
+
+
+[[create-instance-types]]
+=== Configuring available project types
+The available project types mostly define the structure of the generated project and its
+build system. Once a project type is selected, the related action is invoked to generate
+the project.
+
+By default, Spring Initializr exposes the following actions:
+
+* `/pom.xml` generate a Maven `pom.xml`
+* `/build.gradle` generate a Gradle build
+* `/starter.zip` generate a complete project structure archived in a zip
+* `/starter.tgz` generate a complete project structure archived in a tgz
+
+Each type also defines one or more *tags*, that is additional metadata entries to qualify
+the entry. The following standard tags exist:
+
+* `build`: the name of the build system to use (e.g. `maven`, `gradle`)
+* `format`: the format of the project (e.g. `project` for a full project, `build` for just
+a build file).
+
+By default, the HTML UI filters all the available types to only display the ones that have
+a `format` tag with value `project`.
+
+You can of course implement additional endpoints that generate whatever project structure
+you need but, for now, we'll simply configure our instance to generate a Gradle or a Maven
+project:
+
+[source,yaml,indent=0]
+----
+	initializr:
+	  types:
+		- name: Maven Project
+		  id: maven-project
+		  description: Generate a Maven based project archive
+		  tags:
+			build: maven
+			format: project
+		  default: true
+		  action: /starter.zip
+		- name: Gradle Project
+		  id: gradle-project
+		  description: Generate a Gradle based project archive
+		  tags:
+			build: gradle
+			format: project
+		  default: false
+		  action: /starter.zip
+----
+
+NOTE: If you intend to build a custom client against your service, you can add as
+many tags as you want.
+
+The spring boot CLI uses them as a shortcut to the full id. So rather than having to
+create a Gradle project as follows:
+
+[indent=0,subs="verbatim,quotes,attributes"]
+----
+	$ spring init --type=gradle-project my-project.zip
+----
+
+You can simply define a more convenient build parameter:
+
+[indent=0,subs="verbatim,quotes,attributes"]
+----
+	$ spring init --build=gradle my-project.zip
+----
+
+
+With that configuration, you should be able to generate your first project,
+congratulations! Let's now add dependencies so that you can start searching for them.
+
+
+
+[[create-instance-dependencies]]
+=== Configuring dependencies
+The most basic `dependency` is composed of:
+
+* An `id` used in clients to refer to it
+* The full maven coordinates of the dependency (`groupId` and `artifactId`)
+* A display `name` (used in the UI and the search results)
+* A `description` can (and should) be added to provide more information about the
+dependency
+
+Spring Initializr automatically considers that a dependency without maven coordinates
+defines an official Spring Boot starter. In such a case, the `id` is used to infer the
+`artifactId`.
+
+For instance, the following configures the `spring-boot-starter-web` Starter:
+
+[source,yaml,indent=0]
+----
+	initializr:
+	  dependencies:
+		- name: Web
+		  content:
+			- name: Web
+			  id: web
+			  description: Full-stack web development with Tomcat and Spring MVC
+----
+
+Each dependency is contained in a _group_ that gathers dependencies sharing a common
+surface area or any other form of grouping. In the example above, a `Web` group holds our
+unique dependency. A group can also provide default values for various settings, see the
+<<howto-group-share-settings,dedicated how-to>> for more details.
+
+In our `spring-boot-starter-web` example above, the dependency is _managed_ by Spring
+Boot so there is no need to provide a `version` attribute for it. You'll surely need to
+define additional dependencies that are not provided by Spring Boot and we strongly
+recommend you to use a <<create-instance-boms,Bill Of Materials (or BOM)>>.
+
+If no BOM is available you can specify a version directly:
+
+[source,yaml,indent=0]
+----
+	initializr:
+	  dependencies:
+		- name: Tech
+		  content:
+			- name: Acme
+			  id: acme
+			  groupId: com.example.acme
+			  artifactId: acme
+			  version: 1.2.0.RELEASE
+			  description: A solid description for this dependency
+----
+
+If you add this configuration and search for "acme" (or "solid"), you'll find this extra
+entry; generating a maven project with it should add the following to the pom
+
+[source,xml,indent=0,subs="verbatim"]
+----
+	<dependency>
+		<groupId>com.example.acme</groupId>
+		<artifactId>acme</artifactId>
+		<version>1.2.0.RELEASE</version>
+	</dependency>
+----
+
+The rest of this section will detail the other configuration options.
+
+
+[[dependencies-version-range]]
+==== Availability (version range)
+
+
+[[dependencies-mappings]]
+==== Map coordinates according to the Spring Boot version
+
+
+[[dependencies-alias]]
+==== Aliases
+
+
+[[dependencies-repository]]
+==== Repository
+
+If the dependency is not available on Maven Central (or whatever default repository that
+is configured on your end), you can also add a <<dependencies-repository,reference to a
+repository>>.
+
+
+[[dependencies-facet]]
+==== Facets
+
+[[create-instance-dependencies-link]]
+==== Links
+
+
+[[create-instance-dependencies-search]]
+==== Improve search results
+
+Weight + keywords
+
+
+[[create-instance-repositories]]
+=== Configuring Repositories
+
+
+[[create-instance-boms]]
+=== Configuring Bill of Materials
+
+
+[[configuration-howto]]
+== '`How-to`' guides
+
+This section provides answers to some common '`how do I do that...`' type of questions
+that often arise when configuring Spring Initializr.
+
+[[howto-dependency-starter-flag]]
+=== Make sure a regular dependency brings the base starter
+
+[[howto-group-share-settings]]
+=== Share common dependency settings in a group
+
+
+[[create-instance-advanced-config]]
+== Advanced configuration
+
+
+
+[[create-instance-advanced-config-caching]]
+=== Caching configuration
+If you use the service, you'll notice that the logs have lots of entries with the message
+`Fetching boot metadata from https://spring.io/project_metadata/spring-boot`. To avoid
+checking for the latest Spring Boot versions too often, you should enable caching on your
+service. Spring Initializr has some auto-configuration to apply the proper caches if you
+are willing to use a JCache (JSR-107) implementation.
+
+Add the `javax.cache:cache-api` and your favorite JCache implementation and simply enable
+caching by adding `@EnableCaching` to your `@SpringBootApplication`. For instance, you
+could use `ehcache` by adding the following:
+
+[source,xml,indent=0,subs="verbatim,attributes"]
+----
+	<dependency>
+		<groupId>javax.cache</groupId>
+		<artifactId>cache-api</artifactId>
+	</dependency>
+	<dependency>
+		<groupId>org.ehcache</groupId>
+		<artifactId>ehcache</artifactId>
+	</dependency>
+----
+
+Or if you are using Gradle:
+
+[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
+----
+compile("javax.cache:cache-api")
+compile("org.ehcache:ehcache")
+----
+
+You'll notice that the log entry is much more rare. If you do not want to use JSR-107, you
+should configure the cache yourselves:
+
+.Cache configuration
+|===
+| cache name | Description
+
+|`initializr`
+|Cache the full metadata of the service. When the metadata expires, it is fully resolved
+again (including a check on spring.io for the latest Spring Boot versions). Adapt the
+expiration settings accordingly.
+
+|`project-resources`
+|Cache resources that are used to generate projects.
+
+|`dependency-metadata`
+|Cache dependency-specific metadata.
+|===

initializr-docs/src/main/asciidoc/documentation-overview.adoc

@@ -1,19 +1,32 @@
-[[boot-documentation]]
+[[initializr-documentation]]
 = Spring Initializr Documentation
 
-Spring Initializr provides an extensible API to generate quickstart projects. It also
+[partintro]
-provides a configurable service: you can see our default instance at
+--
-https://start.spring.io. It provides a simple web UI to configure the project to
+This section provides a brief overview of Spring Initializr reference documentation. Think
-generate and endpoints that you can use via plain HTTP.
+of it as map for the rest of the document. Some sections are targeted to a specific
+audience so this reference guide is not meant to be read in a linear fashion.
+--
 
-Spring Initializr also exposes an endpoint that serves its metadata in a
+Spring Initializr provides an extensible API to generate quickstart projects. Such an API
-<<metadata-format.adoc#metadata-format,well-known format>> to allow third-party
+can be used standalone or embedded in other tools. We also provide a configurable service:
-clients to provide the necessary assistance.
+you can see our default instance at https://start.spring.io. It provides a simple web UI
+to configure the project to generate and endpoints that you can use via plain HTTP.
 
-Finally, Initializr offers a <<configuration-format.adoc#configuration-format,
+The service allows you to customize the project to generate: the build system and its
-configuration structure>> to define all the aspects related to the project to
+coordinates, the language and version, the packaging and finally the dependencies to add
-generate: list of dependencies, supported java and boot versions, etc.
+the project. The latter is a core concept: based on the chosen Spring Boot version, a set
+of dependencies can be chosen, usually Spring Boot starters, that will have a concrete
+impact on your application. More details in the <<user-guide.adoc#user-guide>>.
 
+You can easily create your own instance: there is minimal code involved and the service
+has a very rich configuration structure, allowing you to define not only the values of
+various project attributes but also the list of dependencies and the constraints to apply
+to them.
+
+Spring Initializr also exposes an endpoint that serves its metadata in a well-known format
+to allow third-party clients to provide the necessary assistance. Currently, all the major
+Java IDEs are covered and you can generate a project right from your favourite IDE.
 
 
 [[initializr-documentation-about]]

initializr-docs/src/main/asciidoc/index.adoc

@@ -19,13 +19,11 @@ Stéphane Nicoll; Dave Syer
 :spring-initializr-docs-version: current
 :spring-initializr-docs: http://docs.spring.io/initializr/docs/{spring-initializr-docs-version}/reference
 :spring-initializr-docs-current: http://docs.spring.io/initializr/docs/current/reference
-
+:spring-boot-reference: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/reference/htmlsingle
 
 // ======================================================================================
 
-include::documentation-overview.adoc[leveloffset=+1]
+include::documentation-overview.adoc[]
-include::metadata-format.adoc[leveloffset=+1]
+include::user-guide.adoc[]
-include::using-the-stubs.adoc[leveloffset=+1]
+include::configuration-guide.adoc[]
-include::configuration-format.adoc[leveloffset=+1]
-
 // ======================================================================================

initializr-docs/src/main/asciidoc/user-guide.adoc

@@ -0,0 +1,226 @@
+[[user-guide]]
+= User Guide
+
+[partintro]
+--
+If you're wondering how to use https://start.spring.io or what features are available,
+this section is for you! You'll find the various way you can interact with the service and
+get a better insight at what you can do with it.
+--
+
+
+
+[[getting-started]]
+== Getting Started
+Let's create a first project and discover the various options that you can use to tune it.
+Go to https://start.spring.io, change the `Group` field from "com.example" to "org.acme"
+and put the focus in the `Dependencies` field on the right hand side. If you type "web",
+you will see a list of matching choices with that simple criteria. Use the mouse or the
+arrow keys and `Enter` to select the "Web" starter.
+
+Your browser should now be in this state:
+
+TODO: add screenshot
+
+NOTE: The Spring Boot version above probably doesn't match the one you have. As we will
+see later, start.spring.io is continuously updated as new Spring Boot versions are
+published and the service uses the latest version by default.
+
+Click on `Generate Project`, this downloads a zip file containing a Maven project with
+the following structure:
+
+```
+mvnw
+mvnw.cmd
+pom.xml
+src
+├── main
+│   ├── java
+│   │   └── org
+│   │       └── acme
+│   │           └── DemoApplication.java
+│   └── resources
+│       ├── application.properties
+│       ├── static
+│       └── templates
+└── test
+    └── java
+        └── org
+            └── acme
+                └── DemoApplicationTests.java
+```
+
+A typical project generated by Spring Initializr contains a Spring Boot application
+(`DemoApplication`), a test and an empty configuration. If you run the `main` method
+of `DemoApplication`, you'll see an "empty" spring boot app starting on localhost:8080.
+
+Because Spring Initializr has detected it is a web application, a `static` and `templates`
+directories have been created to hold your static resources and ui templates.
+
+Also, a Maven wrapper is automatically included so that you don't have to install Maven to
+run this project. You can select Gradle instead in first drop down list. This will
+generate a Gradle-based project instead that also contains a wrapper if you don't have
+Gradle installed.
+
+
+
+[[getting-started-advanced-options]]
+=== Advanced options
+Next to the `Generate Project` you'll find a "Switch to the full version" link. If you
+click on that, you'll see all the available options. Let's browse through them quickly:
+
+* *Group*: project coordinates (id of the project's group, as referred by the `groupId`
+attribute in Apache Maven). Also infers the root package name to use.
+* *Artifact*: project coordinates (id of the artifact, as referred by the `artifactId`
+attribute in Apache Maven). Also infers the name of the project
+* *Name*: display name of the project that also determines the name of your Spring Boot
+application. For instance, if the name of your project is `my-app`, the generated project
+will have a `MyAppApplication` class
+* *Description*: description of the project
+* *Package Name*: root package of the project. If not specified, the value of the *Group*
+attribute is used
+* *Packaging*: project packaging (as referred by the concept of the same name in Apache
+Maven). start.spring.io can generate jar or war projects
+* *Java Version*: the Java version to use
+* *Language*: the programming language to use
+
+If you keep on scrolling, you'll discover all the dependencies that you can find using the
+search box on the right. You'll probably notice that some dependencies aren't available
+because they require a specific Spring Boot version. We'll tackle that in the next
+section.
+
+
+
+[[getting-started-dependencies]]
+=== Dependencies
+The UI allows you to select the Spring Boot version you want to use. You may want to be
+conservative and keep the default which corresponds at all times to the latest stable
+release. Or you may want to chose a milestone of the next major version. Either way,
+you'll notice that certain dependencies become available and others aren't anymore when
+you change the version.
+
+If you are searching for a dependency that you know to be available and you get no result,
+it's worth looking in the advanced section if that dependency is available in the Spring
+Boot version that is currently selected.
+
+You may find it is not the case with a message that looks like the following:
+
+```
+requires Spring Boot >=1.0.0.RELEASE and <1.5.0.RC1
+```
+
+Concretely, this defines a "version range" that states the dependency is deprecated and is
+no longer available as of Spring Boot 1.5. You may want to check the release notes of the
+related project to understand what your migration path can be. Alternatively, the message
+could be:
+
+```
+requires Spring Boot >=2.0.0.RELEASE
+```
+
+That version range means the dependency is not available with the current Spring Boot
+generation. Obviously, if you select Spring Boot 2.0 (or later if available), you'll be
+able to select that dependency.
+
+
+
+[[getting-started-tuning-defaults]]
+=== Tuning default values
+The Initializr service is configured to offer default values so that you can generate a
+new project with minimum fuss. Maybe you are a Kotlin fan? Or a Gradle fan? Currently
+start.spring.io defaults to Java and Maven but it also allows you to tune these defaults
+easily.
+
+You can share or bookmark URLs that will automatically customize form inputs. For
+instance, the following URL changes the default to use Kotlin and Gradle:
+
+```
+https://start.spring.io/#!language=kotlin&type=gradle-project
+```
+
+TIP: `type` is the attribute of the first drop-down list where the type of project can
+be selected and `gradle-project` is the id for the Gradle option. As you may guess,
+`maven-project` is the id of the default (Maven) option.
+
+
+
+[[command-line]]
+== Command line support
+You can also generate a project in a shell using `cURL` or `HTTPie`. To discover the
+available options of a particular instance, simply "curl it", i.e. if you have `curl`
+installed invoke `curl start.spring.io` on the command-line (or alternatively
+`http start.spring.io` if you prefer to use `HTTPie`).
+
+This provides a textual representation of the capabilities of the service that are split
+in three sections:
+
+First, a table that describes the available project's types. On the default instance,
+you'll find the `maven-project` and `gradle-project` we've discussed above but you'll
+also be able to generate only a build script rather than an entire project.
+
+Then, a table that describes the available parameters. For the most part, these are the
+same options as the ones available in the web UI. There are, however, a few additional
+ones:
+
+* `applicationName` can be used to define the name of the application, disabling the
+algorithm that infer it based on the `name` parameter
+* `baseDir` can be used to create a base directory in the archive so that you can extract
+the generated zip without creating a directory for it first
+
+Finally, the list of dependencies are defined. Each entry provides the identifier that
+you'll have to use if you want to select the dependency, a description and the Spring Boot
+version range, if any.
+
+Alongside the capabilities of the service, you'll also find a few examples that help you
+understand how you can generate a project. These are obviously tailored to the client that
+you are using.
+
+Let's assume that you want to generate a "my-project.zip" project based on Spring Boot
+`1.5.2.RELEASE`, using the `web` and `devtools` dependencies (remember, those two ids are
+displayed in the capabilities of the service):
+
+```
+$ curl https://start.spring.io/starter.zip -d dependencies=web,devtools \
+           -d bootVersion=1.5.2.RELEASE -o my-project.zip
+```
+
+If you extract `my-project.zip`, you'll notice a few differences compared to what happens
+with the web UI:
+
+* The project will be extracted in the current directory (the web UI adds a base directory
+automatically with the same name as the one of the project)
+* The name of the project is not `my-project` (the `-o` parameter has no incidence on the
+name of the project)
+
+The exact same project can be generated using the `http` command as well:
+
+```
+$ http https://start.spring.io/starter.zip dependencies==web,devtools \
+           bootVersion==1.5.1.RELEASE -d
+```
+
+NOTE: `HTTPie` reads the same hint as the browser so it will store a `demo.zip` file in
+the current directory, with the same differences discussed above.
+
+
+
+[[ide]]
+== IDEs support
+Spring Initializr is also integrated in all major Java IDEs and allows you to create and
+import a new project without having to leave the IDE for the command-line or the web UI.
+
+The following IDEs have dedicated support:
+* Eclipse/STS
+* IntelliJ IDEA (Ultimate Edition)
+* NetBeans (using the
+
+Refer to the documentation of your favorite IDE for more details.
+
+
+
+[[spring-boot-cli]]
+== Spring Boot CLI support
+The `spring` command line tool defines an `init` command that allows you to create a
+project using Spring Initializr.
+
+Check {spring-boot-reference}/#cli-init[the documentation for more details].