Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(docs): add ts types in the docs #16265 #16779

Open
wants to merge 5 commits into
base: dev
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 79 additions & 6 deletions docs/build/md/md-parse-utils.js
Original file line number Diff line number Diff line change
@@ -1,15 +1,43 @@
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import fs from 'node:fs'
import matter from 'gray-matter'
import toml from 'toml'

const rootFolder = fileURLToPath(new URL('../../../', import.meta.url))

const typesDir = path.resolve(rootFolder, 'node_modules/quasar/dist/types/api')
const typeFiles = fs.readdirSync(typesDir)

const extEndRE = /\.(js|vue)$/

function getComponentsImport (componentsList) {
return componentsList
.map((c) => {
const parts = c.split('/')
const file = extEndRE.test(c) === false ? `${c}.vue` : c

return `import ${parts[ parts.length - 1 ].replace(
extEndRE,
''
)} from '${file}'\n`
})
.join('')
}

function parseToc (toc) {
let wasHeader = true // Introduction is auto prepended
let headerIndex = 1 // Introduction is auto prepended
let subheaderIndex

const list = toc.map(entry => {
const list = toc.map((entry) => {
if (entry.sub === true) {
if (wasHeader === true) { subheaderIndex = 1 }
else { subheaderIndex++ }
if (wasHeader === true) {
subheaderIndex = 1
}
else {
subheaderIndex++
}

wasHeader = false
}
Expand All @@ -20,9 +48,10 @@ function parseToc (toc) {

return {
...entry,
title: entry.sub === true
? `${ headerIndex }.${ subheaderIndex }. ${ entry.title }`
: `${ headerIndex }. ${ entry.title }`
title:
entry.sub === true
? `${headerIndex}.${subheaderIndex}. ${entry.title}`
: `${headerIndex}. ${entry.title}`
}
})

Expand Down Expand Up @@ -67,3 +96,47 @@ export function parseFrontMatter (content) {
}
})
}

/** Add types if quasar/dist/types/api/ have it */
export function addTypeDeclarations (code, id) {
const fileName = path.basename(id).replace('.md', '')

let typeFile = typeFiles.find((typeFile) => {
return typeFile.includes(fileName)
})

// some special
if (fileName === 'color-palette') typeFile = 'color.d.ts'
if (fileName === 'touch-swipe') typeFile = 'touchswipe.d.ts'
if (fileName === 'field') typeFile = 'validation.d.ts'

if (typeFile) {
let typeCode = fs.readFileSync(path.join(typesDir, typeFile), 'utf-8')

// clean up types
typeCode = typeCode
.replace(/import\(.*?\)\./g, '')
.replace(/import[\s\S]+?from ?["'][\s\S]+?["'];/g, '')
.replace(/export {}/g, '')
.replace(/\/\/.*/g, '')

typeCode = `\`\`\` typescript\n${typeCode.trim()}\n\`\`\``

const typingSection =
typeCode.length > 1000
? `
## Type Declarations

::: details Show Type Declarations

${typeCode}

:::
`
: `\n## Type Declarations\n\n${typeCode}`

return code + typingSection
}

return code
}
4 changes: 3 additions & 1 deletion docs/build/md/md-parse.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import md from './md.js'
import { convertToRelated, flatMenu } from './flat-menu.js'
import { getVueComponent, parseFrontMatter } from './md-parse-utils.js'
import { addTypeDeclarations, getVueComponent, parseFrontMatter } from './md-parse-utils.js'

const docApiRE = /<DocApi /
const docInstallationRE = /<DocInstallation /
Expand All @@ -22,6 +22,8 @@ function splitRenderedContent (mdPageContent) {
}

export default function mdParse (code, id) {
code = addTypeDeclarations(code,id)

const { data: frontMatter, content } = parseFrontMatter(code)

frontMatter.id = id
Expand Down