Add automatically generated documentation, CI for testing

.github/workflows/cmake-single-platform.yml

@@ -7,6 +7,7 @@ on:
     branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  workflow_dispatch:
 
 env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
@@ -22,6 +23,9 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
+    - name: Install Catch2
+      run: sudo apt-get install catch2
+
     - name: Configure CMake
       # Configure CMake in a 'build' subdirectory
       run: cmake -B ${{github.workspace}}/build 
@@ -33,5 +37,5 @@ jobs:
       working-directory: ${{github.workspace}}/build
       # Execute tests defined by the CMake configuration.
       # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
-      run: ctest --test-dir build --rerun-failed --output-on-failure
+      run: ctest --rerun-failed --output-on-failure
 

.github/workflows/make-docs.yml

@@ -0,0 +1,50 @@
+name: Build Doxide Docs
+
+on:
+  push:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+
+      - name: Install Doxide and MkDocs Material
+        run: |
+          echo 'deb http://download.indii.org/deb resolute main' | sudo tee /etc/apt/sources.list.d/indii.org.list
+          curl -fsSL https://download.indii.org/deb/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/indii.org.gpg > /dev/null
+          sudo apt update
+          sudo apt install doxide 
+          pip install mkdocs mkdocs-material
+
+      - name: Build Doxide Documentation
+        run: |
+          doxide build
+
+      - name: Build MkDocs Site
+        run: |
+          mkdocs build
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

README.md

@@ -80,16 +80,6 @@ int main() {
 }
 ```
 
-## Explaination
-
-### Philosophy of approach 
-
-This header tries to avoid JSON manipulation as much as possible. It focuses
-on a bare bones approach to RO-Crates; modelling an RO-Crate a flat list of entities, 
-where each entity is a flat list of properties. The library does not attempt to 
-model the RO-Crate specification in a more complex way, such as modelling the 
-relationships between entities.
-
 ## How-To
 
 ### Create an RO-Crate
@@ -158,6 +148,68 @@ write the RO-Crate to. This will write out the `ro-crate-metadata.json` file.
 crate.writeOut("./routput/");o
 ```
 
+## Explaination
+
+These notes are mostly aimed at developers who want to understand the design of 
+this library, but may be of interest to users as well.
+
+### Philosophy of approach 
+
+This header tries to avoid JSON manipulation as much as possible. It focuses
+on a bare bones approach to RO-Crates; modelling an RO-Crate a flat list of entities, 
+where each entity is a flat list of properties. The library does not attempt to 
+model the RO-Crate specification in a more complex way, such as modelling the 
+relationships between entities.
+
+### Entity lifecycle
+
+When an entity is created, it is not automatically added to the RO-Crate. The user 
+must explicitly add the entity to the RO-Crate using the `addEntity` method.
+
+When an entity is added to the RO-Crate, it is stored in a map of entities.
+
+For maximum flexiblity, an already added entity may still be updated on the 
+original entity object. The RO-Crate shares the same entity object, so any changes 
+made to the original entity will be reflected in the RO-Crate.
+
+Worked example:
+
+```cpp
+ROCrate crate;
+
+Entity alice({"Person"});
+alice.set("name", "Alice");
+
+crate.addEntity("#alice", alice);
+
+/* Crate state: 
+{
+  "#alice": {
+    "type": ["Person"],
+    "name": "Alice"
+  }
+}
+*/
+
+// Add an additional property to the crate entity
+Entity crateAlice = crate.getEntity("#alice");
+crateAlice.set("description", "One of hopefully many Contextual Entities");
+
+// Add an additional property to the original entity object
+alice.set("occupation", "Software Engineer");
+
+/* Crate state:
+{
+  "#alice": {
+    "type": ["Person"],
+    "name": "Alice",
+    "description": "One of hopefully many Contextual Entities",
+    "occupation": "Software Engineer"
+  }
+}
+*/
+```
+
 ## Reference
 
-Doxygen or similar reference documentation to follow.
+Reference documentation generated by [doxide](doxide.org) is available [here](http://esciencelab.org.uk/ro-crate-cpp/).

docs/javascripts/mathjax.js

@@ -0,0 +1,16 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => { 
+  MathJax.typesetPromise()
+})

docs/javascripts/tablesort.js

@@ -0,0 +1,6 @@
+document$.subscribe(function() {
+  var tables = document.querySelectorAll("article table:not([class])")
+  tables.forEach(function(table) {
+    new Tablesort(table)
+  })
+})

docs/overrides/partials/copyright.html

@@ -0,0 +1,17 @@
+<div class="md-copyright">
+  {% if config.copyright %}
+    <div class="md-copyright__highlight">
+      {{ config.copyright }}
+    </div>
+  {% endif %}
+  {% if not config.extra.generator == false %}
+    Made with
+    <a href="https://doxide.org" target="_blank" rel="noopener">
+      Doxide
+    </a>
+    and
+    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
+      Material for MkDocs
+    </a>
+  {% endif %}
+</div>

docs/stylesheets/doxide.css

@@ -0,0 +1,58 @@
+:root {
+  --md-admonition-icon--variable: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20.41 3c1.39 2.71 1.94 5.84 1.59 9-.2 3.16-1.3 6.29-3.17 9l-1.53-1c1.61-2.43 2.55-5.2 2.7-8 .34-2.8-.11-5.57-1.3-8l1.71-1M5.17 3 6.7 4C5.09 6.43 4.15 9.2 4 12c-.34 2.8.12 5.57 1.3 8l-1.69 1c-1.4-2.71-1.96-5.83-1.61-9 .2-3.16 1.3-6.29 3.17-9m6.91 7.68 2.32-3.23h2.53l-3.78 5 2.2 4.92h-2.26L11.71 14l-2.43 3.33H6.76l3.9-5.12-2.13-4.76h2.27l1.28 3.23Z"/></svg>');
+  --md-admonition-icon--function: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.6 5.29c-1.1-.1-2.07.71-2.17 1.82L13.18 10H16v2h-3l-.44 5.07a3.986 3.986 0 0 1-4.33 3.63 4.007 4.007 0 0 1-3.06-1.87l1.5-1.5c.24.74.9 1.31 1.73 1.38 1.1.1 2.07-.71 2.17-1.82L11 12H8v-2h3.17l.27-3.07c.19-2.2 2.13-3.83 4.33-3.63 1.31.11 2.41.84 3.06 1.87l-1.5 1.5c-.24-.74-.9-1.31-1.73-1.38Z"/></svg>');
+  --md-admonition-icon--typedef: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M 13.43 7.11 L 13.18 10 H 17 V 12 H 13 L 12.56 17.07 A 1 1 0 0 0 15.287 17.261 L 17.028 17.48 A 1 1 0 0 1 10.57 16.89 L 11 12 H 8 V 10 H 11.17 L 11.44 6.93 Z"/></svg>');
+  --md-admonition-icon--concept: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3.75 3.5a.25.25 0 0 0-.25.25v2.062a.75.75 0 1 1-1.5 0V3.75C2 2.783 2.783 2 3.75 2h2.062a.75.75 0 1 1 0 1.5Zm13.688-.75a.75.75 0 0 1 .75-.75h2.062c.966 0 1.75.783 1.75 1.75v2.062a.75.75 0 1 1-1.5 0V3.75a.25.25 0 0 0-.25-.25h-2.062a.75.75 0 0 1-.75-.75ZM2.75 17.438a.75.75 0 0 1 .75.75v2.062c0 .138.112.25.25.25h2.062a.75.75 0 1 1 0 1.5H3.75A1.75 1.75 0 0 1 2 20.25v-2.062a.75.75 0 0 1 .75-.75Zm18.5 0a.75.75 0 0 1 .75.75v2.062A1.75 1.75 0 0 1 20.25 22h-2.062a.75.75 0 1 1 0-1.5h2.062a.25.25 0 0 0 .25-.25v-2.062a.75.75 0 0 1 .75-.75Zm-18.5-8.25a.75.75 0 0 1 .75.75v4.124a.75.75 0 1 1-1.5 0V9.938a.75.75 0 0 1 .75-.75ZM9.188 2.75a.75.75 0 0 1 .75-.75h4.124a.75.75 0 1 1 0 1.5H9.938a.75.75 0 0 1-.75-.75Zm0 18.5a.75.75 0 0 1 .75-.75h4.124a.75.75 0 1 1 0 1.5H9.938a.75.75 0 0 1-.75-.75ZM21.25 9.188a.75.75 0 0 1 .75.75v4.124a.75.75 0 1 1-1.5 0V9.938a.75.75 0 0 1 .75-.75ZM3.75 8.25a.75.75 0 0 1 .75-.75h2a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1-.75-.75Zm5.5 0A.75.75 0 0 1 10 7.5h2A.75.75 0 0 1 12 9h-2a.75.75 0 0 1-.75-.75Zm-1-4.5A.75.75 0 0 1 9 4.5v2a.75.75 0 0 1-1.5 0v-2a.75.75 0 0 1 .75-.75Zm0 5.5A.75.75 0 0 1 9 10v2a.75.75 0 0 1-1.5 0v-2a.75.75 0 0 1 .75-.75Zm0 4.75a.75.75 0 0 1 .75.75v4a.75.75 0 0 1-1.5 0v-4a.75.75 0 0 1 .75-.75ZM14 8.25a.75.75 0 0 1 .75-.75h4a.75.75 0 0 1 0 1.5h-4a.75.75 0 0 1-.75-.75Z"/></svg>');
+  --md-admonition-icon--macro: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m5.41 21 .71-4h-4l.35-2h4l1.06-6h-4l.35-2h4l.71-4h2l-.71 4h6l.71-4h2l-.71 4h4l-.35 2h-4l-1.06 6h4l-.35 2h-4l-.71 4h-2l.71-4h-6l-.71 4h-2M9.53 9l-1.06 6h6l1.06-6h-6Z"/></svg>');
+}
+
+.md-typeset .admonition.variable, .md-typeset details.variable,
+.md-typeset .admonition.function, .md-typeset details.function,
+.md-typeset .admonition.typedef, .md-typeset details.typedef,
+.md-typeset .admonition.concept, .md-typeset details.concept,
+.md-typeset .admonition.macro, .md-typeset details.macro {
+  border-color: var(--md-default-fg-color--lighter);
+}
+
+.md-typeset .variable > .admonition-title, .md-typeset .variable > summary,
+.md-typeset .function > .admonition-title, .md-typeset .function > summary,
+.md-typeset .typedef > .admonition-title, .md-typeset .typedef > summary,
+.md-typeset .concept > .admonition-title, .md-typeset .concept > summary,
+.md-typeset .macro > .admonition-title, .md-typeset .macro > summary {
+  background-color: var(--md-default-bg-color);
+}
+
+.md-typeset .variable > .admonition-title::before,
+.md-typeset .variable > summary::before {
+  background-color: var(--md-default-fg-color--light);
+  -webkit-mask-image: var(--md-admonition-icon--variable);
+          mask-image: var(--md-admonition-icon--variable);
+}
+
+.md-typeset .function > .admonition-title::before,
+.md-typeset .function > summary::before {
+  background-color: var(--md-default-fg-color--light);
+  -webkit-mask-image: var(--md-admonition-icon--function);
+          mask-image: var(--md-admonition-icon--function);
+}
+
+.md-typeset .typedef > .admonition-title::before,
+.md-typeset .typedef > summary::before {
+  background-color: var(--md-default-fg-color--light);
+  -webkit-mask-image: var(--md-admonition-icon--typedef);
+          mask-image: var(--md-admonition-icon--typedef);
+}
+
+.md-typeset .concept > .admonition-title::before,
+.md-typeset .concept > summary::before {
+  background-color: var(--md-default-fg-color--light);
+  -webkit-mask-image: var(--md-admonition-icon--concept);
+          mask-image: var(--md-admonition-icon--concept);
+}
+
+.md-typeset .macro > .admonition-title::before,
+.md-typeset .macro > summary::before {
+  background-color: var(--md-default-fg-color--light);
+  -webkit-mask-image: var(--md-admonition-icon--macro);
+          mask-image: var(--md-admonition-icon--macro);
+}

doxide.yaml

@@ -0,0 +1,4 @@
+title: ro-crate-cpp
+description: A header only library for creating RO-Crates in C++
+files:
+  - "include/ro-crate.hpp"