diff --git a/.gitignore b/.gitignore index 1c21d74..3d7b70f 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,9 @@ node_modules # Used to control concurrency between multiple Hugo instances docs/_preview/.hugo_build.lock +# Hugo build output +docs/_site/ + # Needed for navigation/intellisense help inside code editors jsconfig.json diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml new file mode 100644 index 0000000..df7825d --- /dev/null +++ b/.idea/inspectionProfiles/Project_Default.xml @@ -0,0 +1,6 @@ + + + + \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ad8bf44 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,74 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this repo is + +A Hugo-based documentation source for [spine.io](https://spine.io). The `docs/` directory is consumed as a Hugo module by the `SpineEventEngine/SpineEventEngine.github.io` site. The `docs/_preview/` directory exists only to render the site locally — it is not shipped. + +## Prerequisites + +JDK 8 (x86_64), Go 1.22+ (per `docs/go.mod`), Node.js 18+, Hugo Extended `v0.150.0`+. The `embedCode` and `checkSamples` Gradle tasks hardcode `embed-code-macos` (ARM) from `docs/_bin/`; on an x86_64 Mac, invoke `embed-code-macos-x86_64` directly (see bypass snippet below) — the Gradle wrappers won't work. CI uses `embed-code-ubuntu` (the `check-samples` script branches on `$GITHUB_ACTIONS`). + +## Common commands + +Run from repo root: + +```shell +./gradlew :runSite # install deps + hugo server (local preview) +./gradlew :buildSite # install deps + hugo build (no server) +./gradlew :embedCode # update git submodules + embed code snippets into markdown +./gradlew :checkSamples # verify embedded snippets match source (CI uses this) +./gradlew :buildAll # build all included example projects via composite build +``` + +Bypassing Gradle (you must run the prerequisite steps yourself, or you'll skip what the Gradle tasks do): + +```shell +# equivalent to :runSite — installDependencies runs npm install via docs/_script/install-dependencies +./docs/_script/install-dependencies && cd docs/_preview && hugo server + +# equivalent to :embedCode — the script updates submodules before invoking the binary. +# Use ./embed-code-macos on ARM Macs, ./embed-code-macos-x86_64 on Intel Macs. +git submodule update --remote --merge --recursive +cd docs/_bin && ./embed-code-macos \ + -config-path="../_settings/v1.embed-code.yml" -mode="embed" +``` + +Each Gradle task is a thin wrapper around a script in `docs/_script/`. When debugging a task, read that script first. + +## Architecture + +### Two-directory split + +- `docs/` — content shipped as a Hugo module. Has its own `go.mod` (`github.com/SpineEventEngine/documentation/docs`) and `hugo.toml`. Everything outside `docs/` is build tooling. +- `docs/_preview/` — local preview rig. Its `hugo.toml` imports `../..` (the repo root) plus `github.com/SpineEventEngine/site-commons`. Edit `docs/_preview/hugo.toml` to enable/disable other doc modules (validation, compiler, framework) when previewing aggregation locally. + +### Theme and module aggregation + +Layouts/components come from the `site-commons` Hugo theme (pulled via Hugo Modules, not git submodules). The site is also a **documentation aggregator**: it imports docs from sibling repos (`SpineEventEngine/validation/docs`, `compiler/docs`, etc.) and renders them under a unified sidenav. `params.moduleOrder` in `hugo.toml` controls sidenav order; `disable = true` on a module import excludes it from the build. + +To pull theme/module updates: `cd docs/_preview && hugo mod clean && hugo mod get -u github.com/SpineEventEngine/site-commons` (or `./...` for all). Commit the resulting `go.mod`/`go.sum` changes — keep `go.sum` minimal (two entries per theme). + +### Code embedding (`docs/_code/`) + +Snippets in markdown pages are inserted by the [`embed-code-go`](https://github.com/SpineEventEngine/embed-code-go) tool, not written inline. + +- `docs/_code/examples/` — full example projects, each a **git submodule** of a `spine-examples/*` repo (airport, blog, hello, kanban, todo-list). The composite build in `settings.gradle.kts` includes `airport`, `hello`, and the local `samples` build. +- `docs/_code/samples/` — a local Gradle subproject (included as a composite build via `includeBuild("./docs/_code/samples")`) whose Java/Proto sources under `src/main/` are embedded as snippets into pages. When adding new snippets here, you may also need to update `samples/build.gradle` and its build will run as part of `:buildAll`. +- `docs/_settings/v1.embed-code.yml` — embed-code config (paths into `docs/_code` and `docs/content/docs/1`). + +Workflow: update snippet at source → `./gradlew :embedCode` → review the `.md`/`.html` diff → commit. After adding a new submodule under `docs/_code/examples/`, also register it in `settings.gradle.kts` (`includeBuild(...)`) and the project must expose a top-level `buildAll` Gradle task. + +### Content versioning + +Versions live side-by-side under `docs/content/docs//`, configured in `docs/data/versions.yml`. The `is_main` version may live at the root (`docs/content/docs/`) instead of in a `/` subdir — switching the main version requires moving directories *and* updating `content_path`/`route_url` in `versions.yml`. Each version also needs a sidenav at `docs/data/docs//sidenav.yml`. Full procedure: see `SPINE_RELEASE.md`. + +### Link conventions in markdown + +- Internal links must **not** start with `/` and **must** end with `/` (avoids redirects). The versioning system rewrites them, e.g. `docs/guides/requirements/` → `/docs/1.9.0/guides/requirements/` for main, `/docs/2/guides/...` for version 2. +- For the version label inside a URL, use `{{% version %}}` (current page's version) or `{{% version "1" %}}` (specific). For repo URLs, use `{{% get-site-data "repositories." %}}` — pulls from `site-commons`' `data/repositories.yml`. + +## Authoring guide + +The user-facing content authoring guide lives in the `SpineEventEngine.github.io` repo (`AUTHORING.md`), not here. diff --git a/README.md b/README.md index 5d41275..3fcef9f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This repository serves for three purposes: -1. The [Wiki][spine-wiki] provides documentation for developers contributing to the framework, Commiters. +1. The [Wiki][spine-wiki] provides documentation for developers contributing to the framework, Committers. 2. Gathering issues improving the documentation of the framework and tasks on writing articles at spine.io and other web resources. 3. Storing documentation files that are added as a Hugo module to the [spine.io][spine-repo] repository. @@ -19,7 +19,7 @@ are working as intended. It allows making changes more convenient for authors. ## Prerequisites 1. JDK 8 (x86_64). -2. [Go][go] `1.12` or newer. +2. [Go][go] `1.22` or newer (matches `docs/go.mod`). 3. [Node.js][nodejs] `18+`. 4. [Hugo Extended][hugo-quick-start] in version `v0.150.0` or higher. @@ -52,21 +52,25 @@ To build the site without running the server: Another way to run the site locally is to follow these steps: 1. Navigate to the `docs/_preview` folder. -2. Start the local server with this command: +2. Install Node dependencies (if you haven't already — see [Configuration](#configuration)): + + ```shell + npm install + ``` +3. Start the local server with this command: ```shell hugo server ``` If you receive a `permission denied` message, but you are sure that you have -all the rights to the [required repositories](#prerequisites), try clearing -the cache: +all the rights to the required repositories, try clearing the cache: ```shell hugo mod clean --all ``` -Then run the `hugo serve` again. +Then run the `hugo server` again. ## Theme updates diff --git a/docs/_bin/embed-code-macos b/docs/_bin/embed-code-macos index 035be58..6ff4302 100755 Binary files a/docs/_bin/embed-code-macos and b/docs/_bin/embed-code-macos differ diff --git a/docs/_bin/embed-code-macos-x86_64 b/docs/_bin/embed-code-macos-x86_64 index 5e2577c..545abc6 100755 Binary files a/docs/_bin/embed-code-macos-x86_64 and b/docs/_bin/embed-code-macos-x86_64 differ diff --git a/docs/_bin/embed-code-ubuntu b/docs/_bin/embed-code-ubuntu index ca362fe..fb0125c 100755 Binary files a/docs/_bin/embed-code-ubuntu and b/docs/_bin/embed-code-ubuntu differ diff --git a/docs/_preview/go.mod b/docs/_preview/go.mod index 9fb3881..77bcc49 100644 --- a/docs/_preview/go.mod +++ b/docs/_preview/go.mod @@ -4,7 +4,7 @@ go 1.22.0 require ( github.com/SpineEventEngine/site-commons v0.0.0-20260522171914-2a606d89558f // indirect - github.com/SpineEventEngine/validation/docs v0.0.0-20260205202311-181ba8844107 // indirect + github.com/SpineEventEngine/validation/docs v0.0.0-20260522175555-cf09b4c706ea // 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 github.com/twbs/bootstrap v5.3.8+incompatible // indirect diff --git a/docs/_preview/go.sum b/docs/_preview/go.sum index 807a319..cdf50f2 100644 --- a/docs/_preview/go.sum +++ b/docs/_preview/go.sum @@ -2,6 +2,8 @@ github.com/SpineEventEngine/site-commons v0.0.0-20260522171914-2a606d89558f h1:y github.com/SpineEventEngine/site-commons v0.0.0-20260522171914-2a606d89558f/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/SpineEventEngine/validation/docs v0.0.0-20260522175555-cf09b4c706ea h1:YEMSlr5KJXkZdK7epMSnN+6HSr2K41n8O3c8OhtF8pM= +github.com/SpineEventEngine/validation/docs v0.0.0-20260522175555-cf09b4c706ea/go.mod h1:4RnP1hlrfBI7ZlTsJkllaOEyluhzmz4mOBrRgbc/tts= github.com/gohugoio/hugo-mod-bootstrap-scss/v5 v5.20300.20400 h1:L6+F22i76xmeWWwrtijAhUbf3BiRLmpO5j34bgl1ggU= github.com/gohugoio/hugo-mod-bootstrap-scss/v5 v5.20300.20400/go.mod h1:uekq1D4ebeXgduLj8VIZy8TgfTjrLdSl6nPtVczso78= github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2 v2.21100.20000 h1:GZxx4Hc+yb0/t3/rau1j8XlAxLE4CyXns2fqQbyqWfs= diff --git a/docs/hugo.toml b/docs/hugo.toml index c3a814e..3539ed8 100644 --- a/docs/hugo.toml +++ b/docs/hugo.toml @@ -5,4 +5,3 @@ [module] [[module.imports]] path = 'github.com/SpineEventEngine/validation/docs' - disable = true