mirror of
https://github.com/penpot/penpot-plugins.git
synced 2025-01-02 04:40:11 -05:00
chore: change typedoc config
This commit is contained in:
Marina López
parent
9fa96e9e95
commit
570e9d7220
4 changed files with 2 additions and 472 deletions
401
.github/scripts/create-doc-md.js
vendored
401
.github/scripts/create-doc-md.js
vendored
|
|
@ -1,401 +0,0 @@
|
|||
import * as fs from 'fs';
|
||||
import typedocJson from '../../docs/api/api-doc.json' with { type: 'json' };
|
||||
|
||||
const singleTab = ' ';
|
||||
const tabsNumber = {
|
||||
0: '',
|
||||
1: singleTab,
|
||||
2: singleTab + singleTab,
|
||||
3: singleTab + singleTab + singleTab,
|
||||
};
|
||||
|
||||
function generateMarkdownFromTypedoc(data) {
|
||||
let markdown = `---
|
||||
title: 5.4. API
|
||||
---\n\n`;
|
||||
|
||||
// Page title
|
||||
markdown += `# ${data.name}\n\n`;
|
||||
|
||||
// Page sections
|
||||
if (data.groups) {
|
||||
data.groups.forEach((group) => {
|
||||
markdown += `## ${group.title}\n\n`;
|
||||
group.children.forEach((childId) => {
|
||||
const child = data.children.find((c) => c.id === childId);
|
||||
// kind 256 or kind 2097152
|
||||
if (child.variant === 'declaration') {
|
||||
markdown += generateMarkdownForItem(child);
|
||||
} else if (child.kind === 64) {
|
||||
// TODO
|
||||
throw Error('64 kind is unexpected');
|
||||
} else if (child.kind === 32) {
|
||||
// TODO
|
||||
throw Error('32 kind is unexpected');
|
||||
} else {
|
||||
throw Error('Unexpected data');
|
||||
}
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
return markdown;
|
||||
}
|
||||
|
||||
function generateMarkdownForItem(item) {
|
||||
let markdown = '';
|
||||
|
||||
// Add item title
|
||||
markdown += `### ${item.name}\n\n`;
|
||||
|
||||
if (item.comment && item.comment.summary) {
|
||||
markdown += getComments(item.comment.summary, 0);
|
||||
}
|
||||
|
||||
if (item?.children) {
|
||||
item.groups.forEach((group) => {
|
||||
markdown += `#### ${group.title}\n`;
|
||||
|
||||
// list of ids from the item children
|
||||
group.children.forEach((id) => {
|
||||
const itemGroup = getItemFromGroup(item.children, id);
|
||||
if (itemGroup.type?.type === 'union') {
|
||||
markdown += `* **${itemGroup.name}**\n\n`;
|
||||
if (itemGroup.type?.declaration?.children) {
|
||||
itemGroup.type.types.forEach((type) => {
|
||||
markdown += `${type.value}`;
|
||||
});
|
||||
} else if (itemGroup.type.types) {
|
||||
markdown += getMarkdownCodeBlock(getNameWithType(itemGroup), 2);
|
||||
}
|
||||
|
||||
if (itemGroup.comment && itemGroup.comment.summary) {
|
||||
markdown += getComments(itemGroup.comment.summary, 2);
|
||||
}
|
||||
} else if (
|
||||
itemGroup.type?.type === 'reference' ||
|
||||
itemGroup.type?.type === 'intrinsic' ||
|
||||
itemGroup.type?.type === 'literal' ||
|
||||
itemGroup.type?.type === 'array'
|
||||
) {
|
||||
markdown += `* **${itemGroup.name}**\n\n`;
|
||||
markdown += getMarkdownCodeBlock(getNameWithType(itemGroup), 2);
|
||||
|
||||
if (itemGroup.comment && itemGroup.comment.summary) {
|
||||
markdown +=
|
||||
getComments(itemGroup.comment.summary, 2);
|
||||
}
|
||||
|
||||
if (itemGroup.comment && itemGroup.comment.blockTags) {
|
||||
markdown += singleTab + singleTab + `**Example:**\n\n`;
|
||||
markdown += getBlockTag(itemGroup.comment.blockTags, 2);
|
||||
}
|
||||
} else if (itemGroup.type?.type === 'reflection') {
|
||||
if (itemGroup.type?.declaration?.children) {
|
||||
markdown += `* **${itemGroup.name}**\n\n`;
|
||||
|
||||
if (itemGroup.comment && itemGroup.comment.summary) {
|
||||
markdown += getComments(itemGroup.comment.summary, 2);
|
||||
}
|
||||
|
||||
if (itemGroup.comment && itemGroup.comment.blockTags) {
|
||||
markdown += singleTab + singleTab + `**Example:**\n\n`;
|
||||
markdown += getBlockTag(itemGroup.comment.blockTags, 2);
|
||||
}
|
||||
|
||||
itemGroup.type.declaration.groups.forEach((itemSubGroup) => {
|
||||
itemSubGroup.children.forEach((itemSubGroupChildrenId) => {
|
||||
const itemSubGroupChildren = getItemFromGroup(
|
||||
itemGroup.type.declaration.children,
|
||||
itemSubGroupChildrenId
|
||||
);
|
||||
markdown +=
|
||||
singleTab + `* **${itemSubGroupChildren.name}**\n\n`;
|
||||
|
||||
if (
|
||||
itemSubGroupChildren.type.declaration &&
|
||||
itemSubGroupChildren.type.declaration.signatures
|
||||
) {
|
||||
markdown += getMarkdownCodeBlock(
|
||||
getSignatureParams(
|
||||
itemSubGroupChildren.name,
|
||||
itemSubGroupChildren.type.declaration.signatures[0]
|
||||
),
|
||||
2
|
||||
);
|
||||
|
||||
if (
|
||||
itemSubGroupChildren.comment &&
|
||||
itemSubGroupChildren.comment.summary
|
||||
) {
|
||||
markdown +=
|
||||
getComments(itemSubGroupChildren.comment.summary, 2);
|
||||
}
|
||||
|
||||
if (itemSubGroupChildren.comment && itemSubGroupChildren.comment.blockTags) {
|
||||
markdown += singleTab + singleTab + `**Example:**\n\n`;
|
||||
markdown += getBlockTag(itemSubGroupChildren.comment.blockTags, 2);
|
||||
}
|
||||
|
||||
// Properties with a method as type
|
||||
markdown += singleTab + singleTab + `**Parameters:**\n\n`;
|
||||
if (itemSubGroupChildren.type.declaration.signatures[0] && itemSubGroupChildren.type.declaration.signatures[0].parameters && itemSubGroupChildren.type.declaration.signatures[0].parameters.some(param => param.comment)) {
|
||||
itemSubGroupChildren.type.declaration.signatures[0].parameters.forEach(param => {
|
||||
markdown += getParamsComments(param.name, param.comment.summary, 2);
|
||||
});
|
||||
}
|
||||
markdown += getMarkdownCodeBlock(
|
||||
getParameters(
|
||||
itemSubGroupChildren.type.declaration.signatures,
|
||||
0
|
||||
),
|
||||
2
|
||||
);
|
||||
markdown += singleTab + singleTab + '**Returns:** ';
|
||||
markdown +=
|
||||
'`' +
|
||||
getType(
|
||||
itemSubGroupChildren.type.declaration.signatures[0]
|
||||
) +
|
||||
'`';
|
||||
markdown += `\n\n`;
|
||||
}
|
||||
});
|
||||
});
|
||||
} else {
|
||||
markdown += `* **${itemGroup.name}**\n\n`;
|
||||
markdown += getMarkdownCodeBlock(
|
||||
getSignatureParams(
|
||||
itemGroup.name,
|
||||
itemGroup.type?.declaration?.signatures[0]
|
||||
),
|
||||
1
|
||||
);
|
||||
|
||||
if (itemGroup.comment && itemGroup.comment.summary) {
|
||||
markdown += getComments(itemGroup.comment.summary, 1);
|
||||
}
|
||||
|
||||
if (itemGroup.comment && itemGroup.comment.blockTags) {
|
||||
markdown += singleTab + singleTab + `**Example:**\n\n`;
|
||||
markdown += getBlockTag(itemGroup.comment.blockTags, 2);
|
||||
}
|
||||
|
||||
// Properties with a method as type
|
||||
if (itemGroup.type?.declaration?.signatures[0].parameters) {
|
||||
markdown += singleTab + `**Parameters:**\n\n`;
|
||||
if (itemGroup.type?.declaration?.signatures[0] && itemGroup.type?.declaration?.signatures[0].parameters && itemGroup.type?.declaration?.signatures[0].parameters.some(param => param.comment)) {
|
||||
itemGroup.type?.declaration?.signatures[0].parameters.forEach(param => {
|
||||
markdown += getParamsComments(param.name, param.comment.summary, 2);
|
||||
});
|
||||
}
|
||||
markdown += getMarkdownCodeBlock(
|
||||
getParameters(itemGroup.type?.declaration?.signatures, 0),
|
||||
1
|
||||
);
|
||||
}
|
||||
|
||||
if (itemGroup.type?.declaration.signatures[0].type) {
|
||||
markdown += singleTab + '**Returns:**\n';
|
||||
markdown +=
|
||||
'`' + getType(itemGroup.type?.declaration?.signatures[0]) + '`';
|
||||
markdown += `\n\n`;
|
||||
}
|
||||
}
|
||||
} else if (itemGroup.signatures) {
|
||||
markdown += `* **${itemGroup.name}**\n\n`;
|
||||
markdown += getMarkdownCodeBlock(
|
||||
getNameWithType(itemGroup.signatures[0]),
|
||||
1
|
||||
);
|
||||
|
||||
if (
|
||||
itemGroup.signatures[0].comment &&
|
||||
itemGroup.signatures[0].comment.summary
|
||||
) {
|
||||
markdown +=
|
||||
singleTab + getComments(itemGroup.signatures[0].comment.summary, 0);
|
||||
}
|
||||
|
||||
if (itemGroup.signatures[0].comment && itemGroup.signatures[0].comment.blockTags) {
|
||||
markdown += singleTab + singleTab + `**Example:**\n\n`;
|
||||
markdown += getBlockTag(itemGroup.signatures[0].comment.blockTags, 2);
|
||||
}
|
||||
|
||||
// Methods
|
||||
if (itemGroup.signatures[0].parameters) {
|
||||
markdown += singleTab + `**Parameters:**\n\n`;
|
||||
if (itemGroup.signatures[0] && itemGroup.signatures[0].parameters && itemGroup.signatures[0].parameters.some(param => param.comment)) {
|
||||
itemGroup.signatures[0].parameters.forEach(param => {
|
||||
if (param.comment) {
|
||||
markdown += getParamsComments(param.name, param.comment.summary, 2);
|
||||
}
|
||||
});
|
||||
}
|
||||
markdown += getMarkdownCodeBlock(
|
||||
getParameters(itemGroup.signatures, 0),
|
||||
1
|
||||
);
|
||||
}
|
||||
|
||||
const isMethod =
|
||||
itemGroup.signatures[0].kind === 4096 ||
|
||||
itemGroup.signatures[0].kind === 2048;
|
||||
if (isMethod) {
|
||||
markdown += singleTab + '**Returns:**\n';
|
||||
markdown += '`' + getType(itemGroup.signatures[0]) + '`';
|
||||
markdown += `\n\n`;
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
} else {
|
||||
markdown += getMarkdownCodeBlock(getNameWithType(item), 0);
|
||||
}
|
||||
|
||||
// add source if exists
|
||||
if (item.sources && item.sources.length > 0) {
|
||||
markdown += `#### Source: [${item.sources[0].fileName}:${item.sources[0].line}](${item.sources[0].url})\n\n`;
|
||||
}
|
||||
|
||||
return markdown;
|
||||
}
|
||||
|
||||
function getItemFromGroup(itemList, id) {
|
||||
return itemList.find((item) => item.id === id);
|
||||
}
|
||||
|
||||
function getNameWithType(data) {
|
||||
const isMethod = data.kind === 4096 || data.kind === 2048;
|
||||
let parentheses = '';
|
||||
if (isMethod) {
|
||||
parentheses = '()';
|
||||
if (data.parameters) {
|
||||
const params = data.parameters.map((it) => it.name);
|
||||
parentheses = `(${params})`;
|
||||
}
|
||||
}
|
||||
const optional = data.flags?.isOptional ? '?' : '';
|
||||
const type = getType(data);
|
||||
return `${data.name}${parentheses}${optional}: ${type}`;
|
||||
}
|
||||
|
||||
function getType(data) {
|
||||
let markdown = '';
|
||||
|
||||
if (data.type?.type === 'union' && data.type?.types) {
|
||||
const types = data.type.types
|
||||
.map((it) => {
|
||||
return it.value === null ? 'null' : it.value || it.name;
|
||||
})
|
||||
.join(' | ');
|
||||
markdown += `${types}`;
|
||||
} else {
|
||||
const options = {
|
||||
array: `${data.type?.elementType?.name}[]`,
|
||||
reference: `${
|
||||
data.type?.typeArguments
|
||||
? `${data.type.name}<${data.type.typeArguments[0].name}>`
|
||||
: data.type?.name
|
||||
}`,
|
||||
literal: `${
|
||||
data.type?.value === null ? 'null' : `"${data.type?.value}"`
|
||||
}`,
|
||||
intrinsic: `${data.type?.name}`,
|
||||
};
|
||||
markdown += `${options[data.type?.type]}`;
|
||||
}
|
||||
return markdown;
|
||||
}
|
||||
|
||||
function getParameters(signatures, tabs) {
|
||||
let paramsParts = '';
|
||||
signatures.forEach((signature) => {
|
||||
if (signature.parameters) {
|
||||
signature.parameters.forEach((param) => {
|
||||
if (param.type.type === 'reflection') {
|
||||
let part = '';
|
||||
if (param.type.declaration?.children) {
|
||||
part = tabsNumber[tabs] + `${param.name}: {\n`;
|
||||
param.type.declaration.children.forEach((it) => {
|
||||
part +=
|
||||
tabsNumber[tabs] + singleTab + `${it.name}: ${it.type.name}\n`;
|
||||
});
|
||||
part += tabsNumber[tabs] + '}';
|
||||
} else if (param.type.declaration?.signatures) {
|
||||
part +=
|
||||
tabsNumber[tabs] +
|
||||
getSignatureParams(
|
||||
param.name,
|
||||
param.type.declaration.signatures[0]
|
||||
) +
|
||||
'\n';
|
||||
} else if (param.type.type === 'array') {
|
||||
part += tabsNumber[tabs] + getNameWithType(param) + '\n';
|
||||
}
|
||||
paramsParts += part;
|
||||
} else {
|
||||
paramsParts += tabsNumber[tabs] + getNameWithType(param) + '\n';
|
||||
}
|
||||
});
|
||||
}
|
||||
});
|
||||
return paramsParts;
|
||||
}
|
||||
|
||||
function getBlockTag(commentBlockTag, tabs) {
|
||||
const block = commentBlockTag.map((block) => {
|
||||
return block.content.map(content => content.text).join(' \n');
|
||||
}).join(' \n\n');
|
||||
const formatContent = block.split('\n')
|
||||
.map((item) => tabsNumber[tabs] + item)
|
||||
.join('\n');
|
||||
return `${formatContent}\n\n`;
|
||||
}
|
||||
|
||||
function getComments(comentSummary, tabs) {
|
||||
const comment = comentSummary.map((summary) => summary.text).join(' ');
|
||||
return `${tabsNumber[tabs]}${comment}\n\n`;
|
||||
}
|
||||
|
||||
function getParamsComments(paramName, comentSummary, tabs) {
|
||||
const comment = comentSummary.map((summary) => summary.text).join(' ');
|
||||
return `${tabsNumber[tabs]}\`${paramName}\` ${comment}\n\n`;
|
||||
}
|
||||
|
||||
function getSignatureParams(paramName, signature) {
|
||||
const params = signature.parameters?.map((it) => it.name).join(', ') || '';
|
||||
if (signature.typeParameter) {
|
||||
const typeParameter = signature.typeParameter[0];
|
||||
if (typeParameter.type) {
|
||||
return `${paramName}: <${typeParameter.name} extends ${typeParameter.type?.operator} ${typeParameter.type?.target?.name}>(${params}) => ${signature.type.name}`;
|
||||
} else {
|
||||
return `${paramName}: <${typeParameter.name}>(${params}) => ${signature.type.name}`;
|
||||
}
|
||||
} else {
|
||||
return `${paramName}: (${params}) => ${signature.type.name}`;
|
||||
}
|
||||
}
|
||||
|
||||
function getMarkdownCodeBlock(content, tabs) {
|
||||
const formatContent = content
|
||||
.split('\n')
|
||||
.map((item) => tabsNumber[tabs] + item)
|
||||
.join('\n');
|
||||
|
||||
return (
|
||||
tabsNumber[tabs] +
|
||||
'```javascript\n' +
|
||||
formatContent +
|
||||
'\n' +
|
||||
tabsNumber[tabs] +
|
||||
'```\n'
|
||||
);
|
||||
}
|
||||
|
||||
const markdown = generateMarkdownFromTypedoc(typedocJson);
|
||||
|
||||
// write markdown in a file
|
||||
fs.writeFileSync('api.md', markdown);
|
||||
|
||||
console.log('document created successfully');
|
||||
68
.github/workflows/api-doc.yml
vendored
68
.github/workflows/api-doc.yml
vendored
|
|
@ -1,68 +0,0 @@
|
|||
name: Sync API doc to penpot-docs repository
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- libs/plugin-types/index.d.ts
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout penpot-plugins repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
path: penpot-plugins
|
||||
|
||||
- name: Checkout penpot-docs repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
path: penpot-docs
|
||||
repository: penpot/penpot-docs
|
||||
token: ${{ secrets.PENPOT_BOT_PAT }}
|
||||
ref: plugins
|
||||
|
||||
- name: Create new branch in penpot-docs
|
||||
working-directory: penpot-docs
|
||||
run: |
|
||||
git checkout -b update-api-docs-${{ github.sha }}
|
||||
|
||||
- name: Setup node
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version-file: penpot-plugins/.nvmrc
|
||||
cache: npm
|
||||
cache-dependency-path: penpot-plugins/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
working-directory: penpot-plugins
|
||||
run: |
|
||||
npm ci
|
||||
|
||||
- name: Create documentation with typedoc
|
||||
working-directory: penpot-plugins
|
||||
run: |
|
||||
npm run create:api-docs
|
||||
|
||||
- name: Create markdown documentation
|
||||
working-directory: penpot-plugins/.github/scripts
|
||||
run: |
|
||||
node create-doc-md.js
|
||||
|
||||
- name: Copy docs from penpot-plugins to penpot-docs
|
||||
run: |
|
||||
cp -r penpot-plugins/.github/scripts/api.md penpot-docs/technical-guide/plugins
|
||||
|
||||
- name: Commit, push and pull request
|
||||
working-directory: penpot-docs
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.PENPOT_BOT_PAT }}
|
||||
run: |
|
||||
git config --global user.name 'penpot-bot'
|
||||
git config --global user.email 'automations+github@penpot.app'
|
||||
git add .
|
||||
git commit -m ":books: Update api docs"
|
||||
git push --set-upstream origin update-api-docs-${{ github.sha }}
|
||||
gh pr create --base plugins --title "Update api plugins docs" --body "Update api plugins docs"
|
||||
|
|
@ -23,7 +23,7 @@
|
|||
"test": "nx run-many -t test --parallel -p plugins-runtime lorem-ipsum-plugin",
|
||||
"registry": "nx local-registry",
|
||||
"prepare": "husky",
|
||||
"create:api-docs": "npx typedoc --tsconfig libs/plugins-runtime/tsconfig.lib.json --options typedoc.json",
|
||||
"create:api-docs": "npx typedoc --tsconfig libs/plugins-runtime/tsconfig.lib.json",
|
||||
"release": "npx tsx ./tools/scripts/publish.ts"
|
||||
},
|
||||
"private": true,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
{
|
||||
"name": "Penpot plugins API",
|
||||
"out": "docs/api",
|
||||
"json": "docs/api/api-doc.json",
|
||||
"out": "dist/apps/api-doc",
|
||||
"entryPoints": ["libs/plugin-types/index.d.ts"],
|
||||
"sort": "source-order",
|
||||
"theme": "default"
|
||||
|
|
|
|||
Loading…
Reference in a new issue