Merge pull request #30 from contentauth/api-doc-improvement

I'm going to merge this to improve the docs served at https://contentauth.github.io/c2pa-node-v2/.

Next week, I plan to add a workflow to automate the API doc generation when there is a release (or on some other trigger) and remove the TypeDoc-generated .md files from the repo.

Author: crandmck

docs/README.md

@@ -1,3 +1,8 @@
+---
+title: README
+layout: none
+---
+
 **@contentauth/c2pa-node**
 
 ***
@@ -6,66 +11,16 @@
 
 ## [Classes](classes/index.md)
 
-- [Builder](classes/Builder.md)
-- [CallbackCredentialHolder](classes/CallbackCredentialHolder.md)
-- [CallbackSigner](classes/CallbackSigner.md)
-- [IdentityAssertionBuilder](classes/IdentityAssertionBuilder.md)
-- [IdentityAssertionSigner](classes/IdentityAssertionSigner.md)
-- [LocalSigner](classes/LocalSigner.md)
-- [Reader](classes/Reader.md)
-- [Trustmark](classes/Trustmark.md)
+{% include_relative classes/index.md %}
 
 ## [Interfaces](interfaces/index.md)
 
-- [BuilderInterface](interfaces/BuilderInterface.md)
-- [CallbackCredentialHolderInterface](interfaces/CallbackCredentialHolderInterface.md)
-- [CallbackSignerInterface](interfaces/CallbackSignerInterface.md)
-- [DestinationBufferAsset](interfaces/DestinationBufferAsset.md)
-- [FileAsset](interfaces/FileAsset.md)
-- [HashedUri](interfaces/HashedUri.md)
-- [IdentityAssertionBuilderInterface](interfaces/IdentityAssertionBuilderInterface.md)
-- [IdentityAssertionSignerInterface](interfaces/IdentityAssertionSignerInterface.md)
-- [JsCallbackSignerConfig](interfaces/JsCallbackSignerConfig.md)
-- [LocalSignerInterface](interfaces/LocalSignerInterface.md)
-- [ReaderInterface](interfaces/ReaderInterface.md)
-- [SignerPayload](interfaces/SignerPayload.md)
-- [SourceBufferAsset](interfaces/SourceBufferAsset.md)
-- [TrustConfig](interfaces/TrustConfig.md)
-- [TrustmarkConfig](interfaces/TrustmarkConfig.md)
-- [TrustmarkInterface](interfaces/TrustmarkInterface.md)
-- [VerifyConfig](interfaces/VerifyConfig.md)
+{% include_relative interfaces/index.md %}
 
 ## [Type Aliases](type-aliases/index.md)
 
-- [CallbackSignerConfig](type-aliases/CallbackSignerConfig.md)
-- [ClaimVersion](type-aliases/ClaimVersion.md)
-- [DestinationAsset](type-aliases/DestinationAsset.md)
-- [ManifestAssertionKind](type-aliases/ManifestAssertionKind.md)
-- [NeonBuilderHandle](type-aliases/NeonBuilderHandle.md)
-- [NeonCallbackCredentialHolderHandle](type-aliases/NeonCallbackCredentialHolderHandle.md)
-- [NeonCallbackSignerHandle](type-aliases/NeonCallbackSignerHandle.md)
-- [NeonIdentityAssertionBuilderHandle](type-aliases/NeonIdentityAssertionBuilderHandle.md)
-- [NeonIdentityAssertionSignerHandle](type-aliases/NeonIdentityAssertionSignerHandle.md)
-- [NeonLocalSignerHandle](type-aliases/NeonLocalSignerHandle.md)
-- [NeonReaderHandle](type-aliases/NeonReaderHandle.md)
-- [NeonTrustmarkHandle](type-aliases/NeonTrustmarkHandle.md)
-- [SigningAlg](type-aliases/SigningAlg.md)
-- [SourceAsset](type-aliases/SourceAsset.md)
-- [TrustmarkVariant](type-aliases/TrustmarkVariant.md)
-- [TrustmarkVersion](type-aliases/TrustmarkVersion.md)
+{% include_relative type-aliases/index.md %}
 
 ## [Functions](functions/index.md)
 
-- [getCawgTrustConfig](functions/getCawgTrustConfig.md)
-- [getSettingsJson](functions/getSettingsJson.md)
-- [getTrustConfig](functions/getTrustConfig.md)
-- [getVerifyConfig](functions/getVerifyConfig.md)
-- [isActionsAssertion](functions/isActionsAssertion.md)
-- [loadC2paSettings](functions/loadC2paSettings.md)
-- [loadC2paSettingsToml](functions/loadC2paSettingsToml.md)
-- [loadCawgTrustConfig](functions/loadCawgTrustConfig.md)
-- [loadSettingsFromFile](functions/loadSettingsFromFile.md)
-- [loadSettingsFromUrl](functions/loadSettingsFromUrl.md)
-- [loadTrustConfig](functions/loadTrustConfig.md)
-- [loadVerifyConfig](functions/loadVerifyConfig.md)
-- [patchVerifyConfig](functions/patchVerifyConfig.md)
+{% include_relative functions/index.md %}

docs/_includes/nav-items.html

@@ -1,8 +1,8 @@
+{%- assign nav_items = "Classes, Interfaces, Type Aliases, Functions" | split: ", " -%}
 <div class="nav-items">
-  {%- for path in include.paths -%}
-  {%- assign hyperpage = site.pages | where: "path", path | first -%}
-  {%- if hyperpage.title %}
-  <a class="nav-item" href="{{ hyperpage.url | relative_url }}">{{ hyperpage.title | escape }}</a>
-  {%- endif -%}
-  {%- endfor %}
+  {% for item in nav_items %}
+    {%- assign path = '/' | append: (item | slugify) | append: '/' -%}
+    <a class="nav-item" href="{{ path | relative_url }}">{{ item }}</a>
+  {% endfor %}
 </div>
+

docs/_includes/sidebar.html

@@ -1,10 +1,8 @@
-{%- assign readme_page = site.pages | where: "path", "README.md" | first -%}
+{%- assign readme_page = site.pages | where: "name", "README.md" | first -%}
+
 {%- if readme_page -%}
   <nav class="sidebar-content">
-    {%- assign _c = readme_page.content -%}
-    {%- assign _c = _c | replace: "This is API documentation for the C2PA Node.js library.", "" -%}
-    {%- assign _c = _c | replace: "# @contentauth/c2pa-node", "" -%}
-    {{ _c | strip | markdownify }}
+    {{ readme_page.content | strip | markdownify }}
   </nav>
 {%- endif -%}
 

docs/assets/css/cai-custom.css

@@ -14,8 +14,7 @@
   max-width: 320px;
 }
 .sidebar-content { font-size: 0.95em; line-height: 1.45; }
-.sidebar-content h1 { font-size: 1.1rem; margin-top: 1rem; }
-.sidebar-content h2 { font-size: 1rem; margin-top: 0.9rem; }
+.sidebar-content h2 { font-size: 1.5rem; margin-top: 0.9rem; } 
 .sidebar-content h3 { font-size: 0.95rem; margin-top: 0.8rem; }
 .sidebar-content ul { list-style: none; padding-left: 0; }
 .sidebar-content li { margin: 0.25rem 0; }
@@ -46,6 +45,8 @@
 
 .sidebar-content > p:first-child { display: none; }
 .sidebar-content hr { display: none; }
+.sidebar-content h1 { display: none; }
+
 
 @media (max-width: 900px) {
   .site-layout { grid-template-columns: 1fr; }

docs/classes/index.md

@@ -1,10 +1,17 @@
 # Classes
 
-- [Builder](Builder.md)
-- [CallbackCredentialHolder](CallbackCredentialHolder.md)
-- [CallbackSigner](CallbackSigner.md)
-- [IdentityAssertionBuilder](IdentityAssertionBuilder.md)
-- [IdentityAssertionSigner](IdentityAssertionSigner.md)
-- [LocalSigner](LocalSigner.md)
-- [Reader](Reader.md)
-- [Trustmark](Trustmark.md)
+{%- assign classes_root = site.baseurl | append: '/classes/' -%}
+{%- assign class_pages = site.pages | where_exp: 'p', "p.url contains '/classes/'" -%}
+{%- assign class_pages = class_pages | reject: 'url', classes_root -%}
+{% assign class_pages = class_pages | sort: 'name' %}
+
+{% if class_pages and class_pages.size > 0 %}
+{%- for p in class_pages -%}
+{% assign label = p.name | replace: '.md','' | replace: '.html','' %}
+{%- unless p.name=="index.md" %}
+- <a href="{{ p.url | relative_url }}">{{ label }}</a> 
+{%- endunless -%}
+{%- endfor -%}
+{%- else -%}
+No classes found.
+{%- endif -%}

docs/functions/index.md

@@ -1,15 +1,17 @@
 # Functions
 
-- [getCawgTrustConfig](getCawgTrustConfig.md)
-- [getSettingsJson](getSettingsJson.md)
-- [getTrustConfig](getTrustConfig.md)
-- [getVerifyConfig](getVerifyConfig.md)
-- [isActionsAssertion](isActionsAssertion.md)
-- [loadC2paSettings](loadC2paSettings.md)
-- [loadC2paSettingsToml](loadC2paSettingsToml.md)
-- [loadCawgTrustConfig](loadCawgTrustConfig.md)
-- [loadSettingsFromFile](loadSettingsFromFile.md)
-- [loadSettingsFromUrl](loadSettingsFromUrl.md)
-- [loadTrustConfig](loadTrustConfig.md)
-- [loadVerifyConfig](loadVerifyConfig.md)
-- [patchVerifyConfig](patchVerifyConfig.md)
+{%- assign functions_root = site.baseurl | append: '/functions/' -%}
+{%- assign functions_pages = site.pages | where_exp: 'p', "p.url contains '/functions/'" -%}
+{%- assign functions_pages = functions_pages | reject: 'url', functions_root -%}
+{% assign functions_pages = functions_pages | sort: 'name' %}
+
+{% if functions_pages and functions_pages.size > 0 %}
+{%- for p in functions_pages -%}
+{% assign label = p.name | replace: '.md','' | replace: '.html','' %}
+{%- unless p.name=="index.md" %}
+- <a href="{{ p.url | relative_url }}">{{ label }}</a> 
+{%- endunless -%}
+{%- endfor -%}
+{%- else -%}
+No functions found.
+{%- endif -%}

docs/index.md

@@ -0,0 +1,13 @@
+---
+layout: base
+title: C2PA Node.js library
+---
+
+This is the API reference documentation for the C2PA Node.js library generated using TypeDoc.
+
+- [Classes](./classes/)
+- [Interfaces](./interfaces/)
+- [Type Aliases](./type-aliases/)
+- [Functions](./functions/)
+
+

docs/interfaces/index.md

@@ -1,19 +1,17 @@
 # Interfaces
 
-- [BuilderInterface](BuilderInterface.md)
-- [CallbackCredentialHolderInterface](CallbackCredentialHolderInterface.md)
-- [CallbackSignerInterface](CallbackSignerInterface.md)
-- [DestinationBufferAsset](DestinationBufferAsset.md)
-- [FileAsset](FileAsset.md)
-- [HashedUri](HashedUri.md)
-- [IdentityAssertionBuilderInterface](IdentityAssertionBuilderInterface.md)
-- [IdentityAssertionSignerInterface](IdentityAssertionSignerInterface.md)
-- [JsCallbackSignerConfig](JsCallbackSignerConfig.md)
-- [LocalSignerInterface](LocalSignerInterface.md)
-- [ReaderInterface](ReaderInterface.md)
-- [SignerPayload](SignerPayload.md)
-- [SourceBufferAsset](SourceBufferAsset.md)
-- [TrustConfig](TrustConfig.md)
-- [TrustmarkConfig](TrustmarkConfig.md)
-- [TrustmarkInterface](TrustmarkInterface.md)
-- [VerifyConfig](VerifyConfig.md)
+{%- assign interfaces_root = site.baseurl | append: '/interfaces/' -%}
+{%- assign interfaces_pages = site.pages | where_exp: 'p', "p.url contains '/interfaces/'" -%}
+{%- assign interfaces_pages = interfaces_pages | reject: 'url', interfaces_root -%}
+{% assign interfaces_pages = interfaces_pages | sort: 'name' %}
+
+{% if interfaces_pages and interfaces_pages.size > 0 %}
+{%- for p in interfaces_pages -%}
+{% assign label = p.name | replace: '.md','' | replace: '.html','' %}
+{%- unless p.name=="index.md" %}
+- <a href="{{ p.url | relative_url }}">{{ label }}</a> 
+{%- endunless -%}
+{%- endfor -%}
+{%- else -%}
+No interfaces found.
+{%- endif -%}

docs/type-aliases/index.md

@@ -1,18 +1,17 @@
 # Type Aliases
 
-- [CallbackSignerConfig](CallbackSignerConfig.md)
-- [ClaimVersion](ClaimVersion.md)
-- [DestinationAsset](DestinationAsset.md)
-- [ManifestAssertionKind](ManifestAssertionKind.md)
-- [NeonBuilderHandle](NeonBuilderHandle.md)
-- [NeonCallbackCredentialHolderHandle](NeonCallbackCredentialHolderHandle.md)
-- [NeonCallbackSignerHandle](NeonCallbackSignerHandle.md)
-- [NeonIdentityAssertionBuilderHandle](NeonIdentityAssertionBuilderHandle.md)
-- [NeonIdentityAssertionSignerHandle](NeonIdentityAssertionSignerHandle.md)
-- [NeonLocalSignerHandle](NeonLocalSignerHandle.md)
-- [NeonReaderHandle](NeonReaderHandle.md)
-- [NeonTrustmarkHandle](NeonTrustmarkHandle.md)
-- [SigningAlg](SigningAlg.md)
-- [SourceAsset](SourceAsset.md)
-- [TrustmarkVariant](TrustmarkVariant.md)
-- [TrustmarkVersion](TrustmarkVersion.md)
+{%- assign type_aliases_root = site.baseurl | append: '/type-aliases/' -%}
+{%- assign type_aliases_pages = site.pages | where_exp: 'p', "p.url contains '/type-aliases/'" -%}
+{%- assign type_aliases_pages = type_aliases_pages | reject: 'url', type_aliaseses_root -%}
+{% assign type_aliases_pages = type_aliases_pages | sort: 'name' %}
+
+{% if type_aliases_pages and type_aliases_pages.size > 0 %}
+{%- for p in type_aliases_pages -%}
+{% assign label = p.name | replace: '.md','' | replace: '.html','' %}
+{%- unless p.name=="index.md" %}
+- <a href="{{ p.url | relative_url }}">{{ label }}</a> 
+{%- endunless -%}
+{%- endfor -%}
+{%- else -%}
+No type aliases found.
+{%- endif -%}

package.json

@@ -22,7 +22,7 @@
   "scripts": {
     "build": "run-s build:rust build:ts",
     "build:debug": "run-s build:rust-debug build:ts",
-    "build:docs": "rimraf docs && typedoc --plugin typedoc-plugin-markdown --readme none --out docs js-src/index.ts",
+    "build:docs": "rimraf docs-typedoc && typedoc --plugin typedoc-plugin-markdown --readme none --out docs-typedoc js-src/index.ts && cpy \"docs-typedoc/**\" docs --parents --overwrite --ignore=\"docs-typedoc/classes/index.md\" --ignore=\"docs-typedoc/README.md\" && rimraf docs-typedoc",
     "build:rust": "pnpm run build:rust-debug --release",
     "build:rust-debug": "cargo build --message-format=json-render-diagnostics > cargo.log",
     "build:ts": "tsc -b && cpy index.node dist && cpy index.node js-src && cpy --flat js-src/types.d.ts dist/types",