diff --git a/README.md b/README.md index e98d8bc..cf7411e 100644 --- a/README.md +++ b/README.md @@ -2,57 +2,146 @@ This repository serves for three purposes: -1. The [Wiki](https://github.com/SpineEventEngine/documentation/wiki) provides documentation for developers contributing to the framework, Commiters. +1. The [Wiki][spine-wiki] provides documentation for developers contributing to the framework, Commiters. 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 submodule to the [spine.io](https://github.com/SpineEventEngine/spine.io) repository. +3. Storing documentation files that are added as a submodule to the [spine.io][spine-repo] repository. -We have repository for the code of [spine.io](https://spine.io) site. Issues there are for improving the site features. +We have repository for the code of [spine.io](https://spine.io) site. +Issues there are for improving the site features. -Tasks for the content of the [spine.io](https://spine.io) site should belong to issues of _this_ repository. +Tasks for the content of the [spine.io](https://spine.io) site should belong +to issues of _this_ repository. -This repository is made to be self-sustainable in terms of editing. A fully-fledged Jekyll site -has been set up for it. All the contents and links are working as intended. It allows making -changes more convenient for authors. To make it all possible this repository has its -own `docs` folder — otherwise all links would be broken. +This repository is made to be self-sustainable in terms of editing. +A fully-fledged Hugo site has been set up for it. All the contents and links +are working as intended. It allows making changes more convenient for authors. -# Prerequisites +## Prerequisites -1. Install Ruby. -2. Install the `bundler` tool. -3. Install the project dependencies by running `bundle install`. +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 + 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. -Now you should be able to run the documentation locally. +## Running the documentation locally -# Running the documentation locally +The project has two directories: -To build and launch the site on the local server: -``` -bundle exec jekyll serve +* `docs` – contains the documentation files along with all the necessary + JS and CSS files. This directory will be added to + `SpineEventEngine/SpineEventEngine.github.io` as a Hugo Module. +* `site` – contains the HTML and CSS files needed only to run the + documentation locally. + +To run the documentation locally: + +1. Navigate to the `site` directory. +2. Install project dependencies: + + ```shell + npm install + ``` + +3. Run the site locally: + + ```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 and run the `hugo serve` again: + +```shell +hugo mod clean --all ``` -# Code samples +## Theme updates + +This project uses several components 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. + +To get theme updates: + +1. Navigate to the `site` directory. +2. Clean the module cache: + + ```shell + hugo mod clean + ``` + +3. Update the Hugo Modules: + + ```shell + hugo mod get -u + ``` + +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. + +## Code samples The code samples used in the framework documentation are added using -the [`embed-code`](https://github.com/SpineEventEngine/embed-code) Jekyll subcommand. +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`](https://github.com/SpineEventEngine/spine.io/blob/master/_code/EMBEDDING.md) file. +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. -# Authoring +## Product release + +To release a new version of Spine documentation, see the [SPINE_RELEASE.md](SPINE_RELEASE.md). + +## Authoring For instructions on adding the content to the documentation, please see -the [`AUTHORING.md`](https://github.com/SpineEventEngine/spine.io/blob/master/AUTHORING.md) file. +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 `site/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 + authentication issues during submodules update. You can resolve it with this + command: -# Styles and assets + ```shell + git config --global --add url."git@github.com:".insteadOf "https://github.com/" + ``` -Styles were placed inside the `_sass` folder. And were separated into two import files: -- `docs.scss` — contains styles responsible for the appearance of the documentation. -Should be imported into the main spine.io site. -- `docs-common.scss` — contains styles that should only be used to build this site. -They are responsible for the common site layout and should not be imported into -the main spine.io site to not override or duplicate styles there. +2. If you are getting the `unknown revision upgrade` error when trying to get + theme updates, clean the module cache: -The `_css`, `_favicons`, and `_fonts` have been configured not to be built in the main repository. + ```shell + hugo mod clean --all + ``` -The images should be placed inside `img/docs` folder to be automatically included in the main site -and avoid accidental overrides for files with the same name. +[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 +[embed-code]: https://github.com/SpineEventEngine/embed-code/tree/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 diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md new file mode 100644 index 0000000..ed6b626 --- /dev/null +++ b/SPINE_RELEASE.md @@ -0,0 +1,168 @@ +Release new version of the documentation +======== + +**Table of Contents** +* [Release major version](#release-major-version) + * [Release steps](#release-steps) + * [URLs](#urls) + +## Release major version + +This site supports documentation versioning. All links within the +documentation are rendered automatically. + +The versions are managed in the `docs/data/versions.yml` file. + +```yml +- short: "1" + full: 1.9.0 + path: docs + is_main: true + switcher: + visible: false + item_visible: false +- short: "2" + full: 2.0.0 + path: docs/2 + switcher: + visible: false + item_visible: false +``` + +Where: + +* `short` shows the major version number, which will be used primarily for the link generation. +* `full` the full version that will be visible in the version switcher. +* `path` will be used when generating links inside a documentation version. +* `is_main` the optional flag that marks the current main version. +* `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 +└── docs + ├── 1 + │ ├── 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. + +``` +data +└── docs + ├── 1 + │ └── sidenav.yml + └── 2 + └── sidenav.yml +``` + +### Release steps + +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` as the main version, + the config should be updated as follows: + + ```yml + - short: "1" + full: 1.9.0 + path: docs # Change the path from `docs` to `docs/1`. + is_main: true # Change the flag to `false` or delete the line. + switcher: + visible: false + item_visible: false + - short: "2" + full: 2.0.0-eap # Change the version to `2.0.0` if needed. + path: docs/2 # Change the path from `docs/2` to `docs`. + is_main: false # Set `is_main` as `true`. + switcher: + visible: false + item_visible: false + ``` + +4. Update the `site/config/_default/hugo.toml` to make the version `2` as main. + + - Navigate to the end of the file to the section "Version control config". + - Find the `path` parameters and update as follows: + ``` + path = '{/docs/1}' -> path = '{/docs/2}' + path = '{/docs/1/**}' -> path = '{/docs/2/**}' + ``` + + Now the version `2` will be available at the `/docs/` URL and + will be opened by default. + +5. Commit and push the new version release. + +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 + +All URLs inside `content/docs//` are automatically managed +according to the current documentation version. + +Use links in documentation as follows, without including a version: + +`[Requirements](docs/guides/requirements/)`. + +Please note: + +* All internal links **must not** start with a slash. +* Each link should **end with a slash** to prevent unnecessary redirects. + +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`. + +To render the current documentation full version inside API URL, +use `{{% version %}}` shortcode: + +```markdown +[CoreJvm]({{% version %}}) + +[CoreJvm {{% version %}}]({{% get-site-data "spine.core_jvm_repo" %}}/index.html) +``` + +Will be rendered as: + +```html +CoreJvm + +CoreJvm 1.9.0 +``` + +Where: + +* {{% get-site-data "spine.core_jvm_repo" %}} will apply the `core_jvm_repo` + from the `data/spine.yml` file. +* {{% version %}} adds the full version of the current page -> `1.9.0`, or `2.0.0`. + +To provide a specific version for example in FAQ or Release Notes, use: + +```markdown +{{% version "1" %}} +``` + +It will always render the latest “full” version of `1`, for example now it is `1.9.0`. diff --git a/docs/content/docs/1/examples/_index.md b/docs/content/docs/1/examples/_index.md index 8b67c16..bc7063f 100755 --- a/docs/content/docs/1/examples/_index.md +++ b/docs/content/docs/1/examples/_index.md @@ -13,7 +13,7 @@ Please see the selected list of the examples with the descriptions below. ## Java - [Hello World]({{% get-site-data "spine.examples" %}}/hello/) — a minimal - client-server solution described in the [Quick Start](docs/guick-start/) guide. + client-server solution described in the [Quick Start](docs/quick-start/) guide. - [Blog]({{% get-site-data "spine.examples" %}}/blog/) — shows server-side functionality of a simple blog. - [Kanban]({{% get-site-data "spine.examples" %}}/kanban/) — shows orchestrating diff --git a/docs/content/docs/1/guides/start-new-project.md b/docs/content/docs/1/guides/start-new-project.md index d9b48c5..18a5868 100755 --- a/docs/content/docs/1/guides/start-new-project.md +++ b/docs/content/docs/1/guides/start-new-project.md @@ -269,4 +269,4 @@ Opt for smaller, fine-graded Pull Requests instead of cluttered and complicated [EventStorming]: https://eventstorming.com "Learn more about EventStorming" [UbiquitousLanguage]: https://martinfowler.com/bliki/UbiquitousLanguage.html "Learn more about the Ubiquitous Language" [ReactiveDDD]: https://www.infoq.com/presentations/reactive-ddd/ "Check out the Reactive DDD presentation" -[VaughnVernon]: https://vaughnvernon.co/ +[VaughnVernon]: https://vaughnvernon.com/ diff --git a/docs/layouts/_partials/docs/components/sidenav/category.html b/docs/layouts/_partials/docs/components/sidenav/category.html index a4b1d25..b3b617c 100644 --- a/docs/layouts/_partials/docs/components/sidenav/category.html +++ b/docs/layouts/_partials/docs/components/sidenav/category.html @@ -26,11 +26,12 @@ {{ $page := .page_context }} {{ $item := .item_context }} +{{ $isActive := .is_active | default false }} {{ $currentCategory := partial "functions/get-doc-category.html" $page }} {{ $categoryKey := $item.key }} {{ $id := print $categoryKey "-category" }} -{{ $isActive := eq $currentCategory $categoryKey }} +{{ $isActive = or (eq $currentCategory $categoryKey) $isActive }}