Skip to content

Commit

Permalink
fix(docs): generate spec for multiple component
Browse files Browse the repository at this point in the history
  • Loading branch information
aesteves60 authored and dpellier committed Sep 28, 2023
1 parent cc77a5f commit 96cf6fd
Show file tree
Hide file tree
Showing 11 changed files with 78 additions and 44 deletions.
13 changes: 6 additions & 7 deletions packages/common/core/src/utils/typedoc/typedoc-json-to-md.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,8 @@ import type {

const tableSeparator = '|';

export function convertJsonToMarkdown(jsonItems: DeclarationReflection[], filter: RegExp): string {
export function convertJsonToMarkdown(jsonItems: DeclarationReflection[]): string {
const result: string[] = [];
const filteredItems = jsonItems.filter(({ name }) => name.match(filter));

const displaySection = (stringArray: string[], sectionString: string) => {
const res = stringArray;
Expand All @@ -21,9 +20,9 @@ export function convertJsonToMarkdown(jsonItems: DeclarationReflection[], filter
}
};

const interfaces = getInterfaces(filteredItems),
types = getTypes(filteredItems),
classes = getClass(filteredItems);
const interfaces = getInterfaces(jsonItems),
types = getTypes(jsonItems),
classes = getClass(jsonItems);

// Create Table
result.push(
Expand Down Expand Up @@ -115,7 +114,7 @@ function getClass(filteredJSON: DeclarationReflection[]): string[] {
parameterSection.push(`Name | Type | Description \n---|---|---`);
parameters?.map(({name: paramName, type: paramType, comment: paramComment }) => {
params.push(`\`${paramName}\`: ${printType(paramType)}`);
parameterSection.push(`**${paramName}** | ${printType(paramType)} | ${paramComment?.shortText || ''}`);
parameterSection.push(`**${paramName}** | ${printType(paramType)} | ${paramComment?.shortText || ' '} |`);
});
}
res.push(`> **${methodName}**(${(params || ['']).join(',')}) => ${printType(type)}\n`);
Expand Down Expand Up @@ -147,7 +146,7 @@ function printType(typeObject?: SomeType | unknown) {
case 'literal':
return `_${getTypeValue(someType)}_`;
case 'reference': {
if (someType.name === 'Promise') {
if (someType.name === 'Promise' || someType.name === 'EventEmitter') {
return `\`${someType.name}<${getTypeValue(someType.typeArguments?.[0] as IntrinsicType)}>\``;
}
return `\`${someType.name}\``;
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
* [**Interfaces**](#interfaces)
* [**Classes**](#classes)

## Interfaces

### OdsAccordionGroupMethod
|name | Type | Required | Default | Description|
|---|---|:---:|---|---|
|**`registerAccordion`** | _void_ | ✴️ | | |
|**`unRegisterAccordion`** | _void_ | ✴️ | | |

## Classes

### OsdsAccordionGroup
#### Methods
> **registerAccordion**(`accordion`: `OsdsAccordion`) => `Promise<void>`
Name | Type | Description
---|---|---
**accordion** | `OsdsAccordion` |
> **unRegisterAccordion**(`accordion`: `OsdsAccordion`) => `Promise<void>`
Name | Type | Description
---|---|---
**accordion** | `OsdsAccordion` |
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
import {Description} from '@storybook/addon-docs';
import Specs from './spec.md';
import SpecsAccordionGroupContents from './specifications-accordion-group-contents.mdx';


## Description
The accordion group component is an invisible component which is a container of several [Accordions](?path=/docs/ui-components-accordion-accordion-atom-specifications--page)

<Description>{Specs}</Description>

## Contents
<SpecsAccordionGroupContents />
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,7 @@
### OdsAccordionEvent
|name | Type | Required | Default | Description|
|---|---|:---:|---|---|
|**`odsAccordionToggle`** | `EventEmitter` | ✴️ | | Event triggered on accordion toggle|

### OdsAccordionGroupMethod
|name | Type | Required | Default | Description|
|---|---|:---:|---|---|
|**`registerAccordion`** | _void_ | ✴️ | | |
|**`unRegisterAccordion`** | _void_ | ✴️ | | |
|**`odsAccordionToggle`** | `EventEmitter<boolean>` | ✴️ | | Event triggered on accordion toggle|

## Types

Expand All @@ -33,17 +27,4 @@

## Classes

### OsdsAccordion

### OsdsAccordionGroup
#### Methods
> **registerAccordion**(`accordion`: `OsdsAccordion`) => `Promise<void>`
Name | Type | Description
---|---|---
**accordion** | `OsdsAccordion` |
> **unRegisterAccordion**(`accordion`: `OsdsAccordion`) => `Promise<void>`
Name | Type | Description
---|---|---
**accordion** | `OsdsAccordion` |
### OsdsAccordion
4 changes: 3 additions & 1 deletion packages/components/accordion/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,9 @@
"ignore:rm": "git clean -Xdf",
"generate": "stencil generate",
"doc:api": "typedoc",
"doc": "typedoc --json ./docs-api/typedoc.json --pretty && node ../../../scripts/generate-typedoc-md.js",
"doc": "yarn run doc:accordion && yarn run doc:accordion-group && node ../../../scripts/generate-typedoc-md.js --multiple",
"doc:accordion": "typedoc src/components/osds-accordion/public-api.ts --out ./docs-api/accordion --json ./docs-api/accordion/typedoc.json",
"doc:accordion-group": "typedoc src/components/osds-accordion-group/public-api.ts --out ./docs-api/accordion-group --json ./docs-api/accordion-group/typedoc.json",
"generate:licence": "npx generate-license-file --input package.json --output THIRD-PARTY-LICENCES --overwrite",
"test": "yarn run test:spec && yarn run test:e2e",
"test:spec": "stencil test --spec --config stencil.config.ts --coverage",
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { Meta } from '@storybook/addon-docs';
import SpecificationsAccordionGroup from '@ovhcloud/ods-components/accordion/documentation/specifications/specifications-accordion-group.mdx';
import SpecificationsAccordionGroup from '@ovhcloud/ods-components/accordion/documentation/specifications/accordion-group/specifications-accordion-group.mdx';

<Meta title="UI Components/Accordion Group [molecule]/Specifications" />

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { Meta } from '@storybook/addon-docs';
import SpecificationsAccordion from '@ovhcloud/ods-components/accordion/documentation/specifications/specifications-accordion.mdx';
import SpecificationsAccordion from '@ovhcloud/ods-components/accordion/documentation/specifications/accordion/specifications-accordion.mdx';

<Meta title="UI Components/Accordion [atom]/Specifications" />

Expand Down
41 changes: 28 additions & 13 deletions scripts/generate-typedoc-md.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,36 @@
const fs = require('fs');
const path = require('path');
// CARE this is the path where the script was exec
const typedocJson = require(path.resolve('docs-api/typedoc.json'));
const packageJson = require(path.resolve('package.json'));
const rootComponent = packageJson.name.replace('@ovhcloud/ods-component-', '');

const { convertJsonToMarkdown } = require('@ovhcloud/ods-common-core');
const isMultiple = process.argv[2]?.includes('multiple');

const component = packageJson.name.replace('@ovhcloud/ods-component-', '');
const regex = new RegExp(component, 'gmi');
const dir = path.resolve('../../components', component, 'documentation/specifications');
fs.mkdirSync(dir, { recursive: true });

if(typedocJson.children) {
fs.writeFileSync(path.resolve(dir, 'spec.md'), convertJsonToMarkdown(typedocJson.children, regex), (err) => {
if (err) {
console.error(`file write error.`);
throw err;
}
});
if (!isMultiple) {
const typedocJson = require(path.resolve('docs-api/typedoc.json'));
const dir = path.resolve('../../components', rootComponent, 'documentation/specifications');
return createSpecMd(typedocJson, dir);
}

/** See Radio or Accordion for example multiple */
const componentFolders = fs.readdirSync('./src/components', {});
componentFolders.forEach((osdsComponent) => {
const component = osdsComponent.replace('osds-', '');
const typedocJson = require(path.resolve(`docs-api/${component}/typedoc.json`));
const dir = path.resolve('../../components', rootComponent, 'documentation/specifications', component);
createSpecMd(typedocJson, dir);
});

function createSpecMd(typedocJson, dir) {
fs.mkdirSync(dir, { recursive: true });

if(typedocJson.children) {
fs.writeFileSync(path.resolve(dir, 'spec.md'), convertJsonToMarkdown(typedocJson.children), (err) => {
if (err) {
console.error(`file write error.`);
throw err;
}
});
}
}

0 comments on commit 96cf6fd

Please sign in to comment.