Tools page refactor (fixes #124)

CONTRIBUTING.md

@@ -194,3 +194,45 @@ pairs `aspect`, `description`, `class`, and `link`.
 
 Keeping the JSON file ordered by the `aspect` number will make it easier to
 identify which Aspects are represented already.
+
+### Updating the Tools page
+
+The [Tools page](https://codemeta.github.io/tools/) structure is defined in
+two shortcodes: `/layouts/shortcodes/tools.md` and 
+`/layouts/shortcodes/unsupported-tools`.
+
+Those shortcodes pull data from the JSON in the `/data/tool_categories.json`
+and `data/tools.json` files, and from `.Site.Params.supported` which tracks
+the current versions the website considers to be "Supported".
+
+To add a new supported version, add a new item to the array in the `supported`
+array. It is in the `Params` section of `/config.toml`.
+
+To add a new tool:
+
+- Add a new object to the array in `data/tools.json`, with the following
+key-value pairs:
+  - `name` is the name of the tool or project,
+  - `language` is the tool's primary language, schema, etc. Useful for choosing
+  a tool within limitations of an existing tech stack.
+  - `versions` is an array of the versions that the tool has been tested with
+  and found to be functional.
+  - `maintainers` is an array of the maintainers. It consists of:
+    - `name` is the name of the maintainer. Both individuals and groups are
+    acceptable.
+    - `url` *(optional)* can be any appropriate contact page for reaching out
+    to the maintainer about the tool, if needed. This is typically a code forge
+    account page, which that party has committed to the project with.
+  - `description` is a sentance or two that explains what the tool does.
+  - `url` is a link to a website where people may acquire the tool.
+  - `categories` is a list of the categories the tool falls into. If the
+  category has not beeb added to `/data/tool_categories.json`, there will be no
+  section or table created for it on the page.
+
+  To add a new tool category:
+
+  - Add a new object to the array in `/data/tool_categories.json` with the following
+  key-value pairs:
+    `name` is a descriptive name for the category,
+    `description` is a few sentences of text that introduces the category to
+    potential users.

config.toml

@@ -60,6 +60,10 @@ publishDir = "../website"
     github =  "codemeta"
     repo = "codemeta.github.io"
     background = "img/pyramids.jpg"
+    supported = [
+        '3.0.0',
+        '2.0.0'
+    ]
 
     newslimit = 5
     feeds = [

content/tools.md

@@ -3,39 +3,53 @@ title: Tools
 layout: sidenav
 ---
 
-This page lists some existing tools to help with CodeMeta files.
-
-## File Generation
-
-Some of the early tools still need a little updating to use the latest version of the CodeMeta context.
-
-Name | Language | CodeMeta versions | Maintainers | Description
------|----------|-------------------|-------------|------------
-[AutoCodemeta Generator](https://w3id.org/autocodemeta) | JavaScript | 3.0.0 | [dgarijo](http://github.com/dgarijo) | Optimized version of CodeMeta Generator that automatically creates a CodeMeta file from a given repository
-[Bolognese](https://github.com/datacite/bolognese) | Ruby | 1.0.0 | [mfenner](https://github.com/mfenner) | Primarily a tool for conversion between formats provided by DataCite, including CodeMeta and schema.org
-[cff-converter](https://github.com/citation-file-format/cff-converter-python) | Python | 2.0.0 | [jspaaks](https://github.com/jspaaksh) | Convert `CITATION.cff` files to codemeta
-[CodeMeta file generator](https://gist.github.com/arfon/478b2ed49e11f984d6fb) | Ruby | 0.1.0 | [arfon](http://github.com/arfon) | (no support for current schema)
-[CodeMeta generator](https://codemeta.github.io/codemeta-generator/) | JavaScript | 2.0.0, 3.0.0 | [ProgVal](https://github.com/ProgVal) | Online form to create or complete a CodeMeta file
-[codemeta-harvester](https://github.com/proycon/codemeta-harvester) | POSIX Shell | 2.0.0, 3.0.0 | [proycon](https://github.com/proycon) | Automatic software metadata conversion pipeline that uses codemetapy and other tools
-[codemeta-server](https://github.com/proycon/codemeta-server) | Python | 2.0.0, 3.0.0 | [proycon](https://github.com/proycon) | Webservice offering an API (including SPARQL) and simple human web-interface so search and browse software metadata
-[codemetapy](https://github.com/proycon/codemetapy) | Python | 2.0.0, 3.0.0 | [proycon](https://github.com/proycon) | Generate CodeMeta for Python, NodeJS, Java packages and others; + generic CodeMeta manipulation
-[codemetar](https://ropensci.github.io/codemetar) | R | 2.0.0 | [cboettig](https://github.com/cboettig) | Generate CodeMeta for R packages; + generic CodeMeta manipulation
-[FACILE-RS](https://git.opencarp.org/openCARP/FACILE-RS) | Python | 2.0.0 | [MarieHouillon](https://github.com/MarieHouillon) | Metadata conversion (to Citation File Format (CFF), DataCite, BagIt and BagPack) and software publication pipelines based on CodeMeta. Previously known as openCARP-CI.
-[Somef](https://github.com/KnowledgeCaptureAndDiscovery/somef) | Python | OEG developers | [dgarijo](http://github.com/dgarijo) | Tool that automatically extracts software metadata from repositories and scientific publications
-[tributors](https://con.github.io/tributors/) | Python | 2.0.0 | [vsoch](https://github.com/vsoch) | Generate CodeMeta contributors section from GitHub API and ORCID API
-{.table .table-striped}
-
-## Integrations
-
-Integrations indicate existing platforms & services which understand CodeMeta descriptions.
-These do not provide a user-facing software tool for generating codemeta.json, but can ingest
-existing codemeta.json files automatically.
-
-Name | Language | CodeMeta versions | Maintainers | Description
------|----------|-------------------|-------------|------------
-[Fidgit](https://github.com/arfon/fidgit) | Ruby | 0.1.0 | Arfon Smith, Kaitlin Thaney, Mark Hahnel | An ungodly union of GitHub and Figshare
-[Software Heritage](https://docs.softwareheritage.org/devel/swh-indexer/metadata-workflow.html#adding-support-for-additional-ecosystem-specific-metadata) | Python | 2.0 | SWH team | The metadata indexers
-{.table .table-striped}
+This page lists some existing tools to help with CodeMeta files. They range from scripts to services, and can help you create, convert, validate, and visualize CodeMeta data.
+
+The list is not exhaustive. You are invited to submit new tools, or update the listings for existing tools! This can be done in [this website's repository](https://github.com/codemeta/codemeta.github.io?tab=contributing-ov-file#updating-the-tools-page)
+
+## Choosing Tools
+
+### A Quick Start
+
+If you need a `codemeta.json` quickly, the [Web-Based Generators](#web-based-generators) are the best option.
+
+These tools do not need anything except your browser. They provide a helpful form for you to fill out, and allow you to see and refine the output, while ensuring it is valid.
+
+The [CodeMeta Generator](/create) is the reference generator implementation, and is best used for simple projects.
+
+### Use Existing Data
+
+The tools in the table of [Converters](#converters) can migrate data to and from various other formats. If you already have the necessary information in a `citation.cff`, a package manifest, or even your Git repository's API, you can easily adapt it to CodeMeta.
+
+### A Tool for Your Stack
+
+Our [table of libraries](#libraries) table lists tools packaged for specitic languages or environments, while [Generation Utilities](#generation-utilities) can be integrated into many pipelines.
+
+### Keep in Sync
+
+If you need to automate your metadata publishing, you can also find [Publishing Pipelines](#publishing-pipelines). These can work with your existing deployment or CI/CD workflows, and can help you keep your metadata in sync across multiple locations.
+
+## Tools for Supported Versions
+
+The tables in this section contain tools for supported versions of CodeMeta.'
+
+Note: Tools marked with a warning symbol ( ⚠️ ) are not known to support the *latest version* of CodeMeta.
+{.tip}
+
+These tools are categorised according to the context they can be used. In many cases a tool belongs to multiple categories and will be listed multiple times on this page.
+
+{{% tools %}}
+
+
+## Tools for Unsupported Versions
+
+These tools have not been verified to work on supported versions of CodeMeta. They may not work as expected, if at all.
+
+While out of date, these tools may provide a good starting point for a new tool, instead of starting from scratch.
+
+
+{{% unsupported-tools %}}
+
 
 Pending:
 

data/tool_categories.json

@@ -0,0 +1,26 @@
+[
+  {
+    "name": "Web-based Generators",
+    "desc": "These are easy-to-use web forms. Once filled out with the required information, they output complete and valid codemeta data which can be reviwed and edited before being downloaded or copied elsewhere. The output can be directly used in a `codemeta.json file`."
+  },
+  {
+    "name": "Converters",
+    "desc": "Tools which pull data from other metadata formats or APIs, and reformats that information into data formatted for codemeta."
+  },
+  {
+    "name": "Generation Utilities",
+    "desc": "These are tools which are usually invoked in a terminal context and interacted with using command-line arguments, to generate partial or complete codemeta output."
+  },
+  {
+    "name": "Libraries",
+    "desc": "Components installed using a language or environment package manager, which facilitates the ingestion or outputting of codemeta data."
+  },
+  {
+    "name": "Publication Pipelines",
+    "desc": "Tools which help automate publishing processes based on codemeta data, via pipelines such as uploads, CI/CD, etc,."
+  },
+  {
+    "name": "Service Integrations",
+    "desc": "Services which make use of other codemeta-related tools to provide a product or service."
+  }
+]

data/tools.json

@@ -0,0 +1,159 @@
+[
+  {
+    "name": "AutoCodemeta Generator",
+    "language": "JavaScript",
+    "versions": ["3.0.0"],
+    "maintainers": [
+      {"name": "dgarijo", "url": "https://github.com/dgarijo"}
+    ],
+    "description": "Optimized version of CodeMeta Generator that automatically creates a CodeMeta file from a given repository",
+    "url": "https://w3id.org/autocodemeta",
+    "categories": ["Web-based Generators"]
+  },
+  {
+    "name": "Bolognese",
+    "language": "Ruby",
+    "versions": ["1.0.0"],
+    "maintainers": [
+      {"name": "mfenner", "url": "https://github.com/mfenner"}
+    ],
+    "description": "Primarily a tool for conversion between formats provided by DataCite, including CodeMeta and schema.org",
+    "url": "https://github.com/datacite/bolognese",
+    "categories": ["Converters", "Libraries", "Generation Utilities", "Publication Pipelines"]
+  },
+  {
+    "name": "cff-converter",
+    "language": "Python",
+    "versions": ["2.0.0"],
+    "maintainers": [
+      {"name": "jspaaks", "url": "https://github.com/jspaaks"}
+    ],
+    "description": "Convert CITATION.cff files to codemeta",
+    "url": "https://github.com/citation-file-format/cff-converter-python",
+    "categories": ["Converters"]
+  },
+  {
+    "name": "CodeMeta file generator",
+    "language": "Ruby",
+    "versions": ["0.1.0"],
+    "maintainers": [
+      {"name": "arfon", "url": "https://github.com/arfon"}
+    ],
+    "description": "(no support for current schema)",
+    "url": "https://gist.github.com/arfon/478b2ed49e11f984d6fb",
+    "categories": ["Generation Utilities"]
+  },
+  {
+    "name": "CodeMeta generator",
+    "language": "JavaScript",
+    "versions": ["2.0.0", "3.0.0"],
+    "maintainers": [
+      {"name": "ProgVal", "url": "https://github.com/ProgVal"}
+    ],
+    "description": "Online form to create or complete a CodeMeta file",
+    "url": "https://codemeta.github.io/codemeta-generator/",
+    "categories": ["Web-based Generators"]
+  },
+  {
+    "name": "codemeta-harvester",
+    "language": "POSIX Shell",
+    "versions": ["2.0.0", "3.0.0"],
+    "maintainers": [
+      {"name": "proycon", "url": "https://github.com/proycon"}
+    ],
+    "description": "Automatic software metadata conversion pipeline that uses codemetapy and other tools",
+    "url": "https://github.com/proycon/codemeta-harvester",
+    "categories": ["Converters", "Generation Utilities"]
+  },
+  {
+    "name": "codemeta-server",
+    "language": "Python",
+    "versions": ["2.0.0", "3.0.0"],
+    "maintainers": [
+      {"name": "proycon", "url": "https://github.com/proycon"}
+    ],
+    "description": "Webservice offering an API (including SPARQL) and simple human web-interface to search and browse software metadata",
+    "url": "https://github.com/proycon/codemeta-server",
+    "categories": ["Service Integrations"]
+  },
+  {
+    "name": "codemetapy",
+    "language": "Python",
+    "versions": ["2.0.0", "3.0.0"],
+    "maintainers": [
+      {"name": "proycon", "url": "https://github.com/proycon"}
+    ],
+    "description": "Generate CodeMeta for Python, NodeJS, Java packages and others; + generic CodeMeta manipulation",
+    "url": "https://github.com/proycon/codemetapy",
+    "categories": ["Converters", "Libraries", "Generation Utilities"]
+  },
+  {
+    "name": "codemetar",
+    "language": "R",
+    "versions": ["2.0.0"],
+    "maintainers": [
+      {"name": "cboettig", "url": "https://github.com/cboettig"}
+    ],
+    "description": "Generate CodeMeta for R packages; + generic CodeMeta manipulation",
+    "url": "https://ropensci.github.io/codemetar",
+    "categories": ["Converters", "Libraries"]
+  },
+  {
+    "name": "FACILE-RS",
+    "language": "Python",
+    "versions": ["2.0.0"],
+    "maintainers": [
+      {"name": "MarieHouillon", "url": "https://github.com/MarieHouillon"}
+    ],
+    "description": "Metadata conversion (to Citation File Format (CFF), DataCite, BagIt and BagPack) and software publication pipelines based on CodeMeta. Previously known as openCARP-CI.",
+    "url": "https://git.opencarp.org/openCARP/FACILE-RS",
+    "categories": ["Converters", "Publication Pipelines"]
+  },
+  {
+    "name": "Somef",
+    "language": "Python",
+    "versions": ["3.0.0"],
+    "maintainers": [
+      {"name": "OEG developers"},
+      {"name": "dgarijo", "url": "https://github.com/dgarijo"}
+    ],
+    "description": "Tool that automatically extracts software metadata from repositories and scientific publications",
+    "url": "https://github.com/KnowledgeCaptureAndDiscovery/somef",
+    "categories": ["Converters"]
+  },
+  {
+    "name": "tributors",
+    "language": "Python",
+    "versions": ["2.0.0"],
+    "maintainers": [
+      {"name": "vsoch", "url": "https://github.com/vsoch"}
+    ],
+    "description": "Generate CodeMeta contributors section from GitHub API and ORCID API",
+    "url": "https://con.github.io/tributors/",
+    "categories": ["Converters", "Generation Utilities"]
+  },
+  {
+    "name": "Fidgit",
+    "language": "Ruby",
+    "versions": ["0.1.0"],
+    "maintainers": [
+      {"name": "Arfon Smith"},
+      {"name": "Kaitlin Thaney"},
+      {"name": "Mark Hahnel"}
+    ],
+    "description": "An ungodly union of GitHub and Figshare",
+    "url": "https://github.com/arfon/fidgit",
+    "categories": ["Service Integrations"]
+  },
+  {
+    "name": "Software Heritage",
+    "language": "Python",
+    "versions": ["2.0.0"],
+    "maintainers": [
+      {"name": "SWH team"}
+    ],
+    "description": "The metadata indexers",
+    "url": "https://docs.softwareheritage.org/devel/swh-indexer/metadata-workflow.html",
+    "categories": ["Service Integrations"]
+  }
+]

layouts/shortcodes/tools.md

@@ -0,0 +1,40 @@
+{{ $supported := .Site.Params.supported }}
+
+{{ $latest := $supported | sort | collections.Reverse }}
+{{ $latest := index $latest 0 }}
+
+{{ $tools := .Site.Data.tools }}
+{{ range $cats := .Site.Data.tool_categories }}
+{{ $cat := index $cats }}
+
+### {{ $cat.name }}
+
+{{ $cat.desc }}
+
+<table class="table table-striped">
+  <tr>
+    <th>Tool name</th>
+    <th>Language</th>
+    <th>Maintainers</th>
+    <th>Versions</th>
+    <th>Description</th>
+  </tr>
+  {{ range $tools }}
+    {{ if in $supported (index .versions 0 ) }}
+      {{- if in .categories $cat.name }}
+
+
+  <tr>
+    <td><a href="{{ .url }}">{{ .name }}</a></td>
+    <td>{{ .language }}</td>
+    <td>{{ $icnt := sub (.maintainers | len) 1 }}{{- range $i, $mtnrs := .maintainers }}{{ $mtnr := index $mtnrs }}{{ if $mtnr.url }}<a href="{{ $mtnr.url }}">{{ $mtnr.name }}</a>{{ else }}{{ $mtnr.name }}{{ end }}{{ if lt $i $icnt }},{{end}}<br>{{ end -}}</td>
+    <td>{{ if in .versions $latest | not }} ⚠️ {{ end }}
+    {{ delimit .versions  ", " }}</td>
+    <td>{{ .description }}</td>
+  </tr>
+    {{ end -}}
+    {{ end }}
+  {{ end }}
+  </table>
+{{ end }}
+