From 45ad0f331c079f2d131b687dd5cd44d8e7ce50c7 Mon Sep 17 00:00:00 2001 From: Jordan Jones Date: Mon, 19 Feb 2024 10:16:33 -0800 Subject: [PATCH] build(docs): update generate docs script --- README.md | 33 ++++++++++---------- scripts/generateDocs.mjs | 67 +++++++++++++++++++++++----------------- 2 files changed, 55 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index e97c1e7..1909cc6 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ The following sections are editable by making changes to the following files: | Component Example Code | HTML sample code of the components use | `./apiExamples/basic.html` | --> -# [Name] +# Header @@ -39,13 +39,14 @@ For the most up to date information on [UI development browser support](https:// ## Install - -[![Build Status](https://img.shields.io/github/actions/workflow/status/AlaskaAirlines/[namespace]-[name]/testPublish.yml?style=for-the-badge)](https://github.com/AlaskaAirlines/[namespace]-[name]/actions/workflows/testPublish.yml) -[![See it on NPM!](https://img.shields.io/npm/v/[npm]/[namespace]-[name]?style=for-the-badge&color=orange)](https://www.npmjs.com/package/[npm]/[namespace]-[name]) -[![License](https://img.shields.io/npm/l/[npm]/[namespace]-[name]?color=blue&style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0) - + +[![Build Status](https://img.shields.io/github/actions/workflow/status/AlaskaAirlines/auro-header/testPublish.yml?style=for-the-badge)](https://github.com/AlaskaAirlines/auro-header/actions/workflows/testPublish.yml) +[![See it on NPM!](https://img.shields.io/npm/v/@aurodesignsystem/auro-header?style=for-the-badge&color=orange)](https://www.npmjs.com/package/@aurodesignsystem/auro-header) +[![License](https://img.shields.io/npm/l/@aurodesignsystem/auro-header?color=blue&style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0) +![ESM supported](https://img.shields.io/badge/ESM-compatible-FFE900?style=for-the-badge) + ```shell -$ npm i [npm]/[namespace]-[name] +$ npm i @aurodesignsystem/auro-header ``` Installing as a direct, dev or peer dependency is up to the user installing the package. If you are unsure as to what type of dependency you should use, consider reading this [stack overflow](https://stackoverflow.com/questions/18875674/whats-the-difference-between-dependencies-devdependencies-and-peerdependencies) answer. @@ -71,13 +72,13 @@ Any update to the Auro Design Tokens will be immediately reflected with browsers ### Define dependency in project component -Defining the component dependency within each component that is using the `<[namespace]-[name]>` component. +Defining the component dependency within each component that is using the `` component. ```js -import "[npm]/[namespace]-[name]"; +import "@aurodesignsystem/auro-header"; ``` @@ -93,7 +94,7 @@ import "[npm]/[namespace]-[name]"; ## Install bundled assets from CDN -In cases where the project is not able to process JS assets, there are pre-processed assets available for use. See -- `[namespace]-[name]__bundled.js` for modern browsers. Legacy browsers such as IE11 are no longer supported. +In cases where the project is not able to process JS assets, there are pre-processed assets available for use. See -- `auro-header__bundled.js` for modern browsers. Legacy browsers such as IE11 are no longer supported. **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. @@ -104,14 +105,14 @@ In cases where the project is not able to process JS assets, there are pre-proce ```html - - - + + + ``` -## [namespace]-[name] use cases +## auro-header use cases @@ -123,7 +124,7 @@ The `` element should be used in situations where users may: ## API Code Examples -### Default [namespace]-[name] +### Default auro-header @@ -173,7 +174,7 @@ The custom element API file is generated in the build and committed back to the ### Testing -Automated tests are required for every Auro component. See `.\test\[namespace]-[name].test.js` for the tests for this component. Run `npm test` to run the tests and check code coverage. Tests must pass and meet a certain coverage threshold to commit. See [the testing documentation](https://auro.alaskaair.com/support/tests) for more details. +Automated tests are required for every Auro component. See `.\test\auro-header.test.js` for the tests for this component. Run `npm test` to run the tests and check code coverage. Tests must pass and meet a certain coverage threshold to commit. See [the testing documentation](https://auro.alaskaair.com/support/tests) for more details. diff --git a/scripts/generateDocs.mjs b/scripts/generateDocs.mjs index 7c0dc0f..5a21cb4 100644 --- a/scripts/generateDocs.mjs +++ b/scripts/generateDocs.mjs @@ -5,7 +5,7 @@ import https from 'https'; const __dirname = new URL('.', import.meta.url).pathname; -const readmeTemplateUrl = 'https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/README.md'; +const readmeTemplateUrl = 'https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/README_esm.md'; const dirDocTemplates = './docTemplates'; const readmeFilePath = dirDocTemplates + '/README.md'; @@ -14,31 +14,37 @@ 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 @aurodesignsystem, header, Header, auro and Auro accordingly + * Replace all instances of [npm], [name], [Name], [namespace] and [Namespace] accordingly */ function formatTemplateFileContents(content, destination) { @@ -48,11 +54,14 @@ function formatTemplateFileContents(content, destination) { /** * Replace placeholder strings */ - result = result.replace(/\@aurodesignsystem/g, nameExtractionData.npm); - result = result.replace(/\header(?!\()/g, nameExtractionData.name); - result = result.replace(/\Header(?!\()/g, nameExtractionData.nameCap); - result = result.replace(/\auro/g, nameExtractionData.namespace); - result = result.replace(/\Auro/g, nameExtractionData.namespaceCap); + result = result.replace(/\[npm]/g, nameExtractionData.npm); + 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