diff --git a/README.md b/README.md index 74eac1f..5d41275 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,63 @@ 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 ./... + ``` + +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 @@ -127,27 +177,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,9 +198,9 @@ 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 [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 8d7c4cd..bf4b3ff 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. -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. -The versions are managed in the `docs/data/versions.yml` file. +In the current repository, versions are defined under the `docs` key: ```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 +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 +``` + +In the `validation` repository: + +```yml +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,109 @@ 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 and move: + - `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 +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: @@ -130,34 +185,38 @@ 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: ```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: * {{% 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 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 use a specific version for example in FAQ or Release Notes, provide the `version_id`: ```markdown {{% 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`. diff --git a/docs/_preview/go.mod b/docs/_preview/go.mod index f9f0b53..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-20260213134955-23ac9f4c75e1 // 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 aac0610..561c7cb 100644 --- a/docs/_preview/go.sum +++ b/docs/_preview/go.sum @@ -1,5 +1,5 @@ -github.com/SpineEventEngine/site-commons v0.0.0-20260213134955-23ac9f4c75e1 h1:CjiYIoV9oMLf55RtAryccy8EXy6Jjrvd7iLTp3Xzou4= -github.com/SpineEventEngine/site-commons v0.0.0-20260213134955-23ac9f4c75e1/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=