Docs: Make snippets easier to read and copy1.0

Separated snippet code blocks into copyable chunks, with comments broken out into the documentation. I used the tab command to allow the user to choose between Groovy or Kotlin and set Kotlin as the default. Added some grammar fixes and made changed the style of the example paths for clarity. Fixes: QTTA-131 Change-Id: Id36e8e97a9164920976bcaaf44ceef4c59e51eff Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io> (cherry picked from commit d41d8f94e4bc7c8a37b6558613ad91f2427c6cb2) Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
author: Nicholas Bennett <nicholas.bennett@qt.io> 2024-10-28 12:52:30 +0200
committer: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> 2024-11-07 11:16:06 +0000
commit: 949b56d381253610d36ed57f47fd4412deb83afe (patch)
tree: 8a1a40359111db6335147a205773cde10e291252
parent: c2b7c4efe416da258dccafd7879c1f94aa89858b (diff)
1 files changed, 101 insertions, 46 deletions
diff --git a/src/doc/src/qt-gradle-plugin.qdoc b/src/doc/src/qt-gradle-plugin.qdoc
index 6b34b85..cc70dbf 100644
--- a/src/doc/src/qt-gradle-plugin.qdoc
+++ b/src/doc/src/qt-gradle-plugin.qdoc
@@ -88,7 +88,7 @@
     here explicitly deselect these and anything not required.
 
     \list 1
-        \li Select custom install. If you change the location make sure to note
+        \li Select custom install. If you change the location, make sure to note
         this as you will need it later.
         \li Deselect \uicontrol{\QDS}.
         \li Expand \uicontrol{Qt 6.8} or later and select \uicontrol{Qt for Android}.
@@ -119,7 +119,7 @@
     \section3 Use the plugin from Maven
 
     Modify the settings.gradle(.kts) from your project's root.
-    This downloads the plugin from the Qt Maven instance and you will be able to refer to its
+    This downloads the plugin from the Qt Maven instance, and you will be able to refer to its
     id in the build.gradle(.kts) later on.
 
     \section4 Kotlin/Groovy (settings.gradle(.kts))
@@ -134,70 +134,124 @@
     \section3 Configure the plugin
 
     The plugin needs to know where certain parts of the Qt toolchain are.
-    In the \c <yourappname>/app/build.gradle(.kts) file you need to define paths for plugin.
+    In the \c <yourappname>/app/build.gradle(.kts) file, you need to define paths for the plugin.
 
-    \section4 Kotlin (build.gradle.kts)
-    Inside the plugins block, include the plugin ID and version.
+    \section4 Plugins path
+    Inside the \b plugins block, include the plugin ID and version.
 
+    \tab {qtgradle-snippets-plugin}{tab-kotlin-plugin}{Kotlin}{checked}
+    \tab {qtgradle-snippets-plugin}{tab-groovy-plugin}{Groovy}{}
+    \tabcontent {tab-kotlin-plugin}
     \badcode \majorversion
     plugins {
         id("org.qtproject.qt.gradleplugin") version("\1.+")
     }
     \endcode
+    \endtabcontent
+    \tabcontent {tab-groovy-plugin}
+    \badcode \majorversion
+    plugins {
+        id 'org.qtproject.qt.gradleplugin' version '\1.+'
+    }
+    \endcode
+    \endtabcontent
 
-    Inside Qt build block define the Qt path (with version >= 6.8.0) and path to the QML project.
-    Other properties are optional and explained below.
+    Create a QtBuild block:
     \badcode
-    // Qt Build is a extension of the Qt Build Task
-    QtBuild {
-        // Qt installation directory
-        qtPath = file("home/<your-username>/Qt/6.8.0")
+    QtBuild{
 
-        // QML project directory
-        projectPath = file("../qmlapp")
+    }
+    \endcode
 
-        // Optional: Qt kit directory location
-        // If defined build will be done to only that ABI
-        // else will build using Multi-ABI
-        qtKitDir = file('home/<your-username>/<your-Qt-builds>/<your-Qt-kit>')
+    Inside the \b QtBuild block, define the following paths.
 
-        // Optional: Extra cmake arguments for configuration
-        setExtraCMakeArguments("-DCMAKE_BUILD_TYPE=Release")
+    \section4 QtPath
 
-        // Optional: If your ninja is installed somewhere other than Qt/Tools/Ninja or
-        // not found in system path you can define it here
-        ninjaPath = '<your>/<path>/<to>/Ninja'
-    }
+    Qt path for version 6.8.0 or newer where the Qt version you want to build against is installed:
+    \tab {qtgradle-snippets-qtpath}{tab-kotlin-qtpath}{Kotlin}{checked}
+    \tab {qtgradle-snippets-qtpath}{tab-groovy-qtpath}{Groovy}{}
+    \tabcontent {tab-kotlin-qtpath}
+    \badcode
+        qtPath = file("/home/username/Qt/6.8.0")
+    \endcode
+    \endtabcontent
+    \tabcontent {tab-groovy-qtpath}
+        \badcode
+        qtPath file('/home/username/Qt/6.8.0/Qt/6.8.0')
     \endcode
+    \endtabcontent
 
-    \section4 Groovy
-    \badcode \majorversion
-    plugins {
-        id 'org.qtproject.qt.gradleplugin' version '\1.+'
-    }
+    \section4 QML project directory
+
+    Add the path to the QML project directory:
+
+    \tab {qtgradle-snippets-projectpath}{tab-kotlin-projectpath}{Kotlin}{checked}
+    \tab {qtgradle-snippets-projectpath}{tab-groovy-projectpath}{Groovy}{}
+    \tabcontent {tab-kotlin-projectpath}
+    \badcode
+        projectPath = file("../qmlapp")
     \endcode
+    \endtabcontent
+    \tabcontent {tab-groovy-projectpath}
+    \badcode
+        projectPath = file('../qmlapp')
+    \endcode
+    \endtabcontent
+
+    Other properties are optional and explained below:
+
+    \section4 Optional: Qt kit directory
+
+    By default, this is not defined, and Multi-ABIs will be built. If this path is defined,
+    then a build will be done for that kit ABI only.
 
+    \tab {qtgradle-snippets-qtKitDir}{tab-kotlin-qtKitDir}{Kotlin}{checked}
+    \tab {qtgradle-snippets-qtKitDir}{tab-groovy-qtKitDir}{Groovy}{}
+    \tabcontent {tab-kotlin-qtKitDir}
     \badcode
-    QtBuild {
-        // Qt installation directory
-        qtPath file('home/<your-username>/Qt/6.8.0')
+        qtKitDir = file("/home/username/qt/build/your-qt-kit")
+    \endcode
+    \endtabcontent
+    \tabcontent {tab-groovy-qtKitDir}
+    \badcode
+        qtKitDir = file('/home/username/qt/build/your-qt-kit')
+    \endcode
+    \endtabcontent
 
-        // QML project directory
-        projectPath file('../qmlapp')
+    \section4 Optional: Extra CMake arguments
 
-        // Optional: Qt kit directory location
-        // If defined build will be done to only that ABI
-        // else will build using Multi-ABI
-        qtKitDir file('home/<your-username>/<your-Qt-builds>/<your-Qt-kit>')
+    For example:
 
-        // Optional: Extra cmake arguments for configuration
+    \tab {qtgradle-snippets-cmakearg}{tab-kotlin-cmakearg}{Kotlin}{checked}
+    \tab {qtgradle-snippets-cmakearg}{tab-groovy-cmakearg}{Groovy}{}
+    \tabcontent {tab-kotlin-cmakearg}
+    \badcode
+        setExtraCMakeArguments("-DCMAKE_BUILD_TYPE=Release")
+    \endcode
+    \endtabcontent
+    \tabcontent {tab-groovy-cmakearg}
+    \badcode
         extraCMakeArguments = ['-DCMAKE_BUILD_TYPE=Release']
+    \endcode
+    \endtabcontent
 
-        // Optional: If your ninja is installed somewhere other than Qt/Tools/Ninja or
-        // not found in system path you can define it here
-        ninjaPath '<your>/<path>/<to>/Ninja'
-    }
+    \section4 Optional: ninjaPath
+
+    If your ninja is installed somewhere other than \b Qt/Tools/Ninja or not found in
+    the system path, you can define it here:
+
+    \tab {qtgradle-snippets-ninja}{tab-kotlin-ninja}{Kotlin}{checked}
+    \tab {qtgradle-snippets-ninja}{tab-groovy-ninja}{Groovy}{}
+    \tabcontent {tab-kotlin-ninja}
+    \badcode
+        ninjaPath = "/your/path/to/ninja"
+    \endcode
+    \endtabcontent
+    \tabcontent {tab-groovy-ninja}
+    \badcode
+        ninjaPath = '/your/path/to/ninja'
     \endcode
+    \endtabcontent
 
     \section2 Using the plugin
 
@@ -215,8 +269,8 @@
     \endcode
 
     If you want to use a build of Qt that was not obtained through the online
-    installer, you need to modify the \c qtKitDir variable, defined in your
-    project's \c build.gradle file. The file is in your project's
+    installer, you need to modify the \c qtKitDir variable defined in your
+    project's \c build.gradle(.kts) file. The file is in your project's
     \c <yourappname>/app folder. Its path could be, for example:
     \c qtquickview_java/app/build.gradle
     \badcode
@@ -241,14 +295,15 @@
     set PATH=%PATH%;C:\<your-username>\myQtBuilds\<your-Qt-kit>\src\3rdparty\gradle
     \endcode
 
-    \section3 Error:"No Qt for Android kit found".
+    \section3 Error: "No Qt for Android kit found".
 
     Fix: qtPath = file('..../Qt') needs to have the Qt version as the path's target folder.
     For example:('..../Qt/6.8.0')
 
     \section3 Error:"[home/../declarative/build/qt_generated/quick, aar] failed with exit code 1".
 
-    Fix: If you use c\ qtKitDir change \c qtPath to use absolute path instead the relative one.
+    Fix: If you use \c qtKitDir, change \c qtPath to use an absolute path instead of the
+    relative one.
 
     Relative:
     \badcode
author	Nicholas Bennett <nicholas.bennett@qt.io>	2024-10-28 12:52:30 +0200
committer	Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>	2024-11-07 11:16:06 +0000
commit	949b56d381253610d36ed57f47fd4412deb83afe (patch)
tree	8a1a40359111db6335147a205773cde10e291252
parent	c2b7c4efe416da258dccafd7879c1f94aa89858b (diff)