Docs set 1

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

@@ -0,0 +1,34 @@
+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: 17
+          distribution: zulu
+
+      - run: cd docs && ./gradlew :buildAll
+
+  check-embedded-samples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: 'recursive'
+
+      - uses: actions/setup-java@v5
+        with:
+          java-version: 17
+          distribution: zulu
+
+      - name: Check Embedding
+        run: cd docs && ./gradlew :checkSamples

buildSrc/src/main/kotlin/BuildExtensions.kt

@@ -152,6 +152,9 @@ val PluginDependenciesSpec.protobuf: PluginDependencySpec
 val PluginDependenciesSpec.prototap: PluginDependencySpec
     get() = id(ProtoTap.gradlePluginId).version(ProtoTap.version)
 
+val PluginDependenciesSpec.`spine-compiler`: PluginDependencySpec
+    get() = id(Compiler.pluginId).version(Compiler.version)
+
 val PluginDependenciesSpec.`gradle-doctor`: PluginDependencySpec
     get() = id(GradleDoctor.pluginId).version(GradleDoctor.version)
 

buildSrc/src/main/kotlin/BuildSettings.kt

@@ -39,4 +39,5 @@ object BuildSettings {
     val javaVersionCompat = JavaVersion.toVersion(JVM_VERSION)
     val jvmTarget = JvmTarget.JVM_17
     const val REMOTE_DEBUG_PORT = 5566
+    const val TIMEOUT_MINUTES = 42L
 }

buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt

@@ -46,12 +46,12 @@ object CoreJvmCompiler {
     /**
      * The version used to in the build classpath.
      */
-    const val dogfoodingVersion = "2.0.0-SNAPSHOT.050"
+    const val dogfoodingVersion = "2.0.0-SNAPSHOT.051"
 
     /**
      * The version to be used for integration tests.
      */
-    const val version = "2.0.0-SNAPSHOT.050"
+    const val version = "2.0.0-SNAPSHOT.051"
 
     /**
      * The ID of the Gradle plugin.

buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt

@@ -36,7 +36,7 @@ object Validation {
     /**
      * The version of the Validation library artifacts.
      */
-    const val version = "2.0.0-SNAPSHOT.392"
+    const val version = "2.0.0-SNAPSHOT.393"
 
     /**
      * The last version of Validation compatible with ProtoData.

docs/.gitignore

@@ -0,0 +1,15 @@
+# Hugo cache files
+_preview/resources
+public
+
+# Node modules
+_preview/node_modules
+
+# Used to control concurrency between multiple Hugo instances
+_preview/.hugo_build.lock
+
+# Needed for navigation/intellisense help inside code editors
+jsconfig.json
+
+# `_out` directory in the example projects
+**/_out

docs/GRADLE.md

@@ -0,0 +1,62 @@
+# Gradle project of the Validation Documentation
+
+This document describes the Gradle project structure and build configuration for
+building the documentation [preview site](./_preview) for the Spine Validation library.
+
+The site built by this project is used for development and preview purposes.
+It is not meant to be published as-is, but rather to be used as a staging area for
+the documentation before it is merged into the main [documentation][main-documentation] project.
+
+## Build tasks
+
+The [Gradle build](build.gradle.kts) under the `docs/` provides the following tasks:
+
+1. **`buildAll`** — building the code of the examples embedded in the documentation. 
+    This ensures that all code snippets are valid and can be compiled.
+
+2. **`embedCode`** — embedding the source code of the examples into the Markdown files. 
+    This allows the documentation to include up-to-date code snippets from the source files.
+   This task is meant to be run manually when you write or update the documentation.
+
+3. **`checkSamples`** — checking that the embedded code snippets in the Markdown files are
+   consistent with the source code. 
+   This is a validation step to ensure that the documentation accurately reflects the example code.
+   This task is executed automatically via the [GitHub workflow][check-code-embedding].
+
+4. **`buildSite`** — building the documentation site using Hugo. 
+   The site is generated in the [_preview/](./_preview) directory.
+
+5. **`runSite`** — running a local Hugo server to preview the documentation site. 
+   This allows you to view the documentation in a web browser during development.
+
+6. **`installDependencies`** — installing the Node dependencies for the preview site. 
+   Tasks related to Hugo depend on this task. It is not meant to be run manually.
+
+## Paths in the scripts
+
+The shell [scripts](./_script) used by the Gradle build assume that **this** `docs/`
+directory is the current working directory.
+
+So when you start working with the documentation, make sure to `cd` into
+it before running any of the scripts or Gradle tasks.
+
+## Including example sources
+
+It is done in the [`settings.gradle.kts`](settings.gradle.kts) file via `includeBuild` directive.
+If you add another example proejct, please remember to update
+the [`settings.gradle.kts`](settings.gradle.kts) file.
+
+## Linking to the main project build
+
+The example projects share the following directories and files with
+the main code project via symlinks:
+ * `buildSrc`
+ * `gradle.properties`
+ * `gradlew`
+ * `gradlew.bat`
+
+When you add an example project, make sure to create the necessary symlinks to
+these files and directories.
+
+[check-code-embedding]: ../.github/workflows/check-code-embedding.yml
+[main-documentation]: https://github.com/SpineEventEngine/documentation/

docs/STRUCTURE.md

@@ -0,0 +1,175 @@
+# Structuring repositories for Hugo documentation using Go modules
+
+This document describes the **recommended repository layout and Hugo
+Module mount strategy** for building modular documentation where:
+
+-   The **main site** assembles documentation from multiple repositories
+-   Each framework/library keeps **all documentation isolated under
+    `docs/`**
+-   Hugo Modules (Go modules) are used for versioning and composition
+
+------------------------------------------------------------------------
+
+## High-level architecture
+
+-   **Main site repository**
+    -   Hugo site that assembles all documentation
+    -   Imports documentation modules only
+-   **Documentation provider repositories** (framework, libraries)
+    -   Each repo exposes its documentation as a **Hugo Module**
+    -   All doc-related files live under `docs/`
+
+Each `docs/` directory is:
+ - a **Go module root** (`go.mod`)
+ - a **Hugo project root** (`hugo.yaml`)
+
+------------------------------------------------------------------------
+
+## Main site repository
+
+    main-site/
+      go.mod
+      hugo.yaml
+      content/
+      layouts/
+      assets/
+
+### hugo.yaml
+
+``` yaml
+module:
+  imports:
+    - path: github.com/your-org/framework/docs
+    - path: github.com/your-org/lib-foo/docs
+    - path: github.com/your-org/lib-bar/docs
+```
+
+------------------------------------------------------------------------
+
+## Framework documentation repository
+
+    framework/
+      docs/
+        go.mod
+        go.sum
+        hugo.yaml
+        content/
+          framework/
+            _index.md
+        layouts/
+        assets/
+
+### docs/go.mod
+
+``` go
+module github.com/your-org/framework/docs
+go 1.22
+```
+
+### docs/hugo.yaml
+
+``` yaml
+module:
+  mounts:
+    - source: content
+      target: content/framework
+    - source: layouts
+      target: layouts
+    - source: assets
+      target: assets
+```
+
+------------------------------------------------------------------------
+
+## Library documentation repository (example: lib-foo)
+
+    lib-foo/
+      docs/
+        go.mod
+        hugo.yaml
+        content/
+          libraries/
+            foo/
+              _index.md
+
+### docs/go.mod
+
+``` go
+module github.com/your-org/lib-foo/docs
+go 1.22
+```
+
+### docs/hugo.yaml
+
+``` yaml
+module:
+  mounts:
+    - source: content
+      target: content/libraries/foo
+    - source: layouts
+      target: layouts
+    - source: assets
+      target: assets
+```
+
+------------------------------------------------------------------------
+
+## Content conventions
+ *	Always mount into namespaced sections:
+ *	`content/framework/...`
+ *	`content/libraries/<libname>/...`
+ *	Use `_index.md` at section roots to create proper landing pages
+ *	Avoid mounting directly to `content/` without a subdirectory
+
+------------------------------------------------------------------------
+
+## Optional: shared documentation UI module
+
+For shared shortcodes, partials, and styling:
+
+    docs-ui/
+    go.mod
+    hugo.yaml
+    layouts/
+    shortcodes/
+    partials/
+    assets/
+
+**docs-ui/hugo.yaml:**
+
+```yaml
+module:
+  mounts:
+  - source: layouts
+    target: layouts
+  - source: assets
+    target: assets
+```
+Import this module before content modules in the main site.
+
+------------------------------------------------------------------------
+
+## Local development
+
+Run documentation standalone from a repo:
+
+    cd framework
+    hugo server --source docs
+
+For multi-repo development, consider a go.work file to use local checkouts instead of remote module versions.
+
+------------------------------------------------------------------------
+
+## Key rules to follow
+ * docs/ is the only Hugo + Go module root in doc-providing repos
+ * Each docs module defines its own mounts
+ * The main site only imports modules
+ * Mount targets must be unique and namespaced
+ * Commit both go.mod and go.sum for reproducible builds
+
+------------------------------------------------------------------------
+
+## References
+ * Hugo Modules overview: https://gohugo.io/hugo-modules/
+ * Hugo module configuration: https://gohugo.io/configuration/module/
+ * Go modules reference: https://go.dev/ref/mod