Skip to content

Commit

Permalink
build(docs): update generate docs script
Browse files Browse the repository at this point in the history
  • Loading branch information
@jordanjones243 @jason-capsule42
jordanjones243 authored and jason-capsule42 committed Feb 19, 2024
1 parent bc47d06 commit 45ad0f3
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 45 deletions.
33 changes: 17 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
<!-- The below content is automatically added from ./../docs/partials/description.md -->
Expand All @@ -39,13 +39,14 @@ For the most up to date information on [UI development browser support](https://

## Install

<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/componentInstall.md) -->
[![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)

<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/componentInstall_esm.md) -->
[![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.
Expand All @@ -71,13 +72,13 @@ Any update to the Auro Design Tokens will be immediately reflected with browsers
### Define dependency in project component

<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/componentImportDescription.md) -->
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 `<auro-header>` component.

<!-- AURO-GENERATED-CONTENT:END -->
<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/componentImport.md) -->

```js
import "[npm]/[namespace]-[name]";
import "@aurodesignsystem/auro-header";
```

<!-- AURO-GENERATED-CONTENT:END -->
Expand All @@ -93,7 +94,7 @@ import "[npm]/[namespace]-[name]";
## Install bundled assets from CDN

<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/bundleInstallDescription.md) -->
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.

Expand All @@ -104,14 +105,14 @@ In cases where the project is not able to process JS assets, there are pre-proce
<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/bundleUseModBrowsers.md) -->

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@[dtVersion]/dist/tokens/CSSCustomProperties.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@[wcssVersion]/dist/bundled/essentials.css" />
<script src="https://cdn.jsdelivr.net/npm/[npm]/[namespace]-[name]@[Version]/dist/[namespace]-[name]__bundled.js" type="module"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@4.3.1/dist/tokens/CSSCustomProperties.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@5.0.8/dist/bundled/essentials.css" />
<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/[email protected]/dist/auro-header__bundled.js" type="module"></script>
```

<!-- AURO-GENERATED-CONTENT:END -->

## [namespace]-[name] use cases
## auro-header use cases

<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/useCases.md) -->
<!-- The below content is automatically added from ./../docs/partials/useCases.md -->
Expand All @@ -123,7 +124,7 @@ The `<auro-header>` element should be used in situations where users may:

## API Code Examples

### Default [namespace]-[name]
### Default auro-header

<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.html) -->
<!-- The below code snippet is automatically added from ./../apiExamples/basic.html -->
Expand Down Expand Up @@ -173,7 +174,7 @@ The custom element API file is generated in the build and committed back to the
### Testing

<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/development/testing.md) -->
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.

<!-- AURO-GENERATED-CONTENT:END -->

Expand Down
67 changes: 38 additions & 29 deletions scripts/generateDocs.mjs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand All @@ -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) {
Expand All @@ -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
Expand Down

0 comments on commit 45ad0f3

Please sign in to comment.