Skip to content

Commit

Permalink
docs: add TextAPI support table
Browse files Browse the repository at this point in the history
  • Loading branch information
paulpestov committed Jan 19, 2024
1 parent 3569d88 commit a843a61
Show file tree
Hide file tree
Showing 5 changed files with 272 additions and 6 deletions.
3 changes: 3 additions & 0 deletions .env
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
GITLAB_BASE_URL=https://gitlab.gwdg.de/api/v4
GITLAB_VALIDATION_PROJECT_ID=31207
GITLAB_ACCESS_TOKEN=YOUR_TOKEN
124 changes: 124 additions & 0 deletions .validation/create-support-matrix.js
Original file line number Diff line number Diff line change
@@ -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}<table><tr><th>Object</th><th>Field</th><th>Supported</th></tr>`

Object.keys(data).forEach((objectKey, i) => {
template += Object.keys(data[objectKey]).map((fieldKey, j) => {
const objectCell = j === 0 ? '<td rowspan="' + Object.keys(data[objectKey]).length + '">' + objectKey + '</td>' : ''
return `<tr>${objectCell}<td>${fieldKey}</td><td style="background:${getSupportColor(data[objectKey][fieldKey])}">${getSupportStatusText(data[objectKey][fieldKey])}</td></tr>`
}).join('')
})

template += '</table>'

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)
}

})()

115 changes: 115 additions & 0 deletions .validation/support-matrix.json
Original file line number Diff line number Diff line change
@@ -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
}
}
31 changes: 25 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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!
5 changes: 5 additions & 0 deletions SUPPORT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# TextAPI Support

This document shows which TextAPI keys TIDO supports in the current version.

<table><tr><th>Object</th><th>Field</th><th>Supported</th></tr><tr><td rowspan="5">actor</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>role</td><td style="background:#d9c873">partially supported</td></tr><tr><td>name</td><td style="background:#7dba70">supported</td></tr><tr><td>id</td><td style="background:#bababa">unused</td></tr><tr><td>idref</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="10">collection</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>textapi</td><td style="background:#bababa">unused</td></tr><tr><td>id</td><td style="background:#7dba70">supported</td></tr><tr><td>title</td><td style="background:#7dba70">supported</td></tr><tr><td>collector</td><td style="background:#d9c873">partially supported</td></tr><tr><td>sequence</td><td style="background:#d9c873">partially supported</td></tr><tr><td>total</td><td style="background:#d96c66">not supported</td></tr><tr><td>description</td><td style="background:#7dba70">supported</td></tr><tr><td>annotationCollection</td><td style="background:#d96c66">not supported</td></tr><tr><td>modules</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="4">/content</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>url</td><td style="background:#7dba70">supported</td></tr><tr><td>type</td><td style="background:#7dba70">supported</td></tr><tr><td>integrity</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="4">idref</td><td>@context</td><td style="background:#d96c66">not supported</td></tr><tr><td>base</td><td style="background:#d96c66">not supported</td></tr><tr><td>type</td><td style="background:#d96c66">not supported</td></tr><tr><td>id</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="4">image</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>id</td><td style="background:#7dba70">supported</td></tr><tr><td>manifest</td><td style="background:#d96c66">not supported</td></tr><tr><td>license</td><td style="background:#7dba70">supported</td></tr><tr><td rowspan="3">integrity</td><td>@context</td><td style="background:#d96c66">not supported</td></tr><tr><td>type</td><td style="background:#d96c66">not supported</td></tr><tr><td>value</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="13">item</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>textapi</td><td style="background:#bababa">unused</td></tr><tr><td>id</td><td style="background:#7dba70">supported</td></tr><tr><td>title</td><td style="background:#d96c66">not supported</td></tr><tr><td>type</td><td style="background:#d96c66">not supported</td></tr><tr><td>n</td><td style="background:#7dba70">supported</td></tr><tr><td>lang</td><td style="background:#d96c66">not supported</td></tr><tr><td>langAlt</td><td style="background:#d96c66">not supported</td></tr><tr><td>content</td><td style="background:#7dba70">supported</td></tr><tr><td>description</td><td style="background:#d96c66">not supported</td></tr><tr><td>image</td><td style="background:#7dba70">supported</td></tr><tr><td>annotationCollection</td><td style="background:#7dba70">supported</td></tr><tr><td>modules</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="3">license</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>id</td><td style="background:#7dba70">supported</td></tr><tr><td>notes</td><td style="background:#7dba70">supported</td></tr><tr><td rowspan="15">manifest</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>textapi</td><td style="background:#bababa">unused</td></tr><tr><td>id</td><td style="background:#7dba70">supported</td></tr><tr><td>label</td><td style="background:#7dba70">supported</td></tr><tr><td>sequence</td><td style="background:#7dba70">supported</td></tr><tr><td>total</td><td style="background:#d96c66">not supported</td></tr><tr><td>actor</td><td style="background:#d9c873">partially supported</td></tr><tr><td>repository</td><td style="background:#d96c66">not supported</td></tr><tr><td>image</td><td style="background:#d96c66">not supported</td></tr><tr><td>metadata</td><td style="background:#7dba70">supported</td></tr><tr><td>support</td><td style="background:#7dba70">supported</td></tr><tr><td>license</td><td style="background:#7dba70">supported</td></tr><tr><td>description</td><td style="background:#d96c66">not supported</td></tr><tr><td>annotationCollection</td><td style="background:#d96c66">not supported</td></tr><tr><td>modules</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="3">metadata</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>key</td><td style="background:#7dba70">supported</td></tr><tr><td>value</td><td style="background:#7dba70">supported</td></tr><tr><td rowspan="2">module</td><td>edition-manuscripts</td><td style="background:#d96c66">not supported</td></tr><tr><td>edition-prints</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="5">repository</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>label</td><td style="background:#d96c66">not supported</td></tr><tr><td>url</td><td style="background:#d96c66">not supported</td></tr><tr><td>baseUrl</td><td style="background:#d96c66">not supported</td></tr><tr><td>id</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="4">sequence</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>id</td><td style="background:#7dba70">supported</td></tr><tr><td>type</td><td style="background:#d96c66">not supported</td></tr><tr><td>label</td><td style="background:#7dba70">supported</td></tr><tr><td rowspan="5">support</td><td>@context</td><td style="background:#d96c66">not supported</td></tr><tr><td>type</td><td style="background:#d9c873">partially supported</td></tr><tr><td>mime</td><td style="background:#d96c66">not supported</td></tr><tr><td>url</td><td style="background:#7dba70">supported</td></tr><tr><td>integrity</td><td style="background:#d96c66">not supported</td></tr><tr><td rowspan="3">title</td><td>@context</td><td style="background:#bababa">unused</td></tr><tr><td>title</td><td style="background:#7dba70">supported</td></tr><tr><td>type</td><td style="background:#7dba70">supported</td></tr></table>

0 comments on commit a843a61

Please sign in to comment.