Ability to reference production code via a relative path

[alexander-yevsyukov]

I am trying to reference a file outside of the specified root of the examples code. It almost works, so I don't know if it's a bug or a feature request. Let me explain in details.

I'm writing a next round of the documentation for the Validation library. Here's the PR.

My embed-code.yml is configured like this:

code-path: "../_examples"
docs-path: "../content/docs/"
embed-mappings:
  - code-path: "../_examples"
    docs-path: "../content/docs/"

The _examples directory lives as a Git submodule under the docs subfolder under the root of the project called validation. So the structure looks like this:

validation
  docs         # The documentation submodule.
    _bin       # This is where `embed-code` binaries live.
    _examples
    content
  jvm-runtime.  # The production code directory I want to reference.

Here's how I try to reference the file I need using the embed-code tag:

<embed-code file="../../../../jvm-runtime/src/main/kotlin/io/spine/validation/TimestampValidator.kt" fragment="core"></embed-code>

For that I got the following error:

panic: embedding error for file ``: unable to embed construction for doc file `../content/docs/validation/04-third-party-messages/_index.md` at line 109: unable to read the code fence end: file /Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/kotlin/io/spine/validation/TimestampValidator-4358f8ba.kt doesn't exist.

Notice the following directory referenced in the error:

/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/kotlin/io/spine/validation/

This is the correct directory on my file system. The problematic part is TimestampValidator-4358f8ba.kt which is a name of a file which obviously does not exits because the correct name is TimestampValidator.kt.

Please investigate and resolve.

[alexander-yevsyukov]

I'm going to rollback the embed-code instruction. So you won't see it in the updated version of the Validation PR I reference in the description. But the rest of the setup will be there.

[alexander-yevsyukov]

@armiol, FYI.

[Vladyslav-Kuksiuk]

@alexander-yevsyukov, it is not possible to reference code outside the folder specified in code-path, because the code must be preprocessed (split into fragments, cleaned, etc.). I will add an error message to make this behavior more obvious.

Currently, it is possible to include the jvm-runtime (or any other folders) in the embedding fragmentation by moving the root code-path higher and specifying the code-includes setting. The configuration would then look like this:

code-path: ../../
code-includes: "./docs/_examples/**, ./jvm-runtime/**"
docs-path: ../content

However, in this case all previously specified embedding paths must be updated, because the relative path changes.

So

<embed-code file="MyExample.kt" fragment="main"></embed-code>

becomes

<embed-code file="docs/_examples/MyExample.kt" fragment="main"></embed-code>

---

Also, it is not necessary to specify the embed-mappings setting if it is the same as code-path and docs-path, because it is intended for additional mappings.

[armiol]

@Vladyslav-Kuksiuk can we do that on-the-fly in case the referenced piece is not inside the originally specified source tree?

[Vladyslav-Kuksiuk]

It is possible to specify the entire file to embed (without fragment):

<embed-code file="desired-path/TimestampValidator.kt"></embed-code>

Then you can add the TimestampValidator.kt file with the exactly required content to the fragments folder specified in the configuration (it is fragments by default), under desired-path.

However, I'm not sure this is the best approach.

[alexander-yevsyukov]

I have another suggestion in relation to this issue: Support multiple code roots.

I need to have the ability to reference relative paths like this:

• "$examples/MyExample.kt`.
• "$production/io/spine/validation/MessageValidator.kt`.

Correspondingly, the configuration file should have named entries for the code roots.

@Vladyslav-Kuksiuk, please estimate.

@armiol, FYI.

[alexander-yevsyukov]

It is possible to specify the entire file to embed (without fragment):

1. Please describe this feature in the documentation. It's not an obvious thing.
2. This is going to be used rarely. One of the reasons is copyright headers in the files: a) we need to have them b) we don't want them embedded into the documentation.

[Vladyslav-Kuksiuk]

@alexander-yevsyukov, adding multiple named code roots should take less than a day.

@armiol, adding the on-the-fly processing may take 3-5 days.

I think adding multiple code roots would be more obvious and readable than on-the-fly processing, because the path $production/io/spine/validation/MessageValidator.kt looks much better than ../../../../jvm-runtime/src/main/kotlin/io/spine/validation/TimestampValidator.kt.

[alexander-yevsyukov]

@Vladyslav-Kuksiuk, let's do it.