From a843a61293ce8be0cbf2e3fea01e79effd16207f Mon Sep 17 00:00:00 2001 From: Paul Pestov <10750176+paulpestov@users.noreply.github.com> Date: Fri, 19 Jan 2024 12:45:54 +0100 Subject: [PATCH] docs: add TextAPI support table --- .env | 3 + .validation/create-support-matrix.js | 124 +++++++++++++++++++++++++++ .validation/support-matrix.json | 115 +++++++++++++++++++++++++ README.md | 31 +++++-- SUPPORT.md | 5 ++ 5 files changed, 272 insertions(+), 6 deletions(-) create mode 100644 .env create mode 100644 .validation/create-support-matrix.js create mode 100644 .validation/support-matrix.json create mode 100644 SUPPORT.md diff --git a/.env b/.env new file mode 100644 index 00000000..d0e4f9ba --- /dev/null +++ b/.env @@ -0,0 +1,3 @@ +GITLAB_BASE_URL=https://gitlab.gwdg.de/api/v4 +GITLAB_VALIDATION_PROJECT_ID=31207 +GITLAB_ACCESS_TOKEN=YOUR_TOKEN diff --git a/.validation/create-support-matrix.js b/.validation/create-support-matrix.js new file mode 100644 index 00000000..0b92986c --- /dev/null +++ b/.validation/create-support-matrix.js @@ -0,0 +1,124 @@ +const fs = require('fs') + +const gitlabBaseUrl = process.env.GITLAB_BASE_URL +const projectId = process.env.GITLAB_VALIDATION_PROJECT_ID +const token = process.env.GITLAB_ACCESS_TOKEN + +async function getSchemaFilesList() { + const url =`${gitlabBaseUrl}/projects/${projectId}/repository/tree?path=schema` + + const response = await fetch(url, { + headers: { + 'PRIVATE-TOKEN': token, + }, + }); + + if (response.ok) { + const data = await response.json(); + return data.map(e => e.path); + } else { + throw `An error occurred while fetching: ${url}`; + } +} + +async function getFileContent(path) { + const url = `${gitlabBaseUrl}/projects/${projectId}/repository/files/${encodeURIComponent(path)}/raw` + + try { + const response = await fetch(url, { + headers: { + 'PRIVATE-TOKEN': token, + }, + }); + + if (response.ok) { + return await response.json(); + } else { + throw `An error occurred while fetching: ${url}`; + } + + } catch(e) { + console.log(e) + } +} + +function getSupportColor(value) { + const red = '#d97a75' + const yellow = '#d9c873' + const green = '#80ba73' + const grey = '#bababa' + + if (value === 0) return red + if (value === 1) return green + if (value === 2) return yellow + return grey +} + +function getSupportStatusText(value) { + if (value === 0) return 'not supported' + if (value === 1) return 'supported' + if (value === 2) return 'partially supported' + return 'unused' +} + +function createTable(data) { + + const header = `# TextAPI Support + + This document shows which TextAPI keys TIDO supports in the current version. + + ` + let template = `${header}` + + Object.keys(data).forEach((objectKey, i) => { + template += Object.keys(data[objectKey]).map((fieldKey, j) => { + const objectCell = j === 0 ? '' : '' + return `${objectCell}` + }).join('') + }) + + template += '
ObjectFieldSupported
' + objectKey + '
${fieldKey}${getSupportStatusText(data[objectKey][fieldKey])}
' + + return template +} + +(async () => { + const supportMatrixFileName = __dirname + '/support-matrix.json' + const supportMatrixExists = fs.existsSync(supportMatrixFileName) + let supportMatrix = {} + + if (supportMatrixExists) { + // If the support matrix was generated before, just read it + supportMatrix = JSON.parse(fs.readFileSync(supportMatrixFileName)) + } else { + // Read JSON schema files from TextAPI specs repo and generate a new support matrix JSON + const filesList = await getSchemaFilesList() + + for (let i = 0; i < filesList.length; i++) { + const content = await getFileContent(filesList[i]) + if (!content || !content.properties) continue + const textApiKeys = Object.keys(content.properties) + supportMatrix[content['$id'].replace('.json', '')] = textApiKeys.reduce((acc, cur) => { + acc[cur] = 0 + return acc + }, {}) + } + + // Store the new support matrix as JSON in file + try { + fs.writeFileSync(supportMatrixFileName, JSON.stringify(supportMatrix), 'utf-8'); + } catch(e) { + console.log(e) + } + } + + // Render table in SUPPORT.md + try { + const fileName = __dirname + '/../SUPPORT.md' + fs.writeFileSync(fileName, createTable(supportMatrix), 'utf-8'); + } catch(e) { + console.log(e) + } + +})() + diff --git a/.validation/support-matrix.json b/.validation/support-matrix.json new file mode 100644 index 00000000..b41af6dd --- /dev/null +++ b/.validation/support-matrix.json @@ -0,0 +1,115 @@ +{ + "actor": { + "@context": 3, + "role": 2, + "name": 1, + "id": 3, + "idref": 0 + }, + "collection": { + "@context": 3, + "textapi": 3, + "id": 1, + "title": 1, + "collector": 2, + "sequence": 2, + "total": 0, + "description": 1, + "annotationCollection": 0, + "modules": 0 + }, + "/content": { + "@context": 3, + "url": 1, + "type": 1, + "integrity": 0 + }, + "idref": { + "@context": 0, + "base": 0, + "type": 0, + "id": 0 + }, + "image": { + "@context": 3, + "id": 1, + "manifest": 0, + "license": 1 + }, + "integrity": { + "@context": 0, + "type": 0, + "value": 0 + }, + "item": { + "@context": 3, + "textapi": 3, + "id": 1, + "title": 0, + "type": 0, + "n": 1, + "lang": 0, + "langAlt": 0, + "content": 1, + "description": 0, + "image": 1, + "annotationCollection": 1, + "modules": 0 + }, + "license": { + "@context": 3, + "id": 1, + "notes": 1 + }, + "manifest": { + "@context": 3, + "textapi": 3, + "id": 1, + "label": 1, + "sequence": 1, + "total": 0, + "actor": 2, + "repository": 0, + "image": 0, + "metadata": 1, + "support": 1, + "license": 1, + "description": 0, + "annotationCollection": 0, + "modules": 0 + }, + "metadata": { + "@context": 3, + "key": 1, + "value": 1 + }, + "module": { + "edition-manuscripts": 0, + "edition-prints": 0 + }, + "repository": { + "@context": 3, + "label": 0, + "url": 0, + "baseUrl": 0, + "id": 0 + }, + "sequence": { + "@context": 3, + "id": 1, + "type": 0, + "label": 1 + }, + "support": { + "@context": 0, + "type": 2, + "mime": 0, + "url": 1, + "integrity": 0 + }, + "title": { + "@context": 3, + "title": 1, + "type": 1 + } +} diff --git a/README.md b/README.md index 0428ceb4..7fc54cbb 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ With this project we provide a highly configurable viewer for projects that impl - [Demo](#demo) - [Getting Started](#getting-started) - [Get the Viewer](#get-the-viewer) - - [Registry setup](#registry-setup) + - [Registry Setup](#registry-setup) - [Installation](#installation) - [Integration](#integration) - [Configuration](#configuration) @@ -28,17 +28,19 @@ With this project we provide a highly configurable viewer for projects that impl - [Prerequisites](#prerequisites) - [Install](#install) - [Set up `nvm` and the recent stable version of `node.js`](#set-up-nvm-and-the-recent-stable-version-of-nodejs) - - [Clone the repository](#clone-the-repository) - - [Get the dependencies](#get-the-dependencies) + - [Clone the Repository](#clone-the-repository) + - [Get the Dependencies](#get-the-dependencies) - [Build](#build) - - [Serve locally](#serve-locally) - - [Serve development build](#serve-development-build) - - [Serve examples (production build)](#serve-examples-production-build) + - [Serve Locally](#serve-locally) + - [Serve Development Build](#serve-development-build) + - [Serve Examples (Production Build)](#serve-examples-production-build) - [Serve Mock API](#serve-mock-api) - [Testing](#testing) - [Local](#local) - [CI](#ci) - [Linting](#linting) + - [Generate TextAPI support table](#generate-textapi-support-table) +- [TextAPI Support](#textapi-support) - [Viewer Architecture](#viewer-architecture) - [Dockerfile](#dockerfile) - [Architecture](#architecture) @@ -528,6 +530,22 @@ npm run lint:scss # to lint the styles npm run lint:vue # to lint vue files only ``` +### Generate TextAPI support table + +We maintain a JSON file (`/.validation/support-matrix.json`) that keeps track of supported TextAPI features. +If you need to recreate that file and rerender `/SUPPORT.md`, here is an explanation: + +- Make sure you run NodeJS version >= 20 +- Set `GITLAB_ACCESS_TOKEN` in `/.env` file +- Run `node ./.validation/create-support-matrix.js` +- Inspect `/.validation/support-matrix.json`, all status values are set to 0 (= not supported) by default +- Edit the statuses manually: 0 = not supported, 1 = supported, 2 = partially supported, 3 = unused +- Run `node ./.validation/create-support-matrix.js` again to generate new `/SUPPORT.md` + +## TextAPI Support +Please view this document to see an overview of supported TextAPI features: [State of TextAPI support](SUPPORT.md) + + ## Viewer Architecture ![Viewer components](img/Viewer.png) @@ -556,3 +574,4 @@ We use [SemVer](https://semver.org/) for versioning. For the versions available, ## Authors See the list of [contributors](https://gitlab.gwdg.de/subugoe/emo/tido/-/graphs/develop) who participated in this project. +First line added! diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000..dd928a5e --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,5 @@ +# TextAPI Support + + This document shows which TextAPI keys TIDO supports in the current version. + +
ObjectFieldSupported
actor@contextunused
rolepartially supported
namesupported
idunused
idrefnot supported
collection@contextunused
textapiunused
idsupported
titlesupported
collectorpartially supported
sequencepartially supported
totalnot supported
descriptionsupported
annotationCollectionnot supported
modulesnot supported
/content@contextunused
urlsupported
typesupported
integritynot supported
idref@contextnot supported
basenot supported
typenot supported
idnot supported
image@contextunused
idsupported
manifestnot supported
licensesupported
integrity@contextnot supported
typenot supported
valuenot supported
item@contextunused
textapiunused
idsupported
titlenot supported
typenot supported
nsupported
langnot supported
langAltnot supported
contentsupported
descriptionnot supported
imagesupported
annotationCollectionsupported
modulesnot supported
license@contextunused
idsupported
notessupported
manifest@contextunused
textapiunused
idsupported
labelsupported
sequencesupported
totalnot supported
actorpartially supported
repositorynot supported
imagenot supported
metadatasupported
supportsupported
licensesupported
descriptionnot supported
annotationCollectionnot supported
modulesnot supported
metadata@contextunused
keysupported
valuesupported
moduleedition-manuscriptsnot supported
edition-printsnot supported
repository@contextunused
labelnot supported
urlnot supported
baseUrlnot supported
idnot supported
sequence@contextunused
idsupported
typenot supported
labelsupported
support@contextnot supported
typepartially supported
mimenot supported
urlsupported
integritynot supported
title@contextunused
titlesupported
typesupported
\ No newline at end of file