From bb53c49a85510782dcb69cebefcb178057d8a450 Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Tue, 11 Apr 2017 10:07:00 +0100 Subject: [PATCH] Fix levels and include basic content for API and howto --- .../src/main/asciidoc/api-guide.adoc | 6 +++ .../main/asciidoc/configuration-guide.adoc | 21 +++++++-- .../main/asciidoc/documentation-overview.adoc | 45 ++++++++++--------- initializr-docs/src/main/asciidoc/index.adoc | 7 +-- 4 files changed, 51 insertions(+), 28 deletions(-) create mode 100644 initializr-docs/src/main/asciidoc/api-guide.adoc diff --git a/initializr-docs/src/main/asciidoc/api-guide.adoc b/initializr-docs/src/main/asciidoc/api-guide.adoc new file mode 100644 index 00000000..418698ab --- /dev/null +++ b/initializr-docs/src/main/asciidoc/api-guide.adoc @@ -0,0 +1,6 @@ +[[api-guide]] += API Guide + +include::metadata-format.adoc[leveloffset=+1] + +include::using-the-stubs.adoc[leveloffset=+1] diff --git a/initializr-docs/src/main/asciidoc/configuration-guide.adoc b/initializr-docs/src/main/asciidoc/configuration-guide.adoc index 0b313f4a..482461fd 100644 --- a/initializr-docs/src/main/asciidoc/configuration-guide.adoc +++ b/initializr-docs/src/main/asciidoc/configuration-guide.adoc @@ -12,16 +12,16 @@ consistent with the chosen Spring Boot generation. [[create-instance]] == Creating your own instance -Spring Initializr is split in three main modules: +Spring Initializr is split across 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-web`: API 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! +actually you could get started using Spring Initializr itself to generate a starting point! Create a new project with the `web` dependency and add the following dependency: @@ -323,6 +323,18 @@ Weight + keywords This section provides answers to some common '`how do I do that...`' type of questions that often arise when configuring Spring Initializr. +[[howto-add-a-new-checkbox]] +=== Add a new dependency checkbox + +[[howto-override-a-version]] +=== Override the version of a dependency + +[[howto-link-boot-version]] +=== Link a Boot version to a version of your dependency + +[[howto-add-snapshot-repository]] +=== Configure a snapshot repository + [[howto-dependency-starter-flag]] === Make sure a regular dependency brings the base starter @@ -368,7 +380,8 @@ 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: +should configure the cache yourselves. Here are the caches used by the application (each +one will require some configuration to get it working): .Cache configuration |=== diff --git a/initializr-docs/src/main/asciidoc/documentation-overview.adoc b/initializr-docs/src/main/asciidoc/documentation-overview.adoc index b4107eae..262e86d6 100644 --- a/initializr-docs/src/main/asciidoc/documentation-overview.adoc +++ b/initializr-docs/src/main/asciidoc/documentation-overview.adoc @@ -8,33 +8,36 @@ of it as map for the rest of the document. Some sections are targeted to a speci audience so this reference guide is not meant to be read in a linear fashion. -- -Spring Initializr provides an extensible API to generate quickstart projects. Such an API -can be used standalone or embedded in other tools. We also provide 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 generate and endpoints that you can use via plain HTTP. +Spring Initializr provides a simple web UI to configure the project to generate and +endpoints that you can use via plain HTTP: you can see our default instance at +https://start.spring.io. The service allows you to customize the project to generate: the +build system and its coordinates, the language and version, the packaging and finally the +dependencies to add to 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 +<> section. -The service allows you to customize the project to generate: the build system and its -coordinates, the language and version, the packaging and finally the dependencies to add -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 <>. - -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. +You can easily create your own instance of the Initializr, by using the jars as libraries +in your own app. 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. If that +sounds interesting, then the <> section has +all the details you need. You might only want to modify an existing instance of the +Initializr, e.g. to add a new dependency type, or update the version of an existing +one. For those and other simple and common use cases check out the +<> section. +The Initializr also provides an extensible API to generate quickstart projects, and to +inspect the metadata used to generate projects, for instance to list the available +dependencies and versions. The API can be used standalone or embedded in other tools +(e.g. it is used in Spring Tool Suite, and in the IntelliJ and Netbeans plugins for Spring +Boot). These features are covered in a separate <> section of +this document. [[initializr-documentation-about]] == About the documentation The Spring Initializr reference guide is available as -{spring-initializr-docs}/html[html], -{spring-initializr-docs}/pdf/spring-boot-reference.pdf[pdf] -and {spring-initializr-docs}/epub/spring-boot-reference.epub[epub] documents. The +{spring-initializr-docs}/html[html]. The latest copy is available at {spring-initializr-docs-current}. Copies of this document may be made for your own use and for diff --git a/initializr-docs/src/main/asciidoc/index.adoc b/initializr-docs/src/main/asciidoc/index.adoc index 2c07fe01..4184ca06 100644 --- a/initializr-docs/src/main/asciidoc/index.adoc +++ b/initializr-docs/src/main/asciidoc/index.adoc @@ -23,7 +23,8 @@ Stéphane Nicoll; Dave Syer // ====================================================================================== -include::documentation-overview.adoc[] -include::user-guide.adoc[] -include::configuration-guide.adoc[] +include::documentation-overview.adoc[leveloffset=+1] +include::user-guide.adoc[leveloffset=+1] +include::configuration-guide.adoc[leveloffset=+1] +include::api-guide.adoc[leveloffset=+1] // ======================================================================================