tldraw/apps/docs/scripts/functions/createApiMarkdown.ts
alex c4b9ea30f4
Document inherited members in reference (#3956)
Our reference docs don't currently include members inherited through the
`extends` keyword. These extended items are barely referenced at all -
you have to find them in the signature.

This diff adds a clearer note to the docs saying which type has been
extended, and if possible brings the extended items through onto the
current documentation page (with a note saying where they're from)


![image](https://github.com/tldraw/tldraw/assets/1489520/0349252d-e8bc-406b-bf47-636da424ebe0)


### Change Type

- [x] `docs` — Changes to the documentation, examples, or templates.
- [x] `improvement` — Improving existing features
2024-06-17 14:47:22 +00:00

90 lines
2.5 KiB
TypeScript

import { APIGroup, InputSection } from '@/types/content-types'
import { TldrawApiModel } from '@/utils/TldrawApiModel'
import { nicelog } from '@/utils/nicelog'
import fs from 'fs'
import path from 'path'
import { CONTENT_DIR, getSlug } from '../utils'
import { getApiMarkdown } from './getApiMarkdown'
export async function createApiMarkdown() {
const apiInputSection: InputSection = {
id: 'reference' as string,
title: 'API Reference',
description: "Reference for the tldraw package's APIs (generated).",
categories: [],
sidebar_behavior: 'reference',
hero: null,
}
const addedCategories = new Set<string>()
const INPUT_DIR = path.join(process.cwd(), 'api')
const OUTPUT_DIR = path.join(CONTENT_DIR, 'reference')
if (fs.existsSync(OUTPUT_DIR)) {
fs.rmSync(OUTPUT_DIR, { recursive: true })
}
fs.mkdirSync(OUTPUT_DIR)
const model = new TldrawApiModel()
const packageModels = []
// get all files in the INPUT_DIR
const files = fs.readdirSync(INPUT_DIR)
for (const file of files) {
// get the file path
const filePath = path.join(INPUT_DIR, file)
// parse the file
const apiModel = model.loadPackage(filePath)
// add the parsed file to the packageModels array
packageModels.push(apiModel)
}
await model.preprocessReactComponents()
for (const packageModel of packageModels) {
const categoryName = packageModel.name.replace(`@tldraw/`, '')
if (!addedCategories.has(categoryName)) {
apiInputSection.categories!.push({
id: categoryName,
title: packageModel.name,
description: '',
groups: Object.values(APIGroup).map((title) => ({
id: title,
path: null,
})),
hero: null,
})
addedCategories.add(categoryName)
}
const entrypoint = packageModel.entryPoints[0]
for (let j = 0; j < entrypoint.members.length; j++) {
const item = entrypoint.members[j]
const outputFileName = `${getSlug(item)}.mdx`
const result = await getApiMarkdown(model, categoryName, item, j)
nicelog(`${outputFileName}`)
fs.writeFileSync(path.join(OUTPUT_DIR, outputFileName), result.markdown)
}
}
// Add the API section to the sections.json file
const sectionsJsonPath = path.join(CONTENT_DIR, 'sections.json')
const sectionsJson = JSON.parse(fs.readFileSync(sectionsJsonPath, 'utf8')) as InputSection[]
sectionsJson.splice(
sectionsJson.findIndex((s) => s.id === 'reference'),
1
)
sectionsJson.push(apiInputSection)
fs.writeFileSync(sectionsJsonPath, JSON.stringify(sectionsJson, null, '\t') + '\n')
model.throwEncounteredErrors()
}