Skip to content

Commit

Permalink
docs-util: support @tags comments (#10627)
Browse files Browse the repository at this point in the history
* support tags in tsdocs + add them in frontmatter

* fixes
  • Loading branch information
shahednasser authored Dec 17, 2024
1 parent 6367bcc commit 2a73d0a
Show file tree
Hide file tree
Showing 6 changed files with 64 additions and 18 deletions.
4 changes: 4 additions & 0 deletions www/utils/packages/typedoc-config/tsdoc.json
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,10 @@
{
"tagName": "@version",
"syntaxKind": "block"
},
{
"tagName": "@tags",
"syntaxKind": "block"
}
]
}
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ const EXCLUDED_TAGS = [
"@category",
"@typeParamDefinition",
"@version",
"@tags",
]

export default function () {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ import { MarkdownTheme } from "../../theme"
import { stringify } from "yaml"
import { replaceTemplateVariables } from "../../utils/reflection-template-strings"
import { Reflection } from "typedoc"
import { FrontmatterData } from "types"
import { getTagComments, getTagsAsArray } from "utils"

export default function (theme: MarkdownTheme) {
Handlebars.registerHelper("frontmatter", function (this: Reflection) {
Expand All @@ -13,34 +15,39 @@ export default function (theme: MarkdownTheme) {
}

// format frontmatter data in case it has any template variables
const resolvedFrontmatter = resolveFrontmatterVariables(
frontmatterData,
this
)

return `---\n${stringify(
resolveFrontmatterVariables(frontmatterData, this)
).trim()}\n---\n\n`
// check if reflection has an `@tags` tag
const tagsComment = getTagComments(this)
if (tagsComment?.length && !("tags" in resolvedFrontmatter)) {
resolvedFrontmatter["tags"] = []
}
tagsComment?.forEach((tag) => {
const tagContent = getTagsAsArray(tag)
resolvedFrontmatter["tags"]?.push(...tagContent)
})

return `---\n${stringify(resolvedFrontmatter).trim()}\n---\n\n`
})
}

function resolveFrontmatterVariables(
frontmatterData: Record<string, unknown>,
frontmatterData: FrontmatterData,
reflection: Reflection
): Record<string, unknown> {
const tempFrontmatterData = Object.assign({}, frontmatterData)
): FrontmatterData {
const tempFrontmatterData: FrontmatterData = JSON.parse(
JSON.stringify(frontmatterData)
)
Object.keys(tempFrontmatterData).forEach((key) => {
const value = tempFrontmatterData[key]
if (!value) {
if (!value || typeof value !== "string") {
return
}

switch (typeof value) {
case "object":
tempFrontmatterData[key] = resolveFrontmatterVariables(
value as Record<string, unknown>,
reflection
)
break
case "string":
tempFrontmatterData[key] = replaceTemplateVariables(reflection, value)
}
tempFrontmatterData[key] = replaceTemplateVariables(reflection, value)
})

return tempFrontmatterData
Expand Down
10 changes: 9 additions & 1 deletion www/utils/packages/types/lib/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,14 @@ export type FormattingOptionsType = {
[k: string]: FormattingOptionType
}

export type FrontmatterData = {
slug?: string
sidebar_label?: string
displayed_sidebar?: string
tags?: string[]
[k: string]: unknown
}

export type FormattingOptionType = {
sections?: Sections
reflectionGroups?: {
Expand All @@ -74,7 +82,7 @@ export type FormattingOptionType = {
showCommentsAsHeader?: boolean
showCommentsAsDetails?: boolean
parameterStyle?: ParameterStyle
frontmatterData?: Record<string, unknown>
frontmatterData?: FrontmatterData
parameterComponent?: string
parameterComponentExtraProps?: Record<string, unknown>
mdxImports?: string[]
Expand Down
1 change: 1 addition & 0 deletions www/utils/packages/utils/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@ export * from "./hooks-util"
export * from "./step-utils"
export * from "./str-formatting"
export * from "./str-utils"
export * from "./tag-utils"
export * from "./workflow-utils"
25 changes: 25 additions & 0 deletions www/utils/packages/utils/src/tag-utils.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { CommentTag, DeclarationReflection, Reflection } from "typedoc"

export const getTagsAsArray = (tag: CommentTag): string[] => {
return tag.content
.map((content) => content.text)
.join("")
.split(",")
.map((value) => value.trim())
}

export const getTagComments = (reflection: Reflection): CommentTag[] => {
const tagComments: CommentTag[] = []

reflection.comment?.blockTags
.filter((tag) => tag.tag === `@tags`)
.forEach((tag) => tagComments.push(tag))

if (reflection instanceof DeclarationReflection) {
reflection.signatures?.forEach((signature) =>
tagComments.push(...getTagComments(signature))
)
}

return tagComments
}

0 comments on commit 2a73d0a

Please sign in to comment.