Merge pull request #131 from gradle/sg/init-docs

Add some content for build init

docs/getting-started/samples.md

@@ -5,6 +5,7 @@
 
 All samples in this page can be used to demonstrate features made possible by Declarative Gradle.
 
+- [Generate a new build with `gradle init`](../reference/build-init.md)
 - [Java Application](#java-application)
 - [Kotlin Application](#kotlin-application)
 - [Android Application](#android-application)
@@ -19,33 +20,31 @@ After picking a sample, read about new [Declarative Gradle features](./features.
 
 A sample Java application written in the Declarative Gradle DSL, using the prototype Declarative Gradle `javaApplication` Software Type defined in the `org.gradle.experimental.jvm-ecosystem` ecosystem plugin.
 
-Please follow the README available at [github.com/gradle/declarative-samples-java-app](https://github.com/gradle/declarative-samples-java-app) to try this sample.
+Please follow the README available at [gradle/declarative-samples-java-app](https://github.com/gradle/declarative-samples-java-app) to try this sample.
 
 ## Kotlin Application
 
 A sample Kotlin application written in the Declarative Gradle DSL, using the prototype Declarative Gradle `kotlinJvmApplication` Software Type defined in the `org.gradle.experimental.kmp-ecosystem` ecosystem plugin.
 
-Please follow the README available at  [github.com/gradle/declarative-samples-kotlin-app](https://github.com/gradle/declarative-samples-kotlin-app) to try this sample.
+Please follow the README available at [gradle/declarative-samples-kotlin-app](https://github.com/gradle/declarative-samples-kotlin-app) to try this sample.
 
 ## Android Application
 
 A sample Android application written in the Declarative Gradle DSL, using the prototype Declarative Gradle `androidApplication` Software Type defined in the `org.gradle.experimental.android-ecosystem` ecosystem plugin.
 
-Please follow the README available at  [github.com/gradle/declarative-samples-android-app](https://github.com/gradle/declarative-samples-android-app) to try this sample.
+Please follow the README available at [gradle/declarative-samples-android-app](https://github.com/gradle/declarative-samples-android-app) to try this sample.
 
 ## Now In Android
 
 [Now in Android](https://github.com/android/nowinandroid) is a fully functional Android app built entirely with Kotlin and Jetpack Compose from the Android team.
 We forked _Now in Android_ and updated the build to work with Declarative Gradle.
-The prototype repository can be found in [github.com/gradle/nowinandroid](https://github.com/gradle/nowinandroid).
+The prototype repository can be found in [gradle/nowinandroid](https://github.com/gradle/nowinandroid).
 
-Please follow the README available at [github.com/gradle/nowinandroid/DECLARATIVE-README.md](https://github.com/gradle/nowinandroid/blob/main-declarative/DECLARATIVE-README.md) to try this sample.
+Please follow the [README](https://github.com/gradle/nowinandroid/blob/main-declarative/DECLARATIVE-README.md) to try this sample.
 
 ## Bleeding edge prototypes
 
-If you want to go further you can take a look at some more projects for JVM, Android, KMP, Swift and C++ projects. These projects may use newer versions of Gradle or require additional manual setup, so you should try the other samples first. 
-
-They are available at [github.com/gradle/declarative-gradle/tree/main/unified-prototype](https://github.com/gradle/declarative-gradle/tree/main/unified-prototype).
+If you want to go further you can take a look at some more projects for JVM, Android, KMP, Swift and C++ projects. [These projects](https://github.com/gradle/declarative-gradle/tree/main/unified-prototype) may use newer versions of Gradle or require additional manual setup, so you should try the other samples first. 
 
 Please follow the README available in each directory linked below to try these samples.
 

docs/reference/README.md

@@ -1,4 +1,4 @@
 # Declarative Gradle - Documentation
 
+* [`gradle init`](./build-init.md) - generate new builds using software types and DCL files
 * [Software Features](./software-features.md) - configuration model used by software developers
-* [`gradle init`](./build-init.md) - generate new projects using software types and DCL files

docs/reference/build-init.md

@@ -1,3 +1,42 @@
-# `gradle init` 
+# Generating new builds with `gradle init` 
 
-TODO
+Gradle supports generating new builds using [`gradle init`](https://docs.gradle.org/current/userguide/build_init_plugin.html). 
+
+To make it easier to try Declarative Gradle with new samples, our prototypes have changed `gradle init` to generate samples that use declarative configuration language (DCL) files and software types.
+
+An experimental system property has been added to Gradle to add new things that `gradle init` can generate. The value of the system property is a comma-separated list of plugins published to the [Gradle Plugin Portal](https://plugins.gradle.org/).
+
+Example: `gradle init -Dorg.gradle.buildinit.specs=<plugin-id-1:version>,<plugin-id-2:version>`
+
+!!! tip
+    This feature is only supported with nightlies of Gradle 8.12 created after October 24, 2024. 
+
+    If you have the correct version of Gradle, you'll be asked a new question:
+
+    Additional project types were loaded.  Do you want to generate a project using a contributed project specification?
+
+    Answer 'yes' (the default) to generate new Declarative Gradle builds.
+
+# Supported project types
+
+## Android 
+
+`gradle init -Dorg.gradle.buildinit.specs=org.gradle.experimental.android-ecosystem-init:0.1.23`
+
+There are three build samples you can choose from.
+
+By default, this generates a project like [gradle/declarative-samples-android-app](https://github.com/gradle/declarative-samples-android-app).
+
+You can also generate a single Android application build with an empty Activity or basic Activity.
+
+## Java 
+
+`gradle init -Dorg.gradle.buildinit.specs=org.gradle.experimental.jvm-ecosystem-init:0.1.23`
+
+This init sample asks no questions and generates a project using Java like [gradle/declarative-samples-java-app](https://github.com/gradle/declarative-samples-java-app).
+
+## Kotlin 
+
+`gradle init -Dorg.gradle.buildinit.specs=org.gradle.experimental.kmp-ecosystem-init:0.1.23`
+
+This init sample asks no questions and generates a project using Kotlin like [gradle/declarative-samples-kotlin-app](https://github.com/gradle/declarative-samples-kotlin-app).

mkdocs.yml

@@ -91,8 +91,9 @@ nav:
     - Features: docs/getting-started/features.md
   - Documentation:
     - Overview: docs/reference/README.md
-    - Roadmap: docs/ROADMAP.md
+    - Generate new builds: docs/reference/build-init.md
     - Software Features: docs/reference/software-features.md
+    - Roadmap: docs/ROADMAP.md
   - Resources:
     - Publications: docs/publications/README.md
     - Contributing: docs/CONTRIBUTING.md