Skip to content

EMBEDDING.md

Latest commit

 

History

History
125 lines (90 loc) · 4.53 KB

EMBEDDING.md

File metadata and controls

125 lines (90 loc) · 4.53 KB

Embedding code

We use the embed-code tool (Go version) to embed code snippets to markdown pages. Take a look on its README file to know how it works.

Prerequisites

Obtain embed-code executable

Firstly, we need to download the last available executable of embed-code. Originally, this tool was written as a plugin for Jekyll, but now it is also available as a binary executable written in Go.

  1. Open embed-code repository.
  2. Go to the bin directory and download an executable suitable for you OS.
  3. Put it in the docs/_bin directory of this repository.

Download code snippets

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 organization. These repositories are added to this project as Git submodules.
  • samples — smaller pieces of code embedded to the site.

To get the latest version of the code snippets, update the submodules:

git submodule update --remote

Config files

As for now, there is the docs/_settings/v1.embed-code.yml config file for Spine v1.

Usage patterns

First, update the code snippets, and then migrate the updated snippets to the documentation files using the tool. The most important points here are:

  1. Choose the correct config file (or create / modify one).
  2. Check out the correct branch in the repository with snippets.
  3. Make sure the used Spine version in snippets matches your expectations.
  4. After code embedding, please always review the changes made to .md or .html files.

How to update an existing code snippet?

  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 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:

    ./embed-code-macos -config-path="../_settings/v1.embed-code.yml" -mode="embed"

Adding a new example project

  1. Make sure the project you're going to add has a top-level buildAll Gradle task.

    See the build script of Hello Example for the declaration of such a task. This task must be present in both single- and multi-module Gradle example projects that are going to be used for embedding into this site.

    See the declaration of buildAll task for more details.

  2. Add the example code as a submodule for this project:

    git submodule add https://github.com/spine-examples/<example-name> docs/_code/examples/<example-name>

    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 file.

  4. Insert code embedding directives where needed in the docs/content/ folder.

  5. Navigate to the docs/_bin directory.

  6. Execute: ./embed-code -config-path="config-of-your-choice.yml" -mode="embed".

    For example:

    ./embed-code-macos -config-path="../_settings/v1.embed-code.yml" -mode="embed"

Adding a new small piece

  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.
  4. Include the build of the added project into the settings.gradle.kts file includeBuild("./docs/_code/samples").

How to remove a code snippet?

  1. Remove the snippet in the appropriate repository.

  2. Remove its code embeddings from the markdown files.

  3. Make sure there are no embeddings of the removed snippet anymore: ./embed-code-<os> -config-path="config-of-your-choice.yml" -mode="check".

    For example:

    ./embed-code-macos -config-path="../_settings/v1.embed-code.yml" -mode="check"

Troubleshooting

If you encounter an error indicating that the executable file cannot be run, it likely does not have execution permissions. To grant execution rights on Linux or macOS, run the following command from the _code directory:

chmod +x embed-code-macos