improve docs

Author: martinbonnin

docs/src/content/docs/index.mdx

@@ -8,7 +8,7 @@ Nmcp (New Maven Central Publishing) is a plugin that uses the new [Central Porta
 
 Nmcp is compatible with modern Gradle development practices:
 * Compatible with [Configuration Cache](https://docs.gradle.org/current/userguide/configuration_cache_enabling.html).
-* Compatible with [Isolated project](https://docs.gradle.org/current/userguide/isolated_projects.html).
+* Compatible with [Isolated projects](https://docs.gradle.org/current/userguide/isolated_projects.html).
 * Compatible with [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html).
 * Uses [classloader isolation](https://mbonnin.net/2025-08-24_isolation_101/) to prevent conflicts with other plugins.
 * Uses [Gradle 8.8 lifecycle callbacks ](https://docs.gradle.org/8.8/release-notes.html) for easy configuration.
@@ -21,9 +21,7 @@ For a higher level API use [vanniktech/gradle-maven-publish-plugin](https://gith
 
 ### Requirements
 
-Nmcp requires Java 17+, Gradle 8.8+ for the settings plugin and Gradle 8.2+ otherwise.
-
-
+Nmcp requires Java 17+, Gradle 8.2+ and Gradle 8.8+ for the settings plugin.
 
 ### Configuring the settings plugin
 
@@ -64,15 +62,15 @@ Call `publishAggregationToCentralPortal` to publish the aggregation:
 
 ```bash
 ./gradlew publishAggregationToCentralPortal
-# yay everything is uploaded 🎉
-# go to https://central.sonatype.com/ to release if you used USER_MANAGED
+# Your deployment is uploaded
+# go to https://central.sonatype.com/ to release it if you used USER_MANAGED
 ```
 
-Call `publishAggregationToCentralPortalSnapshots` to publish to the snapshots:
+Call `publishAggregationToCentralSnapshots` to publish to the snapshots:
 
 ```bash
-./gradlew publishAggregationToCentralPortalSnapshots
-# yay everything is uploaded to "https://central.sonatype.com/repository/maven-snapshots/" 🎉
+./gradlew publishAggregationToCentralSnapshots
+# Your snapshots are uploaded to "https://central.sonatype.com/repository/maven-snapshots/"
 ```
 
 Under the hood, the `com.gradle.nmcp.settings` plugin applies the `com.gradleup.nmcp` plugin to all your projects and `com.gradleup.nmcp.aggregation` to your root project.

docs/src/content/docs/manual-configuration.mdx

@@ -4,7 +4,7 @@ title: Manual configuration
 
 import { Aside } from '@astrojs/starlight/components';
 
-For simple projects, the [settings plugin](/nmcp) is recommended.
+For simple projects, the [settings plugin](/nmcp#configuring-the-settings-plugin) is recommended.
 
 For more control, you can configure the `com.gradleup.nmcp.aggregation` and `com.gradleup.nmcp` plugins manually as described in this page.
 
@@ -60,7 +60,7 @@ nmcpAggregation {
 
 ```
 
-_Note that you may also apply both `com.gradleup.nmcp.aggregation` and `com.gradleup.nmcp` in the same project._
+_Note that you may apply both `com.gradleup.nmcp.aggregation` and `com.gradleup.nmcp` in the same project._
 
 For the aggregation to find the outgoing variant, you need to add the `nmcpAggregation` dependency for each project that you want to publish:
 
@@ -74,18 +74,17 @@ dependencies {
 }
 ```
 
-`com.gradleup.nmcp.aggregation` uses a lenient configuration to collect all the project. You may declare a dependency on all projects and the ones that do not apply `com.gradleup.nmcp` _should_ be ignored:
+`com.gradleup.nmcp.aggregation` uses a lenient configuration to collect files. You may add all projects and projects that do not apply `com.gradleup.nmcp` are ignored:
 
 ```kotlin
 // build.gradle.kts
 dependencies {
   /**
-   * You may also do this
+   * Add all projects to the `nmcpAggregation` dependency. Projets that do not
+   * apply `com.gradleup.nmcp` are ignored.
    *
-   * This is a bit more dangerous as it relies on the fact that
-   * the resolution is lenient.
-   * If you find unexpected content in your publications or bump
-   * into resolution errors, list all projects explicitly.
+   * Note: if you are using isolated projects, this potentially "over" configures
+   * your build by configuring projects that are not important for publishing.
    */
   allprojects {
     nmcpAggregation(project(path))
@@ -101,9 +100,9 @@ Call `publishAggregationToCentralPortal` to publish the aggregation:
 # go to https://central.sonatype.com/ to release if you used USER_MANAGED
 ```
 
-Call `publishAggregationToCentralPortalSnapshots` to publish to the snapshots:
+Call `publishAggregationToCentralSnapshots` to publish to the snapshots:
 
 ```bash
-./gradlew publishAggregationToCentralPortalSnapshots
-# yay everything is uploaded to "https://central.sonatype.com/repository/maven-snapshots/" 🎉
+./gradlew publishAggregationToCentralSnapshots
+# Your snapshots are uploaded to "https://central.sonatype.com/repository/maven-snapshots/"
 ```

nmcp/src/main/kotlin/nmcp/NmcpAggregationExtension.kt

@@ -6,10 +6,6 @@ import org.gradle.api.file.FileCollection
 interface NmcpAggregationExtension {
     /**
      * Configures publishing to central portal releases (Maven Central) and central portal snapshots.
-     *
-     * Adds the following tasks:
-     * - nmcpPublishAggregationToCentralPortal
-     * - nmcpPublishAggregationToCentralPortalSnapshots
      */
     fun centralPortal(action: Action<CentralPortalOptions>)
 

nmcp/src/main/kotlin/nmcp/NmcpSettings.kt

@@ -6,10 +6,6 @@ import org.gradle.api.file.FileCollection
 interface NmcpSettings {
     /**
      * Configures publishing to central portal releases (Maven Central) and central portal snapshots.
-     *
-     * Adds the following tasks:
-     * - nmcpPublishAggregationToCentralPortal
-     * - nmcpPublishAggregationToCentralPortalSnapshots
      */
     fun centralPortal(action: Action<CentralPortalOptions>)
 }

nmcp/src/main/kotlin/nmcp/internal/utils.kt

@@ -69,7 +69,8 @@ internal fun Project.registerPublishToCentralPortalTasks(
         else ->  null
     }
     val centralPortalLifecycleTaskName = "publish${name.capitalizeFirstLetter()}ToCentralPortal"
-    val snapshotsLifecycleTaskName = "publish${name.capitalizeFirstLetter()}ToCentralPortalSnapshots"
+    val deprecatedLifecycleTaskName = "publish${name.capitalizeFirstLetter()}ToCentralPortalSnapshots"
+    val snapshotsLifecycleTaskName = "publish${name.capitalizeFirstLetter()}ToCentralSnapshots"
 
     val zipName = "${name}.zip"
     val zipTaskProvider = tasks.register(zipTaskName, Zip::class.java) {
@@ -119,6 +120,14 @@ internal fun Project.registerPublishToCentralPortalTasks(
         it.description = "$description to the Central Snapshots repository."
         it.dependsOn(centralSnapshots)
     }
+    project.tasks.register(deprecatedLifecycleTaskName) {
+        it.group = PUBLISH_TASK_GROUP
+        it.description = "$description to the Central Snapshots repository."
+        it.dependsOn(snapshotsLifecycleTaskName)
+        it.doLast {
+            println("'$deprecatedLifecycleTaskName' is deprecated and will be removed in a future release. Use '$snapshotsLifecycleTaskName' instead.")
+        }
+    }
 
     val m2File = File(System.getProperty("user.home")).resolve(".m2/repository")
     registerNmcpPublishFileByFileToFileSystemTask(