From a9768030934867ed196cbf0a2a586fccba54337d Mon Sep 17 00:00:00 2001 From: henkvancann Date: Mon, 11 Nov 2024 14:01:33 +0100 Subject: [PATCH 1/3] amended Signed-off-by: henkvancann --- docs/intro.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/intro.md b/docs/intro.md index 4c740122..f5db17af 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -38,6 +38,7 @@ Supporting roles are: We have KERI specifications that consist of content and terminology. Let's take the KERI spec as an example. A `reader` could be anyone interested in the spec: - studying KERI - contributing to KERI in team + Contributing to any Spec-Up-T-based specification can be of type: - `curator` - `content author` or editor @@ -52,7 +53,7 @@ However, through all the chapters, including the Terms and Definitions chapter i > *Phil Pfeairheller* is a typical user of term defnitions. Generally he is a `content author` of specifications in the KERI team, whenever he sees a term that is not yet defined, he might create a definition on-the-fly if needed. -Note that any specification could use only **definitions** of other glossaries. And xref to those glossaries. This is rather uncommon because if your specifying, you most probably construct new concepts whithin a new mental model. +Note that any specification could use only **definitions** of other glossaries. And `xref` to those glossaries. This is rather uncommon because if your specifying, you most probably construct new concepts whithin a new mental model. *Drummond Reed* is `terminology author` of the ToIP main glossary. The main glosary has *hardly any content section*. All other terminology authors and content authors can use the Main ToIP glossary by `xref`-ing to it, as a plain Spec-Up-T link "[[xref: glossary, term ]]" even in their own `def`s to explain the difference between the mental model of the term in the smaller context vs. the broader ToIP context. From 2be285b7865cdeb88722ab6762887c44d1c0144c Mon Sep 17 00:00:00 2001 From: henkvancann Date: Tue, 12 Nov 2024 11:58:17 +0000 Subject: [PATCH 2/3] migration from Spec-Up to Spec-Up-T added Signed-off-by: henkvancann --- docs/general/migration.md | 136 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 docs/general/migration.md diff --git a/docs/general/migration.md b/docs/general/migration.md new file mode 100644 index 00000000..6659950f --- /dev/null +++ b/docs/general/migration.md @@ -0,0 +1,136 @@ +--- +sidebar_position: 1 +--- + +# Migration + +**Pre condition: You have a Spec-Up installation up and running** + + +## What you'll need + +- A terminal / Command Line +- An editor, also called IDE (Integrated Development Environment). We recommend Visual Studio Code, but an editor in which you can quickly write Markdown is also good +- [Node.js](https://nodejs.org/en/download/): + - When installing Node.js, you are recommended to check all checkboxes related to dependencies + - Use Node.js version 18 or higher +- A [webbrowser](https://en.wikipedia.org/wiki/Web_browser). You are probably reading this in a browser, so you already have one +- [Git](https://git-scm.com/). To host your specification on Github, you must also have Git installed on your local system. By the way, you can also create a specification (index.html) without hosting it on GitHub. But if you do so, the whole idea of a version-managed glossary using Git goes through the window. + +:::info +Non-technical explanation: +- Command Line: A text interface to type commands for your computer. +- IDE: A software where you can easily write, test, and debug code. +- Node.js: This makes Spec-Up and Spec-Up-T run +- Git: A system to track and manage changes in your code. +::: + +## Organize your Terminology data + +- Split your Terms and Definition into seperate files under a directory in `/spec` directory +- Adjust your Spec.json accordingly +- Add a Terms-spec.json +- + +## Modify your Spec-Up installation with Spec-Up-T install + +### General info + +Installing Spec-Up-T is as follows: + +- Install the tool via `npx` +- Install the spec-up-t package via `npm` + +It is explained in more detail below: + +### Let's create + +```bash +npx create-spec-up-t my-spec-up-t-website +``` + +*my-spec-up-t-website* can be anything you want it to be (however, it is recommended to not use spaces or special characters in directory names). + +You can also omit the last part: + +```bash +npx create-spec-up-t +``` + +If you omit `my-spec-up-t-website`, a default directory name, namely `spec-up-t-starterpack,` is used. + +Sometimes, you want to force the latest version to be installed. Then you can do the following: + +```bash +npx create-spec-up-t@latest my-spec-up-t-website +``` + +You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. It should work on any operating system (not tested yet). + +You should now have a directory called `my-spec-up-t-website` (or `spec-up-t-starterpack` if you did not specify a name). + +### Go into the directory + +- Go into this directory (folder) that was just created: + +```bash +cd my-spec-up-t-website +``` + +You are now in this directory. + +### Install all dependencies + +- Install all dependencies: + +```bash +npm run install +``` + +It can take some time, and you should see multiple lines of output during installation. + +When the prompt is visible again, you should now have a basic Spec-Up-T install: + +- a `specs.json` file +- a `spec/` directory with sample markdown files +- a `node_modules` directory, a `package.json` file, and a `package-lock.json` file (these three elements belong to the `npm` system) + +What you don't have yet is the following: + +- a `docs` directory with a sample `index.html` file (which is the actual specification file that is the goal of it all). + +How to do this, go to the [General Instructions](./command-line-menu.md). + +### Add repo to Github + +You should push your new specification (i.e. the sample content) to a GitHub repo. + +These are the steps to take: + +#### Edit `specs.json` + +Change this entry in `specs.json`: + +```json +"source": { + "host": "github", + "account": "blockchainbird", + "repo": "spec-up-t-starter-pack" +} +``` + +to the correct information: + +```json +"source": { + "host": "github", + "account": "your-account", + "repo": "your-repo" +} +``` + +These are the host (GitHub), your GitHub account name, and the repo name of the repo you are about to push. + +#### Commit and Push repo to GitHub + +Now, commit your changes and push the repo to GitHub. Use the command line or your preferred way to do this. From f7121b9935a45b8a592fd839a2a1e542d8df4bc0 Mon Sep 17 00:00:00 2001 From: henkvancann Date: Tue, 12 Nov 2024 14:28:43 +0000 Subject: [PATCH 3/3] migration page added Signed-off-by: henkvancann --- docs/general/migration.md | 179 ++++++++++++++++++++++---------------- 1 file changed, 106 insertions(+), 73 deletions(-) diff --git a/docs/general/migration.md b/docs/general/migration.md index 6659950f..2a50a452 100644 --- a/docs/general/migration.md +++ b/docs/general/migration.md @@ -6,7 +6,6 @@ sidebar_position: 1 **Pre condition: You have a Spec-Up installation up and running** - ## What you'll need - A terminal / Command Line @@ -17,7 +16,7 @@ sidebar_position: 1 - A [webbrowser](https://en.wikipedia.org/wiki/Web_browser). You are probably reading this in a browser, so you already have one - [Git](https://git-scm.com/). To host your specification on Github, you must also have Git installed on your local system. By the way, you can also create a specification (index.html) without hosting it on GitHub. But if you do so, the whole idea of a version-managed glossary using Git goes through the window. -:::info +::: note Non-technical Info Non-technical explanation: - Command Line: A text interface to type commands for your computer. - IDE: A software where you can easily write, test, and debug code. @@ -25,112 +24,146 @@ Non-technical explanation: - Git: A system to track and manage changes in your code. ::: -## Organize your Terminology data +## Save your data + +Back-up Specs.json to specs-backup.json + +Back-up package.json to package-backup.json -- Split your Terms and Definition into seperate files under a directory in `/spec` directory -- Adjust your Spec.json accordingly -- Add a Terms-spec.json -- +``` +mv specs.json specs-backup.json +mv package.json package-backup.json +``` + +Be sure to get the latest specs.json [here](https://github.com/trustoverip/spec-up-t-starter-pack/blob/main/spec-up-t-starterpack/specs.json) from the starter pack and save into the root of the repo. ## Modify your Spec-Up installation with Spec-Up-T install -### General info +We consider migration a task for the roles `developer` or `administrator`. -Installing Spec-Up-T is as follows: +It's about file management. It's in line with how static website generator generally work. So, be aware that you only organize your files in the migration process, you then configure your configuration files and you're good to go. Spec-Up-T will: -- Install the tool via `npx` -- Install the spec-up-t package via `npm` +- create the `terms-index.json` in the root of the repo +- generate the glossary in `index.html` +- creates `specs-generated.json` in the output directory, DON'T TOUCH +- creates `terms-and-definitions-intro.md` in the `/spec` directory DON'T TOUCH -It is explained in more detail below: +### Feel free to reorganize the order of term in the glossary +Open the `terms-index.json` with a text editor in the root of the repo and change the order of terms. You can even throw terms out. -### Let's create +::: note Plan to change +`terms-index.json` will be a file that can't be editted by the user. We'll create the following process: +- a user bypasses a term file (that is in draft) using an `_` (underscore) as the first character of the file name +- a user create a custom order (default: alphabetically) by putting an order number as the first 3 characters of a filename. Example: `10_validator.md`, `15_autonomous-identifier.md`, etc. + +This method is adopted from Docusaurus. +::: -```bash -npx create-spec-up-t my-spec-up-t-website -``` +### Prepare specs.json -*my-spec-up-t-website* can be anything you want it to be (however, it is recommended to not use spaces or special characters in directory names). -You can also omit the last part: +#### We copy the new specs.json structure for Spec-Up-T -```bash -npx create-spec-up-t +```json +{ + "specs": [ + { + "title": "Spec-Up-T Starterpack", + "spec_directory": "./spec", + "spec_terms_directory": "terms-definitions", | <- choose your name! | + "output_path": "./docs", + "markdown_paths": [ + "intro.md", + **| copy your .md files here, listed in specs.json-backup, excluding the terminology md files |** + ], + "logo": "https://raw.githubusercontent.com/blockchainbird/spec-up-t-starter-pack/main/spec-up-t-starterpack/logo.svg", + "logo_link": "https://github.com/blockchainbird/spec-up-t", + "source": { + "host": "github", + "account": "blockchainbird", + "repo": "spec-up-t-demo-on-documentation-website" + }, + "external_specs": [ + { + "test-1": "https://blockchainbird.github.io/spec-up-xref-test-1/" + }, + { + "test-2": "https://blockchainbird.github.io/spec-up-xref-test-2/" + } + ], + "external_specs_repos": [ + { + "external_spec": "test-1", + "url": "https://github.com/blockchainbird/spec-up-xref-test-1", + "terms_dir": "spec/term-definitions" + }, + { + "external_spec": "test-2", + "url": "https://github.com/blockchainbird/spec-up-xref-test-2", + "terms_dir": "spec/term-definitions" + } + ], + "katex": false, + "searchHighlightStyle": "ssi" + } + ] +} ``` -If you omit `my-spec-up-t-website`, a default directory name, namely `spec-up-t-starterpack,` is used. +Be sure to get the latest specs.json [here](https://github.com/trustoverip/spec-up-t-starter-pack/blob/main/spec-up-t-starterpack/specs.json) -Sometimes, you want to force the latest version to be installed. Then you can do the following: +Copy your old order of files from `specs-backup.json` and add `terms-and-definitions-intro.md` somewhere in the list (you choose the order!) -```bash -npx create-spec-up-t@latest my-spec-up-t-website -``` +#### Alter package.json +Follow the instructions here: [Update package.json](https://trustoverip.github.io/spec-up-t-website/docs/various-roles/admins-guide/updating/#packagejson) -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. It should work on any operating system (not tested yet). +#### Copy Spec-Up-T specific files +Follow the instructions here: [Make Spec-Up-T operational](https://trustoverip.github.io/spec-up-t-website/docs/various-roles/admins-guide/updating/#copy-files-to-the-root-of-your-installation) -You should now have a directory called `my-spec-up-t-website` (or `spec-up-t-starterpack` if you did not specify a name). +#### Terms in their own directory +| TBW why are we doing this | +You should place the terms in their own directory. This directory is defined in specs.json as `spec_terms_directory`. -### Go into the directory +Alter the configuration according to your wishes and place all term-files the directory. Also see [Organize your Terminology data](#organize-your-terminology-data) -- Go into this directory (folder) that was just created: +#### Npm Install +Delete your `node_modules` directory and `package-lock.json` file. -```bash -cd my-spec-up-t-website +Install Spec-Up-T and install all dependencies: +``` +npm install ``` +Go into the menu -You are now in this directory. +``` +npm run menu +``` -### Install all dependencies +Add new terms: option 6 -- Install all dependencies: +Generate the specification -```bash -npm run install +``` +npm run menu +1 ``` It can take some time, and you should see multiple lines of output during installation. -When the prompt is visible again, you should now have a basic Spec-Up-T install: +When the prompt is visible again, you should now have a Spec-Up-T install of your former Spec-Up install: -- a `specs.json` file -- a `spec/` directory with sample markdown files -- a `node_modules` directory, a `package.json` file, and a `package-lock.json` file (these three elements belong to the `npm` system) +- a `specs.json` file of the Spec-Up-T structure +- a `spec/` directory with your markdown files +- a `node_modules` directory, and a `package-lock.json` file (these elements belong to the `npm` system together with the earlier processed, modified-by-hand `package.json`) -What you don't have yet is the following: +What you also should have is: -- a `docs` directory with a sample `index.html` file (which is the actual specification file that is the goal of it all). - -How to do this, go to the [General Instructions](./command-line-menu.md). +- a `docs` directory with a generated `index.html` file (which is the actual specification file that is the goal of it all). ### Add repo to Github -You should push your new specification (i.e. the sample content) to a GitHub repo. - -These are the steps to take: - -#### Edit `specs.json` - -Change this entry in `specs.json`: - -```json -"source": { - "host": "github", - "account": "blockchainbird", - "repo": "spec-up-t-starter-pack" -} -``` +Follow the steps to take here if you want to use a different account or repo: [Add repo to Github](https://trustoverip.github.io/spec-up-t-website/docs/various-roles/admins-guide/updating/#copy-files-to-the-root-of-your-installation) -to the correct information: - -```json -"source": { - "host": "github", - "account": "your-account", - "repo": "your-repo" -} -``` - -These are the host (GitHub), your GitHub account name, and the repo name of the repo you are about to push. - -#### Commit and Push repo to GitHub +## Organize your Terminology data +- Split your Terms and Definition into separate files under a directory in `/spec` directory -Now, commit your changes and push the repo to GitHub. Use the command line or your preferred way to do this.