Consolidate the docs directory

.gitignore

@@ -1,15 +1,15 @@
 # Hugo cache files
-/site/resources
+docs/_site/resources
 public
 
 # Cache folder for Hugo Modules
-/site/_vendor
+docs/_site/_vendor
 
 # Node modules
 node_modules
 
 # Used to control concurrency between multiple Hugo instances
-/site/.hugo_build.lock
+docs/_site/.hugo_build.lock
 
 # Needed for navigation/intellisense help inside code editors
 jsconfig.json

.gitmodules

@@ -1,15 +1,15 @@
-[submodule "_code/examples/airport"]
-	path = _code/examples/airport
+[submodule "docs/_code/examples/airport"]
+	path = docs/_code/examples/airport
 	url = https://github.com/spine-examples/airport.git
-[submodule "_code/examples/blog"]
-	path = _code/examples/blog
+[submodule "docs/_code/examples/blog"]
+	path = docs/_code/examples/blog
 	url = https://github.com/spine-examples/blog.git
-[submodule "_code/examples/hello"]
-	path = _code/examples/hello
+[submodule "docs/_code/examples/hello"]
+	path = docs/_code/examples/hello
 	url = https://github.com/spine-examples/hello.git
-[submodule "_code/examples/kanban"]
-	path = _code/examples/kanban
+[submodule "docs/_code/examples/kanban"]
+	path = docs/_code/examples/kanban
 	url = https://github.com/spine-examples/kanban.git
-[submodule "_code/examples/todo-list"]
-	path = _code/examples/todo-list
+[submodule "docs/_code/examples/todo-list"]
+	path = docs/_code/examples/todo-list
 	url = https://github.com/spine-examples/todo-list.git

_code/EMBEDDING.md → EMBEDDING.md

@@ -16,11 +16,11 @@ available as a binary executable written in Go.
 1. Open [embed-code][embed-code-repo] repository.
 2. Switch to the `embed-code-go` branch.
 3. Go to the `embed-code-go/bin` and download an executable suitable for you OS.
-4. Put it in the `_code` directory of this repository.
+4. Put it in the `docs/_bin` directory of this repository.
 
 ### Download code snippets
 
-The `_code` directory contains the source code, which is embedded into the pages 
+The `docs/_code` directory contains the source code, which is embedded into the pages 
 of the spine.io documentation:
 
 * `examples` — contains examples selected from the repositories under `spine-examples`
@@ -35,7 +35,7 @@ git submodule update --remote
 
 ### Config files
 
-As for now, there is the `_code/config-v1.yml` config file for Spine v1.
+As for now, there is the `docs/_settings/v1.embed-code.yml` config file for Spine v1.
 
 ## Usage patterns
 
@@ -53,13 +53,13 @@ to the documentation files using the tool. The most important points here are:
 1. Update the snippet in the appropriate repository.
 2. Make sure it builds successfully.
 3. Go to the `SpineEventEngine/documentation` project.
-4. Navigate to the `_code` directory.
+4. Navigate to the `docs/_bin` directory.
 5. Execute the binary based on your operating system and architecture: 
    `./embed-code-<os> -config-path="config-of-your-choice.yml" -mode="embed"`.
 
    For example:
    ```shell
-   ./embed-code-macos -config-path="config-v1.yml" -mode="embed"
+   ./embed-code-macos -config-path="../_settings/v1.embed-code.yml" -mode="embed"
    ```
 
 ### Adding a new example project
@@ -76,29 +76,29 @@ to the documentation files using the tool. The most important points here are:
 2. Add the example code as a submodule for this project:
 
    ```bash
-   git submodule add https://github.com/spine-examples/<example-name> _code/examples/<example-name>
+   git submodule add https://github.com/spine-examples/<example-name> docs/_code/examples/<example-name>
    ```
-   Please make sure the new submodule goes under the `_code/examples` directory, as shown in
-   the command line template above.
+   Please make sure the new submodule goes under the `docs/_code/examples` directory, 
+   as shown in the command line template above.
 
 3. Include the build of the added project into the [`settings.gradle.kts`](settings.gradle.kts)
    file.
 4. Insert code embedding directives where needed in the `docs/content/` folder.
-5. Navigate to the `_code` directory.
+5. Navigate to the `docs/_bin` directory.
 6. Execute: `./embed-code -config-path="config-of-your-choice.yml" -mode="embed"`.
 
    For example:
    ```shell
-   ./embed-code-macos -config-path="config-v1.yml" -mode="embed"
+   ./embed-code-macos -config-path="../_settings/v1.embed-code.yml" -mode="embed"
    ```
 
 ### Adding a new small piece
 
-1. Add the code under `_code/samples/src` directory.
+1. Add the code under `docs/_code/samples/src` directory.
 2. Make sure tests for the new code pass.
 3. Add the new piece using the [`embed-code` guide][embed-code-readme].
 4. Include the build of the added project into the [`settings.gradle.kts`](settings.gradle.kts)
-   file `includeBuild("./_code/samples")`.
+   file `includeBuild("./docs/_code/samples")`.
 
 ### How to remove a code snippet?
 
@@ -109,7 +109,7 @@ to the documentation files using the tool. The most important points here are:
 
    For example:
    ```shell
-   ./embed-code-macos -config-path="config-v1.yml" -mode="check"
+   ./embed-code-macos -config-path="../_settings/v1.embed-code.yml" -mode="check"
    ```
 
 ## Troubleshooting

README.md

@@ -36,7 +36,7 @@ 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
   `SpineEventEngine/SpineEventEngine.github.io` as a Hugo Module.
-* `site` – contains the HTML and CSS files needed only to run the
+* `docs/_site` – contains the HTML and CSS files needed only to run the
   documentation locally.
 
 To build and launch the site on the local server:
@@ -53,7 +53,7 @@ To build the site without running the server:
 
 Another way to run the site locally is to follow these steps:
 
-1. Navigate to the `site` folder.
+1. Navigate to the `docs/_site` folder.
 2. Start the local server with this command:
 
    ```shell
@@ -80,7 +80,7 @@ be updated in the main `spine.io` site repository.
 
 To get theme updates:
 
-1. Navigate to the `site` directory.
+1. Navigate to the `docs/_site` directory.
 2. Clean the module cache:
 
    ```shell
@@ -101,8 +101,8 @@ To get theme updates:
 The code samples used in the framework documentation are added using
 the [`embed-code`][embed-code] tool (Go version).
 
-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.
+The code resides under the `docs/_code` directory. For instructions on embedding 
+the code into the pages, please see the [`EMBEDDING.md`](EMBEDDING.md) file.
 
 Please note that the following part of the script requires an ARM-based Mac.
 
@@ -142,7 +142,7 @@ There are two main import files:
   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`.
+in `docs/_site/assets/scss`. They will not be available on `spine.io`.
 
 ## Troubleshooting
 

build.gradle.kts

@@ -29,36 +29,36 @@
  */
 task<Exec>("runSite") {
     dependsOn("installDependencies")
-    commandLine("./_script/hugo-serve")
+    commandLine("./docs/_script/hugo-serve")
 }
 
 /**
  * Builds the site without starting the server.
  */
 task<Exec>("buildSite") {
     dependsOn("installDependencies")
-    commandLine("./_script/hugo-build")
+    commandLine("./docs/_script/hugo-build")
 }
 
 /**
  * Installs the Node.js dependencies required for building the site.
  */
 task<Exec>("installDependencies") {
-    commandLine("./_script/install-dependencies")
+    commandLine("./docs/_script/install-dependencies")
 }
 
 /**
  * Embeds the code samples into pages of the site.
  */
 task<Exec>("embedCode") {
-    commandLine("./_script/embed-code")
+    commandLine("./docs/_script/embed-code")
 }
 
 /**
  * Verifies that the source code samples embedded into the pages are up-to-date.
  */
 task<Exec>("checkSamples") {
-    commandLine("./_script/check-samples")
+    commandLine("./docs/_script/check-samples")
 }
 
 /**

_script/check-samples → docs/_script/check-samples

@@ -39,8 +39,8 @@ elif [ -f ${BASH_RC} ]; then
   . ${BASH_RC}
 fi
 
-# Navigate to the folder with samples.
-cd _code
+# Navigate to the folder with embed-code binaries.
+cd docs/_bin
 
 # Use the Ubuntu binary for GitHub Actions and macOS binary in other cases.
 if [ "$GITHUB_ACTIONS" = "true" ]; then
@@ -52,4 +52,4 @@ else
 fi
 
 # Check code samples.
-"$TOOL" -config-path="config-v1.yml" -mode="check"
+"$TOOL" -config-path="../_settings/v1.embed-code.yml" -mode="check"

_script/embed-code → docs/_script/embed-code

@@ -37,11 +37,11 @@ elif [ -f ${BASH_RC} ]; then
   . ${BASH_RC}
 fi
 
-# Ensure `_code` files are fetched.
+# Ensure `docs/_code` files are fetched.
 git submodule update --remote --merge --recursive
 
-# Navigate to the folder with samples.
-cd _code
+# Navigate to the folder with embed-code binaries.
+cd docs/_bin
 
 # Update code samples.
-./embed-code-macos -config-path="config-v1.yml" -mode="embed"
+./embed-code-macos -config-path="../_settings/v1.embed-code.yml" -mode="embed"

_script/hugo-build → docs/_script/hugo-build

@@ -37,5 +37,5 @@ elif [ -f ${BASH_RC} ]; then
   . ${BASH_RC}
 fi
 
-cd site
+cd docs/_site
 hugo

_script/hugo-serve → docs/_script/hugo-serve

@@ -37,5 +37,5 @@ elif [ -f ${BASH_RC} ]; then
   . ${BASH_RC}
 fi
 
-cd site
+cd docs/_site
 hugo server

_script/install-dependencies → docs/_script/install-dependencies

@@ -38,5 +38,5 @@ elif [ -f ${BASH_RC} ]; then
   . ${BASH_RC}
 fi
 
-cd site
+cd docs/_site
 npm install

docs/_settings/v1.embed-code.yml

@@ -0,0 +1,5 @@
+code-path: "../_code"
+docs-path: "../content/docs/1"
+embed-mappings:
+  - code-path: "../_code"
+    docs-path: "../content/docs/1"

site/config/_default/hugo.toml → docs/_site/config/_default/hugo.toml

@@ -6,7 +6,7 @@ disableKinds = ['taxonomy', 'term']
 [module]
   # First theme has higher priority than later ones.
   [[module.imports]]
-    path = '../../docs'
+    path = '../..'
   [[module.imports]]
     path = 'github.com/TeamDev-Ltd/site-commons'
 

settings.gradle.kts

@@ -26,7 +26,7 @@
 
 rootProject.name = "spine-docs"
 
-includeBuild("./_code/samples")
+includeBuild("./docs/_code/samples")
 
-includeBuild("./_code/examples/airport")
-includeBuild("./_code/examples/hello")
+includeBuild("./docs/_code/examples/airport")
+includeBuild("./docs/_code/examples/hello")