Configure gradle to check code samples

.github/workflows/check-code-embedding.yml

@@ -0,0 +1,37 @@
+name: Check Code Embedding
+
+on:
+  pull_request:
+
+jobs:
+  build-embedded-code:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: 'recursive'
+
+      - uses: actions/setup-java@v5
+        with:
+          java-version: 8
+          distribution: zulu
+
+      - run: ./gradlew :buildAll
+
+  check-embedded-samples:
+    # TODO:2025-12-16:julia.evseeva: Remove the `if: false` when the issue
+    # will be fixed https://github.com/SpineEventEngine/embed-code/issues/66
+    if: false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: 'recursive'
+
+      - uses: actions/setup-java@v5
+        with:
+          java-version: 11
+          distribution: zulu
+
+      - name: Check Embedding
+        run: ./gradlew :checkSamples

.gitignore

@@ -29,3 +29,13 @@ jsconfig.json
 
 # The `embed-code` temporary directory
 _code/build
+
+# Local Java version for this project
+.java-version
+
+# Gradle interim configs
+.gradle/
+
+# Gradle build files
+build/
+generated/

README.md

@@ -18,12 +18,15 @@ are working as intended. It allows making changes more convenient for authors.
 
 ## Prerequisites
 
-1. Install [Go][go] at least version `1.12`.
-2. Install [Node.js][nodejs]. Its version should be `18+`.
-3. Install [Hugo Extended][hugo-quick-start] at least version `v0.145` or higher.
-4. Get access to the [`site-commons`][site-commons] repository from the admins
+1. Install [Java JDK] version `11` to build the site.
+2. Install [Go][go] at least version `1.12`.
+3. Install [Node.js][nodejs]. Its version should be `18+`.
+4. Install [Hugo Extended][hugo-quick-start] at least version `v0.145` or higher.
+5. Get access to the [`site-commons`][site-commons] repository from the admins
    to be able to download the theme.
-5. Make sure [SSH][site-commons-ssh] is configured correctly and the passphrase is stored in the keychain.
+6. Make sure [SSH][site-commons-ssh] is configured correctly and the passphrase 
+   is stored in the keychain.
+7. Install project dependencies from the `site` directory by running `npm install`.
 
 ## Running the documentation locally
 
@@ -35,16 +38,22 @@ The project has two directories:
 * `site` – contains the HTML and CSS files needed only to run the
   documentation locally.
 
-To run the documentation locally:
+To build and launch the site on the local server:
 
-1. Navigate to the `site` directory.
-2. Install project dependencies:
+```shell
+./gradlew :runSite
+```
 
-   ```shell
-   npm install
-   ```
+To build the site without running the server:
+
+```shell
+./gradlew :buildSite
+```
+
+Another way to run the site locally is to follow these steps:
 
-3. Run the site locally:
+1. Navigate to the `site` folder.
+2. Start the local server with this command:
 
    ```shell
    hugo server
@@ -92,6 +101,20 @@ the [`embed-code`][embed-code] Go subcommand.
 The code resides under the `_code` directory. For instructions on embedding 
 the code into the pages, please see the [`EMBEDDING.md`](./_code/EMBEDDING.md) file.
 
+Please note that the following part of the script requires an ARM-based Mac.
+
+To embed the code samples, run:
+
+```shell
+./gradlew :embedCode
+```
+
+To verify that the source code samples embedded into the pages are up-to-date, run:
+
+```shell
+./gradlew :checkSamples
+```
+
 ## Product release
 
 To release a new version of Spine documentation, see the [SPINE_RELEASE.md](SPINE_RELEASE.md).

_code/EMBEDDING.md

@@ -25,6 +25,7 @@ of the spine.io documentation:
 
 * `examples` — contains examples selected from the repositories under `spine-examples`
   organization. These repositories are added to this project as Git submodules.
+* `samples` — smaller pieces of code embedded to the site.
 
 To get the latest version of the code snippets, update the submodules:
 
@@ -50,7 +51,7 @@ to the documentation files using the tool. The most important points here are:
 ### How to update an existing code snippet?
 
 1. Update the snippet in the appropriate repository.
-2. Make sure it builds successfully: `./gradlew build`.
+2. Make sure it builds successfully.
 3. Go to the `SpineEventEngine/documentation` project.
 4. Navigate to the `_code` directory.
 5. Execute the binary based on your operating system and architecture: 
@@ -61,20 +62,44 @@ to the documentation files using the tool. The most important points here are:
    ./embed-code-macos -config-path="config-v1.yml" -mode="embed"
    ```
 
-### How to add a new code snippet?
+### Adding a new example project
 
-1. Add a new snippet in the appropriate repository.
-2. Make sure it builds successfully: `./gradlew build`.
-3. Go to the `SpineEventEngine/documentation` project and insert code 
-   embedding directives where needed.
-4. Navigate to the `_code` directory.
-5. Execute: `./embed-code -config-path="config-of-your-choice.yml" -mode="embed"`.
+1. Make sure the project you're going to add has a top-level `buildAll` Gradle task.
+
+   See the build script of [Hello Example](https://github.com/spine-examples/hello/blob/master/build.gradle)
+   for the declaration of such a task. This task must be present in both single- 
+   and multi-module Gradle example projects that are going to be used for 
+   embedding into this site.
+
+   See the declaration of `buildAll` task for more details.
+
+2. Add the example code as a submodule for this project:
+
+   ```bash
+   git submodule add https://github.com/spine-examples/<example-name> _code/examples/<example-name>
+   ```
+   Please make sure the new submodule goes under the `_code/examples` directory, as shown in
+   the command line template above.
+
+3. Include the build of the added project into the [`settings.gradle.kts`](settings.gradle.kts)
+   file.
+4. Insert code embedding directives where needed in the `docs/content/` folder.
+5. Navigate to the `_code` directory.
+6. Execute: `./embed-code -config-path="config-of-your-choice.yml" -mode="embed"`.
 
    For example:
    ```shell
    ./embed-code-macos -config-path="config-v1.yml" -mode="embed"
    ```
 
+### Adding a new small piece
+
+1. Add the code under `_code/samples/src` directory.
+2. Make sure tests for the new code pass.
+3. Add the new piece using the [`embed-code` guide][embed-code-readme].
+4. Include the build of the added project into the [`settings.gradle.kts`](settings.gradle.kts)
+   file `includeBuild("./_code/samples")`.
+
 ### How to remove a code snippet?
 
 1. Remove the snippet in the appropriate repository.

_code/samples/build.gradle

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2020, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+plugins {
+    id "io.spine.tools.gradle.bootstrap" version "1.7.0"
+}
+
+spine.enableJava().server()
+
+ext {
+    junitVersion = '5.7.0'
+}
+
+dependencies {
+    testImplementation "org.junit.jupiter:junit-jupiter-api:$junitVersion"
+    testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:$junitVersion"
+}
+
+test {
+    useJUnitPlatform {
+        includeEngines 'junit-jupiter'
+    }
+}
+
+project.ext {
+    // The root for the generated source code.
+    generatedRootDir = "$projectDir/generated"
+
+    // Directories for the code generated by the Protobuf Compiler and Spine plugins
+    // for the Compiler.
+    generatedJavaDir = "$generatedRootDir/main/java"
+    generatedTestJavaDir = "$generatedRootDir/test/java"
+
+    // Directories for the Spine-specific code generated by the Spine Model Compiler,
+    // for example, rejections.
+    generatedSpineDir = "$generatedRootDir/main/spine"
+    generatedTestSpineDir = "$generatedRootDir/test/spine"
+}
+
+apply plugin: 'idea'
+
+idea {
+    module {
+        // Add generated code directories to the source code of the module in IntelliJ IDEA.
+        generatedSourceDirs += file(generatedJavaDir)
+        generatedSourceDirs += file(generatedSpineDir)
+        testSourceDirs += file(generatedTestJavaDir)
+        testSourceDirs += file(generatedTestSpineDir)
+    }
+}
+
+/**
+ * The task for composite builds to include this project and depend on this top-level task.
+ */
+task buildAll(type: GradleBuild) {
+    tasks = [ 'build' ]
+}

_code/samples/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.7.1-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists