Skip to content

1. TEv2 Minimal Viable Example (using Github Pages/Jekyll)

The repo from which this website has been generated is a minimal viable example (MVE) that includes the minimal stuff for using the TEv2 tools and demonstrating its effects, which are:

  • highlighting of the terms that it uses. Basically, this boils down to converting so-called TermRefs to emphasized texts that have popups showing the definition of the terms that are referenced.

  • creation of a glossary for the terms that are defined within the scope of the repo.

So, this repo contains the documentation that tells you 'How to use TEv2 in a Github Pages/Jekyll context'. Thus, this site documents itself.

1.1. Installation of TEv2 Tools

TEv2 tools are typically deployed in a context where it is clear how the documentation is going to be rendered and presented to users. So, the first prerequisite is that such a context exists.

In this case, the context is a GitHub repo that is configured for using Pages. You can create one for yourself by follwing the descriptions in the GitHub Pages documentation.

The TEv2 tools can be used:

  • within the context of a local repo (on your own computer). This requires them to be installed locally.
  • within the context of the GitHub Actions that create the static Pages website. This requires some steps to be added to the GitHub Actions workflow that you use to generate the static Pages website.

1.2. TEv2 Files and Directories

Before you can actually use the tools, you must have a number of directories and files in place. They are typically located in the same directory where you maintain the files of your documentation. As this MVE has chosen docs as the directory for the documentation, this is also the directory where TEv2 directories and files will be put.

Here is a breakdown of the TEv2 specific directories and files:

├── saf.yaml
├── terms
│   ├── mve.md
│   ├── workflow-file.md
│   └── <etc.>
├── mrgs
├── glossary.md
└── tev2-config.yaml

  • saf.yaml is the scope administration file. It provides a centralized record of the resources in the documentation context, facilitating their access by the various TEv2 tools. Its contents must be provided by the user. Its name may not be changed.

  • terms is a directory that contains files with curated texts, i.e., markdown files that document the terminology defined within this scope. Its name MUST match the content of the field curatedir in the file saf.yaml. This directory, and the files it contains, must be created by users. To illustrate this, the figure above shows two such files.

  • mrgs is a directory that contains machine readable glossaries. Its name matches the content of the field glossarydir in the file saf.yaml. This directory is automatically generated by the tools. Users should not touch it, nor its contents, unless they know what they are doing.

  • glossary.md is a markdown file that we have created to show how a glossary can be defined, simply by putting a marker in such a file. The hrgt tool will convert such markers in the glossary of the terms whose descriptions are in the terms directory.

  • tev2-configs.yaml is a TEv2 configuration file. It is recommended to give it a name that allows you to immediately see that it is a TEv2 configuration file. Its contents must be provided and maintained by the user. Its name can be anything.

1.3. Running the TEv2 tools

The TEv2 tools can be run

  • as part of a GitHub workflow. This requires that you have added the TEv2 steps to the workflow file. The tools will be called as is specified in this workflow file. In this repo, they will be called whenever a commit or push is done to the main branch of the repo.

  • locally, i.e. on a local copy of the repo. In this case, you must have installed the tools locally, and verified that you can run them within the docs directory.

A typical workflow would consist of the following steps:

  1. If the documentation relies on terminologies that are curated elsewhere, the first step consist of importing glossaries from elsewhere. The result of this is that such glossaries are then imported, and stored in the directory as specified in the SAF, which in our case would be /docs/mrgs. If such isn't the case, this step can be skipped.

  2. The next step consists of generating one's own (machine readable) glossaries. The resulting MRGs are stored in the same directory as the imported MRGs, as specified in the SAF. For this MVE that would be /docs/mrgs.

  3. The documentation may have been set up to include one or more glossaries. If this is the case, the next step is to generate the (human readable) glossaries. The result of this is every so-called MRGRef marker that is found in any of the processed files, will be replaced with a (human readable) glossary. The MVE glossary shows the result of this step for this MVE.

  4. The documentation would contain so-called TermRefs. Resolving such TermRefs is the final step that needs to take place. The result of this is that every so-called TermRef that is found in any of the processed files, will be replaced with a renderable ref. In our case, this means it will be replaced such that the text will be highlighed (enhanced), will link to the file that provides further documentation, and will show a popup containing its definition.

In our case, a term such as TermRef is an imported term, whereas MVE is one defined by ourselves. You can see how they are highlighed, are clickable, and show popups.