From 609a08904d1c70873fc38d5717a2f257ca6a750a Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 10 Nov 2025 10:49:07 -0800 Subject: [PATCH 1/3] Remove old unused JS API doc generation files --- docs/js-sdk/sidebars.js | 2 - package.json | 13 +- .../generate-api-docs/api-sidebar-tree.ejs | 18 --- scripts/generate-api-docs/api-sidebar.ejs | 3 - scripts/generate-api-docs/index.js | 139 ------------------ scripts/generate-api-docs/sidebar-visitor.js | 111 -------------- 6 files changed, 3 insertions(+), 283 deletions(-) delete mode 100644 scripts/generate-api-docs/api-sidebar-tree.ejs delete mode 100644 scripts/generate-api-docs/api-sidebar.ejs delete mode 100644 scripts/generate-api-docs/index.js delete mode 100644 scripts/generate-api-docs/sidebar-visitor.js diff --git a/docs/js-sdk/sidebars.js b/docs/js-sdk/sidebars.js index fcebf886..289e3d2d 100644 --- a/docs/js-sdk/sidebars.js +++ b/docs/js-sdk/sidebars.js @@ -1,5 +1,3 @@ -// const api = require('./api/api-sidebar'); - const sidebars = { docs: [ { diff --git a/package.json b/package.json index a2a7f9d3..2721edb2 100644 --- a/package.json +++ b/package.json @@ -10,13 +10,12 @@ "deploy": "docusaurus deploy", "clear": "docusaurus clear", "serve": "docusaurus serve", - "postinstall": "run-p docs:*", + "postinstall": "npm run docs:fetch-readme", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids", "prepare": "husky install", "prettier": "prettier --ignore-unknown --write .", - "docs:fetch-readme": "node scripts/fetch-readme.js", - "docs:generate-api-docs": "node scripts/generate-api-docs/index.js" + "docs:fetch-readme": "node scripts/fetch-readme.js" }, "dependencies": { "@contentauth/react": "^0.2.38", @@ -46,17 +45,11 @@ ] }, "devDependencies": { - "commander": "^9.3.0", - "ejs": "^3.1.8", - "fs-extra": "^10.1.0", - "glob": "^9.0.0", "husky": "^7.0.4", "lint-staged": "^12.3.7", "node-fetch": "^2.6.7", "npm-run-all": "^4.1.5", - "prettier": "^2.6.2", - "raw-loader": "^4.0.2", - "standard-markdown-documenter": "^0.2.2" + "prettier": "^2.6.2" }, "lint-staged": { "**/*": "prettier --ignore-unknown --write" diff --git a/scripts/generate-api-docs/api-sidebar-tree.ejs b/scripts/generate-api-docs/api-sidebar-tree.ejs deleted file mode 100644 index 54cbf812..00000000 --- a/scripts/generate-api-docs/api-sidebar-tree.ejs +++ /dev/null @@ -1,18 +0,0 @@ -<% if (isSideBarItem(sideBarItems)) {%> - <%_ sideBarItems.forEach((item) => { _%> - { - type: '<%-item.type%>', - label: '<%=item.label%>', - <%_ if (item.id) {_%>id: `${dir}/<%=item.id%>`,<%_}_%> - <% if(item.type === 'category') {%>collapsed: <%-item.collapsed%>,<%}%> - <% if(item.type === 'category') {%>items: [<%- tree({ - sideBarItems: item.items, - tree: tree, - isSideBarItem: isSideBarItem - }) %>], - <%}%> - }, - <%_ }); _%> -<% } else { %> - <% sideBarItems.forEach(item => {%> '<$= item %>',<% }) %> -<%}%> \ No newline at end of file diff --git a/scripts/generate-api-docs/api-sidebar.ejs b/scripts/generate-api-docs/api-sidebar.ejs deleted file mode 100644 index f225beed..00000000 --- a/scripts/generate-api-docs/api-sidebar.ejs +++ /dev/null @@ -1,3 +0,0 @@ -// Do not edit this file. It is automatically generated by docusaurus-plugin-api-extractor. -module.exports = (dir = '<%=dir%>') => [ <%- tree({ sideBarItems: sideBarItems, -tree: tree, isSideBarItem: isSideBarItem }) %> ] \ No newline at end of file diff --git a/scripts/generate-api-docs/index.js b/scripts/generate-api-docs/index.js deleted file mode 100644 index d9f37a4d..00000000 --- a/scripts/generate-api-docs/index.js +++ /dev/null @@ -1,139 +0,0 @@ -const { join, resolve } = require('path'); -const { program } = require('commander'); -const { SIDEBAR_VISITOR } = require('./sidebar-visitor'); -const fs = require('fs'); -const { ensureDirSync, writeFileSync } = require('fs-extra'); -const { sync: glob } = require('glob'); -const { ApiModel } = require('@microsoft/api-extractor-model'); -const { StandardMarkdownDocumenter } = require('standard-markdown-documenter'); -const ejs = require('ejs'); -const prettier = require('prettier'); -const { exec } = require('child_process'); -// Added to remove pagination -const path = require('path'); -const noPaginationFrontMatterStr = - '---\npagination_next: null\npagination_prev: null\n---\n'; - -const sidebar = fs.readFileSync(join(__dirname, './api-sidebar.ejs'), 'utf-8'); -const tree = fs.readFileSync( - join(__dirname, './api-sidebar-tree.ejs'), - 'utf-8', -); - -const sidebarTmpl = ejs.compile(sidebar); -const treeTmpl = ejs.compile(tree); - -const DEFAULT_INPUT_DIR = resolve(__dirname, '../../../c2pa-js/common/api'); -const DEFAULT_OUT_DIR = resolve(__dirname, '../../docs/js-sdk/api'); - -program - .name('generate-api-docs') - .description('Generates markdown API docs from c2pa-js') - .option( - '--inputDir', - 'Path to JSON files created by api-extractor', - DEFAULT_INPUT_DIR, - ) - .option('--outDir', 'Specify where files should go', DEFAULT_OUT_DIR); - -const options = program.opts(); - -function isSideBarItem(items) { - return ( - Array.isArray(items) && - typeof items[0] === 'object' && - items[0] !== null && - 'type' in items[0] - ); -} - -// Added to remove pagination -function appendStringToFiles(directory, stringToAppend) { - fs.readdir(directory, (err, files) => { - if (err) { - console.error(err); - return; - } - - files.forEach((file) => { - const filePath = path.join(directory, file); - - fs.readFile(filePath, 'utf8', (err, data) => { - if (err) { - console.error(err); - return; - } - - const updatedData = stringToAppend + data; - - fs.writeFile(filePath, updatedData, 'utf8', (err) => { - if (err) { - console.error(err); - return; - } - - //console.log(`Appended "${stringToAppend}" to ${file}`); - }); - }); - }); - }); -} - -async function generateSidebarFile(inputDir, outDir) { - try { - ensureDirSync(outDir); - - const model = new ApiModel(); - - const globs = glob(`${inputDir}/*.json`); - - for (const resolvedPath of globs) { - model.loadPackage(resolvedPath); - } - - const documenter = new StandardMarkdownDocumenter(model, outDir); - - const sidebarNodes = await documenter.generateSidebar(SIDEBAR_VISITOR); - - const sidebarFile = prettier.format( - sidebarTmpl({ - sideBarItems: sidebarNodes, - dir: 'api', - isSideBarItem, - tree: treeTmpl, - }), - { parser: 'babel', singleQuote: true }, - ); - - writeFileSync(join(outDir, 'api-sidebar.js'), sidebarFile); - } catch (e) { - console.error(e); - process.exitCode = 1; - } -} - -async function generateMarkdownFiles(inputDir, outDir) { - return new Promise((resolve, reject) => { - exec( - `api-documenter markdown --input-folder ${inputDir} --output-folder ${outDir}`, - (err, stdout) => { - if (err) { - return reject(err); - } - - return resolve(stdout); - }, - ); - }); -} - -(async () => { - try { - await generateMarkdownFiles(options.inputDir, options.outDir); - // Added to remove pagination - await appendStringToFiles(options.outDir, noPaginationFrontMatterStr); - await generateSidebarFile(options.inputDir, options.outDir); - } catch (e) { - console.error(e); - } -})(); diff --git a/scripts/generate-api-docs/sidebar-visitor.js b/scripts/generate-api-docs/sidebar-visitor.js deleted file mode 100644 index bda1ec1a..00000000 --- a/scripts/generate-api-docs/sidebar-visitor.js +++ /dev/null @@ -1,111 +0,0 @@ -const { ApiItemKind } = require('@microsoft/api-extractor-model'); - -/** - * This is taken from the docusaurus-plugin-api-extractor codebase as specified in the - * [standard-markdown-documenter README](https://github.com/gabrielcsapo/docusaurus-plugin-api-extractor/tree/main/plugin/standard-markdown-documenter#custom-sidebar-visitor). - * @see https://github.com/gabrielcsapo/docusaurus-plugin-api-extractor/tree/main/plugin/standard-markdown-documenter#custom-sidebar-visitor - * - * @dkozma: We had to change this code because the API model parsed an `IndexSignature` from `c2pa.manifestresolvers` - * which gets picked up by the sidebar but a file doesn't get generated. I'm not sure why this is the case or how to - * fix it, so I put a hack in here to just strip the `._indexer_` suffix since standard-markdown-documenter doesn't - * seem to let me return an empty node or node that returns a valid `html` or `link` type. - */ -exports.SIDEBAR_VISITOR = { - [ApiItemKind.Package](apiItem, meta) { - return containerNode(apiItem, meta); - }, - [ApiItemKind.Namespace](apiItem, meta) { - return containerNode(apiItem, meta); - }, - [ApiItemKind.Interface](apiItem, meta) { - return containerNode(apiItem, meta); - }, - [ApiItemKind.Class](apiItem, meta) { - return containerNode(apiItem, meta); - }, - [ApiItemKind.CallSignature](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - [ApiItemKind.ConstructSignature](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - [ApiItemKind.Constructor](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - [ApiItemKind.Enum](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.EnumMember](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.Function](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.IndexSignature](apiItem, meta) { - return terminalNode( - apiItem.displayName, - meta.id.replace(/._indexer_$/, ''), - ); - }, - - [ApiItemKind.Method](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.Method](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.MethodSignature](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.Property](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.PropertySignature](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.TypeAlias](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.Variable](apiItem, meta) { - return terminalNode(apiItem.displayName, meta.id); - }, - - [ApiItemKind.Model]() { - return { - type: 'category', - label: 'Packages', - items: [terminalNode('Overview', 'index')], - collapsed: false, - }; - }, -}; - -function containerNode(apiItem, meta) { - return { - type: 'category', - label: apiItem.displayName, - collapsed: shouldCollapse(apiItem.kind), - items: [terminalNode('Overview', meta.id)], - }; -} - -function terminalNode(displayName, id) { - return { - type: 'doc', - label: displayName, - id: id, - }; -} - -function shouldCollapse(kind) { - return kind === 'Class' || kind === 'Namespace' || kind === 'Interface'; -} From d4410342bdf2acff2da58859bba9534789458279 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 10 Nov 2025 10:53:05 -0800 Subject: [PATCH 2/3] Merge old js-sdk sidebar into main sidebar --- docs/js-sdk/sidebars.js | 71 ----------------------------------------- sidebars.js | 62 +++++++++++++++++++++++++++++++++-- 2 files changed, 59 insertions(+), 74 deletions(-) delete mode 100644 docs/js-sdk/sidebars.js diff --git a/docs/js-sdk/sidebars.js b/docs/js-sdk/sidebars.js deleted file mode 100644 index 289e3d2d..00000000 --- a/docs/js-sdk/sidebars.js +++ /dev/null @@ -1,71 +0,0 @@ -const sidebars = { - docs: [ - { - type: 'category', - label: 'New JavaScript library', - link: { type: 'doc', id: 'c2pa-js/readme' }, - items: [ - { - type: 'link', - label: 'API documentation', - href: 'https://contentauth.github.io/c2pa-js/', - }, - { - type: 'link', - label: 'GitHub', - href: 'https://github.com/contentauth/c2pa-js', - }, - ], - }, - { - type: 'category', - label: 'Legacy JavaScript library', - link: { type: 'doc', id: 'js-sdk/getting-started/old-js-overview' }, - collapsed: true, - items: [ - { - type: 'doc', - label: 'Quick start', - id: 'js-sdk/getting-started/quick-start', - }, - { - type: 'doc', - label: 'Examples', - id: 'js-sdk/guides/examples', - }, - { - type: 'doc', - label: 'Architecture', - id: 'js-sdk/getting-started/architecture', - }, - { - type: 'doc', - label: 'Hosting assets', - id: 'js-sdk/guides/hosting', - }, - { - type: 'category', - label: 'Viewing manifest data', - link: { type: 'doc', id: 'js-sdk/guides/viewing-manifest-data' }, - items: ['js-sdk/guides/selectors', 'js-sdk/guides/validation'], - collapsed: true, - }, - /* - { - type: 'category', - label: 'API documentation', - items: api('js-sdk/api'), - collapsed: true, - }, - */ - { - type: 'link', - label: 'GitHub', - href: 'https://github.com/contentauth/c2pa-js-legacy', - }, - ], - }, - ], -}; - -module.exports = sidebars; diff --git a/sidebars.js b/sidebars.js index 47196b9f..2c0606ba 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1,5 +1,3 @@ -const jsSdkSidebar = require('./docs/js-sdk/sidebars'); - const sidebars = { docs: [ { @@ -209,7 +207,65 @@ const sidebars = { label: 'JavaScript library', link: { type: 'doc', id: 'js-sdk/js-landing' }, collapsed: true, - items: jsSdkSidebar.docs, + items: [ + { + type: 'category', + label: 'New JavaScript library', + link: { type: 'doc', id: 'c2pa-js/readme' }, + items: [ + { + type: 'link', + label: 'API documentation', + href: 'https://contentauth.github.io/c2pa-js/', + }, + { + type: 'link', + label: 'GitHub', + href: 'https://github.com/contentauth/c2pa-js', + }, + ], + }, + { + type: 'category', + label: 'Legacy JavaScript library', + link: { type: 'doc', id: 'js-sdk/getting-started/old-js-overview' }, + collapsed: true, + items: [ + { + type: 'doc', + label: 'Quick start', + id: 'js-sdk/getting-started/quick-start', + }, + { + type: 'doc', + label: 'Examples', + id: 'js-sdk/guides/examples', + }, + { + type: 'doc', + label: 'Architecture', + id: 'js-sdk/getting-started/architecture', + }, + { + type: 'doc', + label: 'Hosting assets', + id: 'js-sdk/guides/hosting', + }, + { + type: 'category', + label: 'Viewing manifest data', + link: { type: 'doc', id: 'js-sdk/guides/viewing-manifest-data' }, + items: ['js-sdk/guides/selectors', 'js-sdk/guides/validation'], + collapsed: true, + }, + { + type: 'link', + label: 'GitHub', + href: 'https://github.com/contentauth/c2pa-js-legacy', + }, + ], + }, + ], }, { type: 'category', From 4cea5c965bb18940e840839a5cea3ac4c21bbd2a Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 10 Nov 2025 11:03:21 -0800 Subject: [PATCH 3/3] Fix raw-loader error --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 2721edb2..5381b7f8 100644 --- a/package.json +++ b/package.json @@ -49,7 +49,8 @@ "lint-staged": "^12.3.7", "node-fetch": "^2.6.7", "npm-run-all": "^4.1.5", - "prettier": "^2.6.2" + "prettier": "^2.6.2", + "raw-loader": "^4.0.2" }, "lint-staged": { "**/*": "prettier --ignore-unknown --write"