Merge pull request gradle#27082 Clean admonitions in Gradle User Manual

### Details
This is a Documentation change ONLY.

### Context
Our User Manual uses too many admonitions and many of them are too long. Users will ignore them as a result.

This PR:
- Cleans admonitions to use preferred ASCII doc syntax.
- Removes long admonitions and turns them into open blocks.
- Fixes CSS of admonitions

### Reviewers: [**Build Link**](https://builds.gradle.org/repository/download/Gradle_Master_Check_BuildDistributions/75426814:id/distributions/gradle-8.6-docs.zip!/gradle-8.6-20231201202801%2B0000/docs/userguide/about_manual.html)
Please make sure nothing was erroneously deleted.

Co-authored-by: Laura Kassovic <lkassovic@gradle.com>

platforms/core-configuration/kotlin-dsl/doc/c4/README.adoc

@@ -2,11 +2,7 @@
 
 Core link:https://c4model.com/#coreDiagrams[C4 Model] diagrams for the Gradle Kotlin DSL.
 
-[NOTE]
-====
-The optional 4th level, UML diagrams, isn't provided, favoring the source code and inspection tools.
-====
-
+NOTE: The optional 4th level, UML diagrams, isn't provided, favoring the source code and inspection tools.
 
 ## Level 1: System Context diagram
 
@@ -33,6 +29,5 @@ It should be useful enough to know where to find what in the Kotlin DSL source c
 
 image::images/C4_3_Component.svg[]
 
-[NOTE]
-This diagram diverges from the C4 Model because the scope is the whole Kotlin DSL system instead of having one diagram per container".
+NOTE: This diagram diverges from the C4 Model because the scope is the whole Kotlin DSL system instead of having one diagram per container.
 This makes this diagram quite large but it shows how everything fits together and is simpler to maintain.

platforms/documentation/docs/src/docs/css/manual.css

@@ -457,6 +457,10 @@ table.tableblock > caption.title { white-space: nowrap; overflow: visible; max-w
 table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; }
 
 /* Custom Admonition Blocks - Icons from https://github.com/primer/octicons */
+.admonitionblock td:last-of-type {
+    padding-bottom: 0em !important;
+}
+
 .admonitionblock {
     margin: 1.4rem 0 0
 }
@@ -501,7 +505,7 @@ table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-si
 .admonitionblock td.content {
     word-wrap: anywhere;
     background: var(--admonition-background);
-    padding: 1rem 1rem 1rem;
+    padding: 1rem 1rem 1rem 1rem;
     width: 100%;
     border-radius: 4px;
 }
@@ -1276,6 +1280,14 @@ body.book #header > h1 {
  * These styles are copied from a CSS ruleset in asciidoctor.css that has the same group of
  * selectors except that they end with `.nowrap`.
  */
+ .openblock .content {
+    background: #fafafa;
+ 	margin-bottom: 1.25em;
+    padding: 1em 1em 0em 1em;
+    border-radius: 4px;
+    overflow: auto !important;
+ }
+
 .literalblock pre,
 .literalblock pre[class],
 .listingblock pre,

platforms/documentation/docs/src/docs/userguide/api/groovy_build_script_primer.adoc

@@ -38,11 +38,11 @@ Both `version` and `configurations {}` are part of link:{groovyDslPath}/org.grad
 This example reflects how every Groovy build script is backed by an implicit instance of `Project`. If you see an unqualified element and you don't know where it's defined, always check the `Project` API documentation to see if that's where it's coming from.
 
 [CAUTION]
-====
+--
 Avoid using https://groovy-lang.org/metaprogramming.html#_metaclasses[Groovy MetaClass] programming techniques in your build scripts. Gradle provides its own API for adding <<writing_build_scripts#sec:extra_properties,dynamic runtime properties>>.
 
 Use of Groovy-specific metaprogramming can cause builds to retain large amounts of memory between builds that will eventually cause the Gradle daemon to run out-of-memory.
-====
+--
 
 [[groovy:properties]]
 == Properties

platforms/documentation/docs/src/docs/userguide/api/kotlin_dsl.adoc

@@ -23,11 +23,7 @@
 Gradle's Kotlin DSL provides an alternative syntax to the traditional Groovy DSL with an enhanced editing experience in supported IDEs, with superior content assist, refactoring, documentation, and more.
 This chapter provides details of the main Kotlin DSL constructs and how to use it to interact with the Gradle API.
 
-[TIP]
-====
-If you are interested in migrating an existing Gradle build to the Kotlin DSL, please also check out the dedicated <<migrating_from_groovy_to_kotlin_dsl.adoc#migrating_groovy_kotlin,migration section>>.
-====
-
+TIP: If you are interested in migrating an existing Gradle build to the Kotlin DSL, please also check out the dedicated <<migrating_from_groovy_to_kotlin_dsl.adoc#migrating_groovy_kotlin,migration section>>.
 
 [[kotdsl:prerequisites]]
 == Prerequisites
@@ -149,10 +145,7 @@ Just like the Groovy-based equivalent, the Kotlin DSL is implemented on top of G
 Everything you can read in a Kotlin DSL script is Kotlin code compiled and executed by Gradle.
 Many of the objects, functions and properties you use in your build scripts come from the Gradle API and the APIs of the applied plugins.
 
-[TIP]
-====
-You can use the link:{kotlinDslPath}/[Kotlin DSL reference] search functionality to drill through the available members.
-====
+TIP: You can use the link:{kotlinDslPath}/[Kotlin DSL reference] search functionality to drill through the available members.
 
 === Script file names
 
@@ -181,12 +174,11 @@ All Kotlin DSL build scripts have implicit imports consisting of:
 ** `org.gradle.kotlin.dsl.plugins.dsl`
 ** `org.gradle.kotlin.dsl.precompile`
 
-[CAUTION]
 .Avoid using internal Kotlin DSL APIs
-====
+--
 Use of internal Kotlin DSL APIs in plugins and build scripts has the potential to break builds when either Gradle or plugins change.
 The link:{kotlinDslPath}/[Kotlin DSL API] extends the <<authoring_maintainable_build_scripts#sec:avoiding_gradle_internal_apis,Gradle public API>> with the types listed in the link:{kotlinDslPath}/[corresponding API docs] that are in the packages listed above (but not subpackages of those).
-====
+--
 
 [[sec:compilation_warnings]]
 === Compilation warnings
@@ -255,6 +247,7 @@ include::sample[dir="snippets/kotlinDsl/accessors/kotlin",files="build.gradle.kt
 [TIP]
 ====
 Your IDE knows about the type-safe accessors, so it will include them in its suggestions.
+
 This will happen both at the top level of your build scripts — most plugin extensions are added to the `Project` object — and within the blocks that configure an extension.
 ====
 
@@ -480,6 +473,7 @@ For any other situation, keep reading.
 [TIP]
 ====
 When publishing plugins, please use Gradle's built-in <<java_gradle_plugin#java_gradle_plugin,Gradle Plugin Development Plugin>>.
+
 It automates the publication of the metadata necessary to make your plugins usable with the `plugins {}` block.
 ====
 
@@ -537,11 +531,7 @@ Community plugins also contribute containers, like the `android.buildTypes` cont
 The Kotlin DSL provides several ways for build authors to interact with containers.
 We look at each of those ways next, using the `tasks` container as an example.
 
-[TIP]
-====
-Note that you can leverage the type-safe accessors described in <<kotdsl:accessor_applicability,another section>> if you are configuring existing elements on supported containers. That section also describes which containers support type-safe accessors.
-====
-
+TIP: Note that you can leverage the type-safe accessors described in <<kotdsl:accessor_applicability,another section>> if you are configuring existing elements on supported containers. That section also describes which containers support type-safe accessors.
 
 === Using the container API
 
@@ -564,10 +554,7 @@ include::sample[dir="snippets/kotlinDsl/containers-api/kotlin",files="build.grad
 <7> Gets a reference to the existing task named `test` of type `Test` and configures it — in this case you have access to the properties and methods of the specified type
 <8> Registers a new task named `myCopy2` of type `Copy` and configures it
 
-[NOTE]
-====
-The above sample relies on the configuration avoidance APIs. If you need or want to eagerly configure or register container elements, simply replace `named()` with `getByName()` and `register()` with `create()`.
-====
+NOTE: The above sample relies on the configuration avoidance APIs. If you need or want to eagerly configure or register container elements, simply replace `named()` with `getByName()` and `register()` with `create()`.
 
 === Using Kotlin delegated properties
 
@@ -586,7 +573,8 @@ include::sample[dir="snippets/kotlinDsl/containers-delegated-properties/kotlin",
 
 [NOTE]
 ====
-The above rely on configuration avoidance APIs. If you need to eagerly configure or register container elements simply replace link:{kotlinDslPath}/gradle/org.gradle.kotlin.dsl/existing.html[`existing()`] with link:{kotlinDslPath}/gradle/org.gradle.kotlin.dsl/getting.html[`getting()`] and link:{kotlinDslPath}/gradle/org.gradle.kotlin.dsl/registering.html[`registering()`] with link:{kotlinDslPath}/gradle/org.gradle.kotlin.dsl/creating.html[`creating()`].
+The above rely on configuration avoidance APIs.
+If you need to eagerly configure or register container elements simply replace link:{kotlinDslPath}/gradle/org.gradle.kotlin.dsl/existing.html[`existing()`] with link:{kotlinDslPath}/gradle/org.gradle.kotlin.dsl/getting.html[`getting()`] and link:{kotlinDslPath}/gradle/org.gradle.kotlin.dsl/registering.html[`registering()`] with link:{kotlinDslPath}/gradle/org.gradle.kotlin.dsl/creating.html[`creating()`].
 ====
 
 === Configuring multiple container elements together
@@ -763,11 +751,10 @@ The plugin achieves this by doing the following:
  ** registers the link:https://kotlinlang.org/docs/sam-with-receiver-plugin.html[SAM-with-receiver Kotlin compiler plugin].
  * Enables support for <<custom_plugins#sec:precompiled_plugins,precompiled script plugins>>.
 
-[CAUTION]
 .Avoid specifying a version for the `kotlin-dsl` plugin
-====
+--
 Each Gradle release is meant to be used with a specific version of the `kotlin-dsl` plugin and compatibility between arbitrary Gradle releases and `kotlin-dsl` plugin versions is not guaranteed. Using an unexpected version of the `kotlin-dsl` plugin in a build will emit a warning and can cause hard to diagnose problems.
-====
+--
 
 This is the basic configuration you need to use the plugin:
 
@@ -904,10 +891,7 @@ To call a Groovy function with default arguments from Kotlin, always pass values
 You may sometimes have to call Groovy methods that take link:https://groovy-lang.org/closures.html[Closure] arguments from Kotlin code.
 For example, some third-party plugins written in Groovy expect closure arguments.
 
-[NOTE]
-====
-Gradle plugins written in any language should prefer the type `Action<T>` type in place of closures. Groovy closures and Kotlin lambdas are automatically mapped to arguments of that type.
-====
+NOTE: Gradle plugins written in any language should prefer the type `Action<T>` type in place of closures. Groovy closures and Kotlin lambdas are automatically mapped to arguments of that type.
 
 In order to provide a way to construct closures while preserving Kotlin's strong typing, two helper methods exist:
 

platforms/documentation/docs/src/docs/userguide/authoring-builds/basics/intro_multi_project_builds.adoc

@@ -125,10 +125,7 @@ If you run the command from the _services_ project directory, you will only exec
 The basic rule behind Gradle's behavior is to *execute all tasks down the hierarchy with _this_ name*.
 And *complain if there is _no_ such task found* in any of the subprojects traversed.
 
-[NOTE]
-====
-Some task selectors, like `help` or `dependencies`, will only run the task on the project they are invoked on and not on all the subprojects to reduce the amount of information printed on the screen.
-====
+NOTE: Some task selectors, like `help` or `dependencies`, will only run the task on the project they are invoked on and not on all the subprojects to reduce the amount of information printed on the screen.
 
 [[sec:executing_tasks_by_fully_qualified_name]]
 === Executing tasks by fully qualified name

platforms/documentation/docs/src/docs/userguide/authoring-builds/best-practices/organizing_gradle_projects.adoc

@@ -211,9 +211,13 @@ Optionally, the `buildSrc` directory can host a build script if additional confi
 =====
 ====
 
-NOTE: A change in `buildSrc` causes the whole project to become out-of-date.
+[NOTE]
+====
+A change in `buildSrc` causes the whole project to become out-of-date.
+
 Thus, when making small incremental changes, the <<command_line_interface#sec:command_line_execution_options, `--no-rebuild` command-line option>> is often helpful to get faster feedback.
-Remember to run a full build regularly or at least when you're done, though.
+Remember to run a full build regularly.
+====
 
 == Declare properties in `gradle.properties` file
 

platforms/documentation/docs/src/docs/userguide/authoring-builds/other/build_services.adoc

@@ -173,7 +173,7 @@ Currently, it is not possible to use a build service with a worker API action th
 You can constrain concurrent execution when you register the service, by using the `Property` object returned from link:{javadocPath}/org/gradle/api/services/BuildServiceSpec.html#getMaxParallelUsages--[BuildServiceSpec.getMaxParallelUsages()].
 When this property has no value, which is the default, Gradle does not constrain access to the service. When this property has a value > 0, Gradle will allow no more than the specified number of tasks to use the service concurrently.
 
-*IMPORTANT*: When the consuming task property is annotated with `@Internal`, for the constraint to take effect, the build service *must* be registered with the consuming task via
+IMPORTANT: When the consuming task property is annotated with `@Internal`, for the constraint to take effect, the build service *must* be registered with the consuming task via
 link:{groovyDslPath}/org.gradle.api.Task.html#org.gradle.api.Task:usesService(org.gradle.api.provider.Provider)[Task.usesService(Provider<? extends BuildService<?>>)].
 This is not necessary if, instead, the consuming property is annotated with `@ServiceReference`.
 

platforms/documentation/docs/src/docs/userguide/authoring-builds/other/dataflow_actions.adoc

@@ -15,10 +15,7 @@
 [[dataflow_action]]
 = Dataflow Actions
 
-[NOTE]
-====
-The dataflow actions support is an <<feature_lifecycle.adoc#feature_lifecycle,incubating>> feature, and the details described here may change.
-====
+NOTE: The dataflow actions support is an <<feature_lifecycle.adoc#feature_lifecycle,incubating>> feature, and the details described here may change.
 
 A preferred way of executing work in a Gradle build is using a task.
 However, there are some kinds of work that do not fit tasks well, for example, custom handling of the build failure.

platforms/documentation/docs/src/docs/userguide/authoring-builds/other/logging.adoc

@@ -28,13 +28,7 @@ LIFECYCLE:: Progress information messages
 INFO:: Information messages
 DEBUG:: Debug messages
 
-[NOTE]
-====
-
-The rich components of the console (build status and work in progress area) are displayed regardless of the log level used. Before Gradle 4.0 those rich components were only displayed at log level `LIFECYCLE` or below.
-
-====
-
+NOTE: The rich components of the console (build status and work in progress area) are displayed regardless of the log level used. Before Gradle 4.0 those rich components were only displayed at log level `LIFECYCLE` or below.
 
 [[sec:choosing_a_log_level]]
 == Choosing a log level
@@ -53,12 +47,7 @@ You can use the command line switches shown in <<#logLevelCommandLineOptions, Lo
 | `-d` or `--debug` | DEBUG and higher (that is, all log messages)
 |===
 
-[CAUTION]
-====
-
-The `DEBUG` log level can <<#sec:debug_security, expose security sensitive information to the console>>.
-
-====
+CAUTION: The `DEBUG` log level can <<#sec:debug_security, expose security sensitive information to the console>>.
 
 [[stacktraces]]
 
@@ -154,6 +143,7 @@ Gradle also provides integration with the Java Util Logging, Jakarta Commons Log
 
 [[sec:changing_what_gradle_logs]]
 == Changing what Gradle logs
+
 [WARNING]
 ====
 The <<configuration_cache.adoc#config_cache,configuration cache>> limits the ability to customize Gradle's logging UI.

platforms/documentation/docs/src/docs/userguide/authoring-builds/other/test_kit.adoc

@@ -84,6 +84,7 @@ The GradleRunner uses the <<third_party_integration.adoc#embedding,Tooling API>>
 ====
 GradleRunner supports the same range of Gradle versions as the Tooling API.
 The supported versions are defined in the <<third_party_integration.adoc#sec:embedding_compatibility,compatibility matrix>>.
+
 Builds with older Gradle versions _may_ still work but there are no guarantees.
 ====
 
@@ -125,10 +126,7 @@ include::{snippetsPath}/testKit/automaticClasspathInjectionQuickstart/groovy/src
 
 The following build script demonstrates how to reconfigure the conventions provided by the Java Gradle Plugin Development plugin for a project that uses a custom `Test` source set.
 
-[NOTE]
-====
-A new configuration DSL for modeling the below `functionalTest` suite is available via the incubating <<jvm_test_suite_plugin.adoc#jvm_test_suite_plugin,JVM Test Suite>> plugin.
-====
+NOTE: A new configuration DSL for modeling the below `functionalTest` suite is available via the incubating <<jvm_test_suite_plugin.adoc#jvm_test_suite_plugin,JVM Test Suite>> plugin.
 
 .Reconfiguring the classpath generation conventions of the Java Gradle Development plugin
 ====