From 7fedac1a25d416fb868495ac74b336dc56451874 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 12 Feb 2026 17:20:43 +0100 Subject: [PATCH 1/6] Update guides --- README.md | 91 ++++++++++++++-------- SPINE_RELEASE.md | 196 ++++++++++++++++++++++++++++++----------------- 2 files changed, 185 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index 74eac1f..2223ef0 100644 --- a/README.md +++ b/README.md @@ -22,22 +22,20 @@ are working as intended. It allows making changes more convenient for authors. 2. [Go][go] `1.12` or newer. 3. [Node.js][nodejs] `18+`. 4. [Hugo Extended][hugo-quick-start] in version `v0.150.0` or higher. -5. Access to the [`site-commons`][site-commons] repository — to download the theme. ## Configuration -1. Make sure [SSH][site-commons-ssh] configured correctly and the passphrase is stored in the keychain. -2. Install project dependencies from the `site` directory by running `npm install`. +1. Install project dependencies from the `docs/_preview` directory by running `npm install`. ## Running the documentation locally The project has two directories: -* `docs` – contains the documentation files along with all the necessary - JS and CSS files. This directory will be added to +* `docs` – contains the documentation files along with all the necessary + page JS and images. This directory will be added to `SpineEventEngine/SpineEventEngine.github.io` as a Hugo Module. -* `docs/_preview` – contains the HTML and CSS files needed only to run the - documentation locally. +* `docs/_preview` – contains the setup needed only to run the + documentation locally. To build and launch the site on the local server: @@ -72,8 +70,8 @@ Then run the `hugo serve` again. ## Theme updates -This project uses several components from the [`site-commons`][site-commons] -Hugo theme. +This project uses components, layouts, and styles from the +[`site-commons`][site-commons] Hugo theme. Please note that if you update a theme with any critical changes, it must also be updated in the main `spine.io` site repository. @@ -90,11 +88,60 @@ To get theme updates: 3. Update the Hugo Modules: ```shell - hugo mod get -u + hugo mod get -u github.com/SpineEventEngine/site-commons ``` 4. Commit and push changes from `go.mod` and `go.sum` files. - In the `go.sum` file keep only two last records to avoid file cluttering. + In the `go.sum` file, keep only the two required entries for each theme to avoid file clutter. + +## Other documentation modules + +This repository is set up as a documentation aggregator. +That means it can pull documentation from other repositories and build +everything together into one site with the common side-navigation. + +### Add a new documentation module + +1. Open `docs/hugo.toml`. +2. Add the module to the `module.imports` list. +3. Update `moduleOrder` to control how modules appear in the sidenav. + By default, all modules are rendered in alphabetical order. + +The config example: + +```toml +[params] + # Specifies the order of the sidenav modules. + moduleOrder = ["framework", "validation", "compiler"] + +[module] + [[module.imports]] + path = 'github.com/SpineEventEngine/validation/docs' + disable = false + [[module.imports]] + path = 'github.com/SpineEventEngine/framework/docs' + disable = false + [[module.imports]] + path = 'github.com/SpineEventEngine/compiler/docs' + disable = false +``` + +Setting `disable = true` temporarily excludes a module from building without +removing its config. + +### Get documentation module updates + +1. Navigate to the `docs/_preview` directory. +2. Update the needed module: + ```shell + hugo mod get -u github.com/SpineEventEngine/validation/docs + ``` + + or update all the modules recursively (including the `site-commons`): + + ```shell + hugo mod get -u ./... + ``` ## Code samples @@ -127,27 +174,10 @@ To release a new version of Spine documentation, see the [SPINE_RELEASE.md](SPIN For instructions on adding the content to the documentation, please see the [`AUTHORING.md`][authoring-guide] file. -## Styles and assets - -The documentation related styles are placed inside `docs/assets/scss`. -The `docs` directory will be automatically added to the main site using Hugo Modules. - -There are two main import files: - -* `docs-common.scss` — contains the common styles that are also necessary for - the `SpineEventEngine/SpineEventEngine.github.io` repository. To not duplicate - global variables and layout styles, import the file in the main repository - _at the top_ of the `main.scss` -* `docs.scss` — contains styles responsible for the appearance of the documentation. - Should be imported into the `main.scss` of the `spine.io` site as well. - -Styles needed only for running the documentation locally are located -in `docs/_preview/assets/scss`. They will not be available on `spine.io`. - ## Troubleshooting 1. If you are getting the terminal `prompts disabled error` when trying to get - theme updates, make sure you have allowed 2FA to do its job. Also if you have + theme updates, make sure you have allowed 2FA to do its job. Also, if you have authentication issues during submodules update. You can resolve it with this command: @@ -165,8 +195,7 @@ in `docs/_preview/assets/scss`. They will not be available on `spine.io`. [go]: https://go.dev/doc/install [nodejs]: https://nodejs.org/en/download/current [hugo-quick-start]: https://gohugo.io/getting-started/quick-start/#step-1-install-hugo -[site-commons]: https://github.com/TeamDev-Ltd/site-commons -[site-commons-ssh]: https://github.com/TeamDev-Ltd/site-commons/tree/master?tab=readme-ov-file#configure-go-to-use-ssh-for-github +[site-commons]: https://github.com/SpineEventEngine/site-commons [embed-code]: https://github.com/SpineEventEngine/embed-code-go [authoring-guide]: https://github.com/SpineEventEngine/SpineEventEngine.github.io/blob/master/AUTHORING.md [spine-repo]: https://github.com/SpineEventEngine/SpineEventEngine.github.io diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md index 8d7c4cd..0e1371c 100644 --- a/SPINE_RELEASE.md +++ b/SPINE_RELEASE.md @@ -2,33 +2,63 @@ Release new version of the documentation ======== **Table of Contents** +* [Version configuration](#version-configuration) + * [Content](#content) + * [Sidenav](#sidenav) * [Release new version](#release-new-version) - * [Release steps](#release-steps) - * [URLs](#urls) + * [Change the current main version](#change-the-current-main-version) +* [URLs](#urls) -## Release new version +## Version configuration + +This site supports documentation versioning. All links within the documentation +are rendered automatically. + +Each documentation module manages its versions in its own `docs/data/versions.yml` file. +The structure is the same for all modules, but the top-level key must match the module name. + +In the current repository, versions are defined under the `docs` key: -This site supports documentation versioning. All links within the -documentation are rendered automatically. +```yml +docs: + - version_id: "1" + label: 1.9.0 + content_path: docs + route_url: docs + is_main: true + switcher: + visible: false + item_visible: false + + - version_id: "2" + label: 2.0.0 + content_path: docs/2 + route_url: docs/2 + switcher: + visible: false + item_visible: false +``` -The versions are managed in the `docs/data/versions.yml` file. +In the `validation` repository: ```yml -- version_id: "1" - label: 1.9.0 - content_path: docs/1 - route_url: docs - is_main: true - switcher: - visible: false - item_visible: false -- version_id: "2-0-x" - label: 2.0.x - content_path: docs/2-0-x - route_url: docs/2-0-x - switcher: - visible: false - item_visible: false +validation: + - version_id: "2-0-0-snapshot" + label: 2.0.0-SNAPSHOT + content_path: docs/validation + route_url: docs/validation + is_main: true + switcher: + visible: false + item_visible: false + + - version_id: "2-0-x" + label: 2.0.x + content_path: docs/validation/2-0-x + route_url: docs/validation/2-0-x + switcher: + visible: false + item_visible: false ``` Where: @@ -41,84 +71,108 @@ Where: * `switcher`: * `visible` – specifies whether the version switcher will be visible on the page. * `item_visible` – specifies whether the version will be available in the switcher dropdown. - -The `switcher` component is under development. -The documentation content should be created under the `content//` directory. -Note that the current main version is also placed under its `version` directory. +### Content + +The documentation content should be placed under `content/docs//` directory. + +For the main version, content can either be under its version directory or at +the root – this is controlled by the `content_path`. + +For example if the main version is in the root: ``` content └── docs - ├── 1 - │ ├── client-libs - │ ├── quick-start - │ └── _index.md - └── 2-0-x + ├── client-libs + ├── quick-start + ├── _index.md + └── 2 ├── client-libs ├── quick-start └── _index.md ``` -Also, each version should have its own `sidenav` config inside -the `data/docs/` directory. - -For modules with documentation, the config should live in `data/docs//`. +In the `validation` repository: ``` -data +content └── docs - ├── 1 - │ └── sidenav.yml - └── 2-0-x - └── sidenav.yml + └── validation + ├── client-libs + ├── _index.md + └── 2-0-x + ├── client-libs + └── _index.md ``` -### Release steps +### Sidenav + +Each version should have its own sidenav configuration file, located either in: +- `data/docs//sidenav.yml` for this repository; +- `data/docs///sidenav.yml` for documentation modules in their corresponding repositories. + +## Release new version 1. Create a new directory for the documentation inside the `content/docs//`. 2. Create the `sidenav.yml` inside `data/docs//` directory. -3. Update the `data/versions.yml` config. - - For example, if you release the version `2-0-x` as the main version, - the config should be updated as follows: - - ```yml - - version_id: "1" - label: 1.9.0 - content_path: docs/1 - route_url: docs # Change the route from `docs` to `docs/1`. - is_main: true # Change the flag to `false` or delete the line. - switcher: - visible: false - item_visible: false - - version_id: "2-0-x" - label: 2.0.x - content_path: docs/2-0-x # Change the content path to `docs` if the documentation will be copied to the root. - route_url: docs/2-0-x # Change the route from `docs/2-0-x` to `docs`. - is_main: false # Set `is_main` as `true`. - switcher: - visible: false - item_visible: false - ``` - -4. Commit and push the new version release. +3. Add the new version to `data/versions.yml` config. + +### Change the current main version + +This flow applies to the current documentation repository. For modules, the same +steps must be done in the corresponding repository using the appropriate paths +for that module. + +This example shows how to switch from version 1 to version 2. + +The current main version can be located either in the root folder or in its +versioned folder and configured via `module.mounts`. + +1. If the main version is in the root, we also need to manually adjust folder structures: + - `content/docs/*` -> `content/docs/1/` + - `content/docs/2` -> `content/docs` + +2. Update the version configuration in `docs/data/versions.yml`: + + ```yml + docs: + - version_id: "1" + label: 1.9.0 + content_path: docs # Change the path from `docs` to `docs/1`. + route_url: docs # Change the route from `docs` to `docs/1`. + is_main: true # Change the flag to `false` or delete the line. + switcher: + visible: false + item_visible: false + - version_id: "2" + label: 2.0.0 + content_path: docs/2 # Change the content path to `docs` if the documentation will be copied to the root. + route_url: docs/2 # Change the route from `docs/2` to `docs`. + is_main: false # Set `is_main` as `true`. + switcher: + visible: false + item_visible: false + ``` + +Now the version 2 will be available at the `https://spine.io/docs/` URL. Get updates into the main website: 1. Go to the [`SpineEventEngine.github.io`](https://github.com/SpineEventEngine/SpineEventEngine.github.io) repository. 2. Get theme updates `hugo mod get -u github.com/SpineEventEngine/documentation/docs`. -3. Update the `config/_default/hugo.toml` to make the version `2` as main. -### URLs +## URLs All URLs inside `content/docs//` are automatically managed according to the current documentation version. -Use links in documentation as follows, without including a version: +Use links in documentation as follows, without including a version. + +For this repository: `[Requirements](docs/guides/requirements/)`. -`[Requirements](docs/guides/requirements/)`. +In the `validation` repository: `[Requirements](docs/validation/guides/requirements/)`. Please note: @@ -152,7 +206,7 @@ Where: * {{% get-site-data "repositories.core_jvm_repo" %}} will apply the `core_jvm_repo` from the `site-commons` -> `data/repositories.yml` file. -* {{% version %}} adds the full version of the current page -> `1.9.0`, or `2.0.0`. +* {{% version %}} adds the full version label of the current page -> `1.9.0`, or `2.0.0`. To provide a specific version for example in FAQ or Release Notes, use: @@ -160,4 +214,4 @@ To provide a specific version for example in FAQ or Release Notes, use: {{% version "1" %}} ``` -It will always render the latest “full” version of `1`, for example now it is `1.9.0`. +It will always render the latest “full” label version of `1`, for example now it is `1.9.0`. From bf9f261c76d98156635ed0880a4843364b6d1ba3 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 12 Feb 2026 17:35:16 +0100 Subject: [PATCH 2/6] Clean up --- SPINE_RELEASE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md index 0e1371c..cc939a6 100644 --- a/SPINE_RELEASE.md +++ b/SPINE_RELEASE.md @@ -129,7 +129,8 @@ This example shows how to switch from version 1 to version 2. The current main version can be located either in the root folder or in its versioned folder and configured via `module.mounts`. -1. If the main version is in the root, we also need to manually adjust folder structures: +1. If the main version is in the root, we also need to manually adjust folder + structures and move: - `content/docs/*` -> `content/docs/1/` - `content/docs/2` -> `content/docs` From d31ab9af82aad3584e7959f35409083a0331cdd6 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Fri, 13 Feb 2026 10:34:07 +0100 Subject: [PATCH 3/6] Improve guides --- SPINE_RELEASE.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md index cc939a6..5c22fc1 100644 --- a/SPINE_RELEASE.md +++ b/SPINE_RELEASE.md @@ -74,7 +74,7 @@ Where: ### Content -The documentation content should be placed under `content/docs//` directory. +The documentation content should be placed under `content/docs//` directory. For the main version, content can either be under its version directory or at the root – this is controlled by the `content_path`. @@ -109,8 +109,8 @@ content ### Sidenav Each version should have its own sidenav configuration file, located either in: -- `data/docs//sidenav.yml` for this repository; -- `data/docs///sidenav.yml` for documentation modules in their corresponding repositories. +- `data/docs//sidenav.yml` for this repository; +- `data/docs///sidenav.yml` for documentation modules in their corresponding repositories. ## Release new version @@ -166,7 +166,7 @@ Get updates into the main website: ## URLs -All URLs inside `content/docs//` are automatically managed +All URLs inside `content/docs//` are automatically managed according to the current documentation version. Use links in documentation as follows, without including a version. @@ -185,6 +185,8 @@ The link above will be automatically rendered as: - `"/docs/guides/requirements/"` – for main version. - `"/docs/2/guides/requirements/"` – for the version `2`. - `"/docs/3/guides/requirements/"` – for the version `3`. +- `"/docs/validation/guides/requirements/"` – for main version. +- `"/docs/validation/2-0-x/guides/requirements/"` – for the version `2-0-x`. To render the current documentation full version inside API URL, use `{{% version %}}` shortcode: @@ -207,9 +209,9 @@ Where: * {{% get-site-data "repositories.core_jvm_repo" %}} will apply the `core_jvm_repo` from the `site-commons` -> `data/repositories.yml` file. -* {{% version %}} adds the full version label of the current page -> `1.9.0`, or `2.0.0`. +* {{% version %}} adds the version label of the current page -> `1.9.0`, or `2.0.0`. -To provide a specific version for example in FAQ or Release Notes, use: +To provide a specific version for example in FAQ or Release Notes, provide the `version_id`: ```markdown {{% version "1" %}} From bcf13299864e543c197f25936e745692212e59bf Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Fri, 13 Feb 2026 14:50:04 +0100 Subject: [PATCH 4/6] Clean up --- SPINE_RELEASE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md index 5c22fc1..5543bd8 100644 --- a/SPINE_RELEASE.md +++ b/SPINE_RELEASE.md @@ -211,7 +211,7 @@ Where: from the `site-commons` -> `data/repositories.yml` file. * {{% version %}} adds the version label of the current page -> `1.9.0`, or `2.0.0`. -To provide a specific version for example in FAQ or Release Notes, provide the `version_id`: +To use a specific version for example in FAQ or Release Notes, provide the `version_id`: ```markdown {{% version "1" %}} From 4df48daff13715e9a4729682c2495e27c77631aa Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Mon, 16 Feb 2026 10:59:13 +0100 Subject: [PATCH 5/6] Get the latest theme updates --- docs/_preview/go.mod | 2 +- docs/_preview/go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/_preview/go.mod b/docs/_preview/go.mod index 88ebfb1..0787e19 100644 --- a/docs/_preview/go.mod +++ b/docs/_preview/go.mod @@ -3,7 +3,7 @@ module github.com/SpineEventEngine/documentation/docs/_preview go 1.22.0 require ( - github.com/SpineEventEngine/site-commons v0.0.0-20260212124406-a312b6eab34c // indirect + github.com/SpineEventEngine/site-commons v0.0.0-20260213171221-c1157022c545 // indirect github.com/SpineEventEngine/validation/docs v0.0.0-20260205202311-181ba8844107 // indirect github.com/gohugoio/hugo-mod-bootstrap-scss/v5 v5.20300.20400 // indirect github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2 v2.21100.20000 // indirect diff --git a/docs/_preview/go.sum b/docs/_preview/go.sum index 26dfc04..561c7cb 100644 --- a/docs/_preview/go.sum +++ b/docs/_preview/go.sum @@ -1,5 +1,5 @@ -github.com/SpineEventEngine/site-commons v0.0.0-20260212124406-a312b6eab34c h1:NtLNdAfuL3uQB+8cU5sBzx+2tlRXlxd1+76okBWj0Ek= -github.com/SpineEventEngine/site-commons v0.0.0-20260212124406-a312b6eab34c/go.mod h1:tkAl4StIREKmz9r5PiJtuDhvwMMkFXKWcaTyxhIikho= +github.com/SpineEventEngine/site-commons v0.0.0-20260213171221-c1157022c545 h1:NI8WYIfw5yv/FXNhxG2zgiU3J0YChheRQugosxkopoc= +github.com/SpineEventEngine/site-commons v0.0.0-20260213171221-c1157022c545/go.mod h1:tkAl4StIREKmz9r5PiJtuDhvwMMkFXKWcaTyxhIikho= github.com/SpineEventEngine/validation/docs v0.0.0-20260205202311-181ba8844107 h1:2DHRIwwLudP6l3Kh7Nd4KR4uXcsDtIAXE9adW68ivME= github.com/SpineEventEngine/validation/docs v0.0.0-20260205202311-181ba8844107/go.mod h1:STHyjXejVvPmfrxujfDvhofmjg55mMk+fwI3TVL0b4Y= github.com/gohugoio/hugo-mod-bootstrap-scss/v5 v5.20300.20400 h1:L6+F22i76xmeWWwrtijAhUbf3BiRLmpO5j34bgl1ggU= From 4fa4d481e3f3e794d5ceadbf6fd652a924e5d9f5 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Mon, 16 Feb 2026 10:59:19 +0100 Subject: [PATCH 6/6] Update `README.md` --- README.md | 4 ++++ SPINE_RELEASE.md | 10 ++++++---- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2223ef0..5d41275 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,9 @@ removing its config. hugo mod get -u ./... ``` +3. Commit and push changes from `go.mod` and `go.sum` files. +4. Get documentation updates to the `SpineEventEngine.github.io` according to the [guide][spine-docs-update]. + ## Code samples The code samples used in the framework documentation are added using @@ -200,3 +203,4 @@ the [`AUTHORING.md`][authoring-guide] file. [authoring-guide]: https://github.com/SpineEventEngine/SpineEventEngine.github.io/blob/master/AUTHORING.md [spine-repo]: https://github.com/SpineEventEngine/SpineEventEngine.github.io [spine-wiki]: https://github.com/SpineEventEngine/documentation/wiki +[spine-docs-update]: https://github.com/SpineEventEngine/SpineEventEngine.github.io/blob/master/README.md#documentation diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md index 5543bd8..bf4b3ff 100644 --- a/SPINE_RELEASE.md +++ b/SPINE_RELEASE.md @@ -192,17 +192,19 @@ To render the current documentation full version inside API URL, use `{{% version %}}` shortcode: ```markdown -[CoreJvm]({{% version %}}) -[CoreJvm {{% version %}}]({{% get-site-data "repositories.core_jvm_repo" %}}/index.html) + +[Introduction](docs/{{% version %}}/) + +[Hello World v{{% version %}}]({{% get-site-data "repositories.examples" %}}/hello/) ``` Will be rendered as: ```html -CoreJvm +Introduction -CoreJvm 1.9.0 +Hello World v1.9.0 ``` Where: