diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 3e99c67..4ba3990 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -82,11 +82,6 @@ jobs: - name: Build the MkDocs site run: mkdocs build # Builds the static site from Markdown files working-directory: ${{github.workspace}} # Ensures mkdocs builds from the root directory - - - name: List generated site structure - run: | - echo "Listing the contents of the generated site directory:" - ls -R ./site # GitHub Pages setup - name: Setup Pages diff --git a/docs/how-to/add-tev2-tools-to-actions-script.md b/docs/how-to/add-tev2-tools-to-actions-script.md index 7fdc0e4..37436e0 100644 --- a/docs/how-to/add-tev2-tools-to-actions-script.md +++ b/docs/how-to/add-tev2-tools-to-actions-script.md @@ -6,20 +6,18 @@ Title: Add TEv2 to GitHub Actions You only need to do this if you intend to use the tools in a GitHub workflow. -All you need to do is add some texts to the workflow file +All you need to do is add some texts to the [workflow file](@) that is used to generate the static website. This file is located in the `/.github/workflows` directory of your repo. -In this MVE, we also have such a file. -It is called [`deploy-docs.yml`](https://github.com/tno-terminology-design/tev2-mve/blob/main/.github/workflows/deploy-docs.yml). +In this [MVE](@), we also have such a file. It is called +[`deploy-docs.yml`](https://github.com/tno-terminology-design/tev2-mve/blob/main/.github/workflows/deploy-docs.yml). You can use this as an example. -You can also see there the particular parts that you must have in your workflow file - This file is a standard/minimal workflow for creating a GitHub Pages website, where we have inserted the following action-steps: -~~~ +~~~ yaml # Setting up Node, as this is needed to install the TEv2 tools - name: Setup Node.js uses: actions/setup-node@v3 @@ -33,7 +31,7 @@ and it is not necessary to duplicate that then. The TEv2-specific part that (always) needs to be added is as follows: -~~~ +~~~ yaml # TEv2 Tool installation - name: Install terminology tools globally run: npm install -g @tno-terminology-design/trrt @tno-terminology-design/hrgt @tno-terminology-design/mrgt @tno-terminology-design/mrg-import @@ -55,165 +53,6 @@ The TEv2-specific part that (always) needs to be added is as follows: file_pattern: 'docs/glossaries/mrg.mve*.yaml' ~~~ +That's all. - - - - - -The [TEv2 tools] you need are avaiable as NPM packages. We use the [MRG import](@tev2), [MRGT](@tev2), [HRGT](@tev2) and [TRRT](@tev2), which can be installed by executing: - -~~~ -npm install -g @tno-terminology-design/mrg-import -npm install -g @tno-terminology-design/mrgt -npm install -g @tno-terminology-design/hrgt -npm install -g @tno-terminology-design/trrt -~~~ - -You can verify that they are installed correctly by -making the `docs` directory your current directory, -and then run the following commands - -~~~ -mrg-import --version -mrgt --version -hrgt --version -trrt --version -~~~ - -all of which should return a version number. -In case of trouble, you may consult - -- [npm Troubleshooting Guide](https://docs.npmjs.com/troubleshooting) - This is the official npm troubleshooting guide which covers common problems including installation issues on different operating systems. - -- [Stack Overflow](https://stackoverflow.com/questions/tagged/npm) - Stack Overflow has a vast number of questions and answers on npm issues across all platforms. Users can search for their specific issues or ask new questions. - -- [Issues on the Node.js GitHub repo](https://github.com/nodejs/node/issues) - The Node.js GitHub repository can be useful for browsing or reporting issues directly related to Node.js, which may indirectly solve npm issues. - -- [npm Community](https://npm.community/) - The npm Community forum is a place to discuss problems and share solutions with other npm users across different environments. - -## File/Directory Structure - -The `docs` directory is the root directory in which TEv2 works (the reason for -this is that it contains the [Scope Administration File](saf@tev2) (`saf.yaml`) -for the MVE scope). This directory is constructed as follows: - -~~~ -├── mrgs -│ ├── mrg.mve.terms.yaml -│ └── mrg.mve.yaml -├── terms -│ ├── term-1.md -│ └── term-2.md -├── outputs -│ └── readme.md -├── index.md -├── mve-glossary.md -├── saf.yaml -└── tev2-configs.yaml -~~~ - -- `mrgs` (directory) contains [machine readable glossaries](@tev2). They are either -imported (by the [mrg-import](@tev2) tool), or generated (by the [mrgt](@tev2) tool). -The [glossaries](@tev2) generated within this scope are `mrg.mve.terms.yaml` -(the [mrg](@tev2) of [terms](@tev2) that are defined within this scope) and -`mrg.mve.yaml` (the [mrg](@tev2) that holds the default [terminology](@tev2) -of this [scope](@tev2)). Other [mrgs](@tev2) that might exist would be imported. - -- `terms` (directory) contains files with [curated texts](@tev2), i.e., -markdown texts that document the terminology defined within this [scope](@tev2). - -- `index.md` file (this file). - -- `mve-glossary.md` is a markdown file that contains a [marker](mrg-ref@tev2) -that the [hrgt tool](hrgt@tev2) converts into a [human readable glossary](@tev2) -of the [terms](@tev2) that are defined in this [scope](@tev2). - -- `saf.yaml` is the [scope administration file](saf@tev2). - -- `tev2-configs.yaml` is a [TEv2 configuration file](@tev2) that holds -configurations for the [TEv2 tools](@tev2). - -## Working with TEv2 tools - -The purpose of this site is to provide you with an initial setup that enables you to run the tools by yourselves, so that you can see what they do. - -**We assume that all commands are run from the directory that contains the file `saf.yaml`** - -You can do this as follows: - -### Step 0: Make sure the tools become available - -You can do this by installing npm (the node packet manager) on your machine, and subsequently making all tools available, as follows: - -~~~ cmd -npm install -g @tno-terminology-design/mrg-import -npm install -g @tno-terminology-design/mrgt -npm install -g @tno-terminology-design/hrgt -npm install -g @tno-terminology-design/trrt -~~~ - -You can verify they are available by - -1. going to the directory that contains `saf.yaml`, and then -2. executing the following command(s) from within that directory: - -~~~ cmd - --version -~~~ - -(where `` is `mrg-import`, `mrgt`, `hrgt`, or `trrt`). - -### Step 1: importing MRGs - -The first step consists of ensuring that [terminologies](@tev2) that are -defined elsewhere, and that you rely on to be available (e.g., as you refer -to its [terms](@tev2)), are actually available. - -You can skip this step if there are no such [terminologies](@tev2). - -As this file makes extensive use of the [terms](@tev2) defined by TEv2, -we need to import its (default) [MRG](@tev2). You can do that by executing -the following command from within the directory that contains `saf.yaml` - -~~~ cmd -mrg-import -c "tev2-configs.yaml" -~~~ - -This will add various files in the `mrgs` directory, called `mrg.tev2*.yaml`. -You can discard all, except `mrg.tev2.yaml`, but you can also leave them -where they are, as they are not in the way. - -### Step 2: generating Machine Readable Glossaries (MRGs) - -In the second step, we will generate [machine readable glossaries](@tev2) -for the [terminologies](@tev2) that are defined in the [saf](@tev2). -You can do that by executing the following command: - -~~~ cmd -mrgt -c "tev2-configs.yaml" -~~~ - -This adds another two [MRGs](@tev2) to the `mrgs` directory: - -- `mrg.mve.terms.yaml` holds the [MRG](@tev2) that contains all [terms](@tev2) -that are defined in our MVE-[scope](@tev2). -- `mrg.mve.yaml` holds the [MRG](@tev2) that contains all [terms](@tev2) -in the default [terminology](@tev2) of our MVE-[scope](@tev2). - -It so happens that these files have the same contents. - -### Step 3: generating Human Readable Glossaries (HRGs) - -Next, we can generate the [human readable glossaries](@tev2). - -You can do that by executing the following command: - -~~~ cmd -hrgt -c "tev2-configs.yaml" -~~~ - +## Notes \ No newline at end of file diff --git a/docs/how-to/config-files.md b/docs/how-to/config-files.md index 866393a..54965b1 100644 --- a/docs/how-to/config-files.md +++ b/docs/how-to/config-files.md @@ -60,7 +60,7 @@ For example, as the value for its `converter` argument. And it will only process files that have the extension `.md` and that are located in the [scopedir](@tev2) itself. -# Notes +## Notes 1. **Converters determine what the output of a tool looks like**. Each tool that uses [converters](@tev2) comes with a set of predefined ones. diff --git a/docs/how-to/generate-mrgs.md b/docs/how-to/generate-mrgs.md index 68a196b..e9d520e 100644 --- a/docs/how-to/generate-mrgs.md +++ b/docs/how-to/generate-mrgs.md @@ -12,7 +12,7 @@ This results in the generated [MRGs](@tev2) to become available in the `mrgs`-directory (as specified by the [SAF](@tev2)). In our case, that would be -- `mrg.mve.terms.yaml`, which holds the [MRG](@tev2) that contains all [terms](@tev2) +- `mrg.mve.mve-terms.yaml`, which holds the [MRG](@tev2) that contains all [terms](@tev2) that are defined in our [MVE](@), and - `mrg.mve.yaml`, which holds the [MRG](@tev2) that contains all [terms](@tev2) in the default [terminology](@tev2) of our MVE-[scope](@tev2). diff --git a/docs/how-to/saf.md b/docs/how-to/saf.md index 35365b4..8f6053e 100644 --- a/docs/how-to/saf.md +++ b/docs/how-to/saf.md @@ -16,44 +16,57 @@ is called the [scopedir](@tev2) (of that [scope](@tev2)). It is the root relative to which all TEv2-related paths are specified. Here is an example of the [SAF](@tev2) for this [MVE](@). -For starters, you can simply copy this text, and adjust the contents of the various fields. +For starters, you can simply copy this text, and adjust the contents of the various fields. When you do so, please be very accurate with the values that you provide. ~~~ yaml scope: - # identifier that we use for this terminology + # Identifier that we use as a name for this scope scopetag: mve - # URL of the scope-directory (within the repo) + # URL of the scope-directory within the repo scopedir: https://github.com/tno-terminology-design/tev2-mve/tree/master/docs - # path to directory where curated files are located. Full URL is `scopedir`/`curatedir` + # path to directory where curated files are located. + # Full URL is `scopedir`/`curatedir` curatedir: terms - # path to directory where all MRGs are located. Full URL is `scopedir`/`glossarydir` + # path to directory where all MRGs are located. + # Full URL is `scopedir`/`glossarydir` glossarydir: mrgs - # vsntag that identifies the default terminology. MRG is located at `scopedir`/`glossarydir`/mrg.mve.yaml - defaultvsn: terms - # base URL for creating links to rendered versions of Curated Texts. It should also serve as the home page of the terminology. - website: https://tno-terminology-design.github.io/tev2-mve/docs - # Path to the directory where Curated Texts are rendered. What `curatedir` is for Curated Texts is, `navpath` is for the rendered versions of Curated Texts. + # vsntag that identifies the default terminology. + # Its MRG is located at `scopedir`/`glossarydir`/mrg.mve.yaml + defaultvsn: mve-terms + # Base URL for creating links to rendered versions of Curated Texts. + # It should also serve as the home page of the terminology. + website: https://tno-terminology-design.github.io/tev2-mve + # Path to the directory where Curated Texts are rendered. + # What `curatedir` is for Curated Texts, `navpath` is for + # the rendered versions of Curated Texts. navpath: /terms - # Name of the field in the front matter of a body file used by your static site generator in a URL, to uniquely identify that file (e.g., "id", "slug", "permalink"). If not specified, the filename of the body file will be used. | - navid: + # Name of a field that can be found in the front matter of a + # curated text file, that will be used to generate links that + # are routable by the static site generator that is being used. + # If not specified, the filename of the body file will be used. + navid: term # -# The `scopes` section contains a mapping between scopetags that are used within the scope, -# and the associated scopedirs. -# This enables tools to find the SAF of these scopes, and from there all other directories, files etc. -# that live within them, e.g. to use/import their data. +# The `scopes` section contains a mapping between scopetags +# that are used within the scope, and the associated scopedirs. +# This enables tools to find the SAF of these scopes, +# and from there all other directories, files etc. that live +# within them, e.g. to use/import their data. # -scopes: # -- scopetag: tev2 - # URL of the scope-directory +scopes: +- scopetag: tev2 # name we use to identify the scope found at + # the URL of the scope-directory: scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs # -# The `versions` section specifies the terminologies that are actively maintained by the curators. -# For each (version of such a) terminology, instructions are given that say which terms are to be included. -# One such section must have a `vsntag` that matches the value of `defaultvsn` in the `scope`-section +# The `versions` section specifies the terminologies +# that are actively maintained by the curators of this scope. +# For each (version of such a) terminology, termselection instructions +# must be provided that specify which terms are to be included. +# One of these section must have a `vsntag` that matches +# the value of `defaultvsn` in the `scope`-section. # versions: # this version contains all terms that are curated within this scope -- vsntag: terms +- vsntag: mve-terms termselection: # include all terms that are curated within the current scope - "*" diff --git a/docs/saf.yaml b/docs/saf.yaml index 7dc1da1..72a5922 100644 --- a/docs/saf.yaml +++ b/docs/saf.yaml @@ -2,30 +2,56 @@ # This is a Scope Administration File (SAF) that can be used in conjunction with Terminology Engine v2: https://tno-terminology-design.github.io/tev2-specifications/docs/category/introduction-overview. # scope: - scopetag: mve # identifier that curators have determined for this terminology - scopedir: https://github.com/tno-terminology-design/tev2-mve/tree/master/docs # URL of the scope-directory - curatedir: terms # directory where all curated files are located. Full URL is `scopedir`/`curatedir` - glossarydir: mrgs # directory where all MRGs are located. Full URL is `scopedir`/`glossarydir` - defaultvsn: terms # vsntag that identifies the default terminology. MRG is located at `scopedir`/`glossarydir`/mrg.mve.yaml - website: https://tno-terminology-design.github.io/tev2-mve # base URL for creating links to rendered versions of Curated Texts. It should also serve as the home page of the terminology. - navpath: /terms # Path to the directory where Curated Texts are rendered. What `curatedir` is for Curated Texts is, `navpath` is for the rendered versions of Curated Texts. - navid: term # Name of the field in the front matter of a body file used by your static site generator in a URL, to uniquely identify that file (e.g., "id", "slug", "permalink"). If not specified, the filename of the body file will be used. | + # Identifier that we use as a name for this scope + scopetag: mve + # URL of the scope-directory within the repo + scopedir: https://github.com/tno-terminology-design/tev2-mve/tree/master/docs + # path to directory where curated files are located. + # Full URL is `scopedir`/`curatedir` + curatedir: terms + # path to directory where all MRGs are located. + # Full URL is `scopedir`/`glossarydir` + glossarydir: mrgs + # vsntag that identifies the default terminology. + # Its MRG is located at `scopedir`/`glossarydir`/mrg.mve.yaml + defaultvsn: mve-terms + # Base URL for creating links to rendered versions of Curated Texts. + # It should also serve as the home page of the terminology. + website: https://tno-terminology-design.github.io/tev2-mve + # Path to the directory where Curated Texts are rendered. + # What `curatedir` is for Curated Texts, `navpath` is for + # the rendered versions of Curated Texts. + navpath: /terms + # Name of a field that can be found in the front matter of a + # curated text file, that will be used to generate links that + # are routable by the static site generator that is being used. + # If not specified, the filename of the body file will be used. + navid: term # -# The `scopes` section contains a mapping between scopetags that are used within the scope, and the associated scopedirs. -# This enables tools to find the SAF of these scopes, and from there all other directories, files etc. -# that live within them, e.g. to use/import their data. +# The `scopes` section contains a mapping between scopetags +# that are used within the scope, and the associated scopedirs. +# This enables tools to find the SAF of these scopes, +# and from there all other directories, files etc. that live +# within them, e.g. to use/import their data. # -scopes: # -- scopetag: tev2 - scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs # URL of the scope-directory +scopes: +- scopetag: tev2 # name we use to identify the scope found at + # the URL of the scope-directory: + scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs # -# The `versions` section specifies the terminologies that are actively maintained by the curators. -# For each (version of such a) terminology, instructions are given that say which terms are to be included. +# The `versions` section specifies the terminologies +# that are actively maintained by the curators of this scope. +# For each (version of such a) terminology, termselection instructions +# must be provided that specify which terms are to be included. +# One of these section must have a `vsntag` that matches +# the value of `defaultvsn` in the `scope`-section. # versions: -- vsntag: terms # this version contains all terms that are curated within this scope + # this version contains all terms that are curated within this scope +- vsntag: mve-terms termselection: - - "*" # include all terms that are curated within the current scope + # include all terms that are curated within the current scope + - "*" # - vsntag: documentation # this version contains all terms we use to refer to in this site # termselection: # - "*"@tev2" # include all terms of the default TEv2 terminology diff --git a/docs/terms/mve.md b/docs/terms/mve.md index ff625c3..5d2be0f 100644 --- a/docs/terms/mve.md +++ b/docs/terms/mve.md @@ -15,10 +15,11 @@ formPhrases: [ "mimimal viable example{ss}", "mimimum viable example{ss}", "mve{ A **Minimal Viable Example (MVE)** is a very simple version of a GitHub repo that includes the minimal stuff for using the [TEv2 tools](@tev2) and demonstrating its results. This includes: + - the actual documentation that is to be published; - the files needed for generating the static website (e.g., the [workflow file](@); -- any other artifacts needed by the static website generate (e.g., CSS files, plugins, etc.) -- and, of course, the set of directories and files that [TEv2 tools](@tev2) need; +- any other artifacts needed by the static website generate (e.g., CSS files, plugins, etc.); +- and, of course, the set of directories and files that [TEv2 tools](@tev2) need. ## Example