From 70e7420ca78abbed51cd7d3ac5574265bc1bcdbe Mon Sep 17 00:00:00 2001 From: Dale Sande Date: Tue, 6 Feb 2024 22:34:25 -0800 Subject: [PATCH] docs: update to show accurate deps versions Changes to be committed: modified: README.md modified: docTemplates/README.md modified: package-lock.json modified: package.json modified: scripts/generateDocs.mjs --- README.md | 11 +++-- docTemplates/README.md | 2 +- package-lock.json | 8 ++-- package.json | 2 +- scripts/generateDocs.mjs | 94 +++++++++++++++++++++------------------- 5 files changed, 60 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 148bc44..86e7278 100644 --- a/README.md +++ b/README.md @@ -98,19 +98,18 @@ import "@aurodesignsystem/auro-background"; In cases where the project is not able to process JS assets, there are pre-processed assets available for use. See -- `auro-background__bundled.js` for modern browsers. Legacy browsers such as IE11 are no longer supported. -We recommend you load these bundles using [differential serving](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/) so that the browser only loads the bundle correctly. To accomplish this, the script tag for the modern bundle should have `type="module"` and the script tag. +**WARNING!** When installing into your application environment, DO NOT use `@latest` for the requested version. Risks include unknown MAJOR version releases and instant adoption of any new features and possible bugs without developer knowledge. The `@latest` wildcard should NEVER be used for production customer-facing applications. You have been warned. ### Bundle example code - + ```html - - - - + + + ``` diff --git a/docTemplates/README.md b/docTemplates/README.md index 6558a7d..530d1ed 100644 --- a/docTemplates/README.md +++ b/docTemplates/README.md @@ -64,7 +64,7 @@ The following sections are editable by making changes to the following files: ### Bundle example code - + ## [namespace]-[name] use cases diff --git a/package-lock.json b/package-lock.json index 5702dd4..32baa5d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14,7 +14,7 @@ "lit": "^3.1.1" }, "devDependencies": { - "@aurodesignsystem/auro-library": "^2.4.0", + "@aurodesignsystem/auro-library": "^2.4.7", "@aurodesignsystem/design-tokens": "^4.3.1", "@aurodesignsystem/eslint-config": "^1.3.1", "@aurodesignsystem/webcorestylesheets": "^5.0.6", @@ -99,9 +99,9 @@ } }, "node_modules/@aurodesignsystem/auro-library": { - "version": "2.4.0", - "resolved": "https://registry.npmjs.org/@aurodesignsystem/auro-library/-/auro-library-2.4.0.tgz", - "integrity": "sha512-6yGfVJBjOPzmA/rqCpBswc2vWxvEb3/Xp6iLgJLgzRLUW+c6J10bKU5ebtIuOJF5adMWa3WOctCCMrF6Fmi9WQ==", + "version": "2.4.7", + "resolved": "https://registry.npmjs.org/@aurodesignsystem/auro-library/-/auro-library-2.4.7.tgz", + "integrity": "sha512-R6qJqQqO9Jpu475D9rpIei6wEIYL1v57YFyFViYa13/DrLRlzSKMUubJCdIIwNtm/8qvvKf0VWVBpZfevRmp+Q==", "dev": true, "dependencies": { "markdown-magic": "^2.6.1" diff --git a/package.json b/package.json index e33182f..290278c 100644 --- a/package.json +++ b/package.json @@ -28,7 +28,7 @@ "@aurodesignsystem/webcorestylesheets": "^5.0.5" }, "devDependencies": { - "@aurodesignsystem/auro-library": "^2.4.0", + "@aurodesignsystem/auro-library": "^2.4.7", "@aurodesignsystem/design-tokens": "^4.3.1", "@aurodesignsystem/eslint-config": "^1.3.1", "@aurodesignsystem/webcorestylesheets": "^5.0.6", diff --git a/scripts/generateDocs.mjs b/scripts/generateDocs.mjs index d178ec5..e261b15 100644 --- a/scripts/generateDocs.mjs +++ b/scripts/generateDocs.mjs @@ -1,8 +1,3 @@ -/** - * This version is sans dependencies - * Create for use with the SSR updates - */ - import path from 'path'; import markdownMagic from 'markdown-magic'; import fs from 'fs'; @@ -19,28 +14,34 @@ const readmeFilePath = dirDocTemplates + '/README.md'; */ function nameExtraction() { - const packageJson = fs.readFileSync('package.json', 'utf8', function(err, data) { - if (err) { - console.log('ERROR: Unable to read package.json file', err); - } - }) - - let pName = JSON.parse(packageJson).name; - - let npmStart = pName.indexOf('@'); - let namespaceStart = pName.indexOf('/'); - let nameStart = pName.indexOf('-'); - - let result = { - 'npm': pName.substring(npmStart, namespaceStart), - 'namespace': pName.substring(namespaceStart + 1, nameStart), - 'namespaceCap': pName.substring(namespaceStart + 1)[0].toUpperCase() + pName.substring(namespaceStart + 2, nameStart), - 'name': pName.substring(nameStart + 1), - 'nameCap': pName.substring(nameStart + 1)[0].toUpperCase() + pName.substring(nameStart + 2) - }; - - return result; -} + const packageJson = fs.readFileSync('package.json', 'utf8', function(err, data) { + if (err) { + console.log('ERROR: Unable to read package.json file', err); + } + }) + + let pName = JSON.parse(packageJson).name; + let pVersion = JSON.parse(packageJson).version; + let pdtVersion = JSON.parse(packageJson).peerDependencies['\@aurodesignsystem/design-tokens'].substring(1) + let wcssVersion = JSON.parse(packageJson).peerDependencies['\@aurodesignsystem/webcorestylesheets'].substring(1) + + let npmStart = pName.indexOf('@'); + let namespaceStart = pName.indexOf('/'); + let nameStart = pName.indexOf('-'); + + let result = { + 'npm': pName.substring(npmStart, namespaceStart), + 'namespace': pName.substring(namespaceStart + 1, nameStart), + 'namespaceCap': pName.substring(namespaceStart + 1)[0].toUpperCase() + pName.substring(namespaceStart + 2, nameStart), + 'name': pName.substring(nameStart + 1), + 'nameCap': pName.substring(nameStart + 1)[0].toUpperCase() + pName.substring(nameStart + 2), + 'version': pVersion, + 'tokensVersion': pdtVersion, + 'wcssVersion': wcssVersion + }; + + return result; + } /** * Replace all instances of [npm], [name], [Name], [namespace] and [Namespace] accordingly @@ -54,10 +55,13 @@ function formatTemplateFileContents(content, destination) { * Replace placeholder strings */ result = result.replace(/\[npm]/g, nameExtractionData.npm); - result = result.replace(/\[name]/g, nameExtractionData.name); - result = result.replace(/\[Name]/g, nameExtractionData.nameCap); + result = result.replace(/\[name](?!\()/g, nameExtractionData.name); + result = result.replace(/\[Name](?!\()/g, nameExtractionData.nameCap); result = result.replace(/\[namespace]/g, nameExtractionData.namespace); result = result.replace(/\[Namespace]/g, nameExtractionData.namespaceCap); + result = result.replace(/\[Version]/g, nameExtractionData.version); + result = result.replace(/\[dtVersion]/g, nameExtractionData.tokensVersion); + result = result.replace(/\[wcssVersion]/g, nameExtractionData.wcssVersion); /** * Cleanup line breaks @@ -66,7 +70,7 @@ function formatTemplateFileContents(content, destination) { result = result.replace(/>(\r\n|\r|\n){2,}/g, '>\r\n'); // Remove empty lines directly after a closing html tag. result = result.replace(/>(\r\n|\r|\n)```/g, '>\r\n\r\n```'); // Ensure an empty line before code samples. result = result.replace(/>(\r\n|\r|\n){2,}```(\r\n|\r|\n)/g, '>\r\n```\r\n'); // Ensure no empty lines before close of code sample. - result = result.replace(/([^(\r\n|\r|\n)])(\r\n|\r|\n)+#/g, "$1\r\n\r\n#"); // Ensure empty line before header sections. + result = result.replace(/([^(\r\n|\r|\n)])(\r?\n|\r(?!\n))+#/g, "$1\r\n\r\n#"); // Ensure empty line before header sections. /** * Write the result to the destination file @@ -81,14 +85,14 @@ function formatApiTableContents(content, destination) { let result = content; result = result - .replace(/\r\n|\r|\n####\s`([a-zA-Z]*)`/g, `\r\n#### \`$1\`back to top`) + .replace(/\r\n|\r|\n####\s`([a-zA-Z]*)`/g, `\r\n#### \`$1\`back to top`) .replace(/\r\n|\r|\n\|\s`([a-zA-Z]*)`/g, '\r\n| [$1](#$1)') .replace(/\| \[\]\(#\)/g, ""); fs.writeFileSync(destination, result, { encoding: 'utf8'}); - fs.readFile('./demo/api.md', 'utf8', function(err, data) { - formatTemplateFileContents(data, './demo/api.md'); + fs.readFile('./demo/apiExamples.md', 'utf8', function(err, data) { + formatTemplateFileContents(data, './demo/apiExamples.md'); }); } @@ -119,17 +123,17 @@ function processReadme() { } /** - * Compiles `../docs/partials/index.md` -> `./demo/index.md` + * Compiles `./docTemplates/demo.md` -> `./demo/demo.md` */ function processDemo() { const callback = function(updatedContent, outputConfig) { - if (fs.existsSync('./demo/index.md')) { - fs.readFile('./demo/index.md', 'utf8', function(err, data) { - formatTemplateFileContents(data, './demo/index.md'); + if (fs.existsSync('./demo/demo.md')) { + fs.readFile('./demo/demo.md', 'utf8', function(err, data) { + formatTemplateFileContents(data, './demo/demo.md'); }); } else { - console.log('ERROR: ./demo/index.md file is missing'); + console.log('ERROR: ./demo/demo.md file is missing'); } }; @@ -138,23 +142,23 @@ function processDemo() { outputDir: './demo' }; - const markdownPath = path.join(__dirname, '../docs/partials/index.md'); + const markdownPath = path.join(__dirname, '../docs/partials/demo.md'); markdownMagic(markdownPath, configDemo, callback); } /** - * Compiles `../docs/partials/api.md` -> `./demo/api.md` + * Compiles `./docTemplates/apiExamples.md` -> `./demo/apiExamples.md` */ function processApiExamples() { const callback = function(updatedContent, outputConfig) { - if (fs.existsSync('./demo/api.md')) { - fs.readFile('./demo/api.md', 'utf8', function(err, data) { - formatApiTableContents(data, './demo/api.md'); + if (fs.existsSync('./demo/apiExamples.md')) { + fs.readFile('./demo/apiExamples.md', 'utf8', function(err, data) { + formatApiTableContents(data, './demo/apiExamples.md'); }); } else { - console.log('ERROR: ./demo/api.md file is missing'); + console.log('ERROR: ./demo/apiExamples.md file is missing'); } }; @@ -163,7 +167,7 @@ function processApiExamples() { outputDir: './demo' }; - const markdownPath = path.join(__dirname, '../docs/partials/api.md'); + const markdownPath = path.join(__dirname, '../docs/partials/apiExamples.md'); markdownMagic(markdownPath, config, callback); }