Skip to content
Merged
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
16 changes: 16 additions & 0 deletions .containerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Exclude entire build context, then add back only doc-core pack inputs (see Containerfile COPY . .)
**

!package.json
!package-lock.json
!astro.config.mjs
!tsconfig.json
!wrangler.jsonc
!cli
!cli/**
!src
!src/**
!public
!public/**
!textContent
!textContent/**
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,5 @@ coverage/

.wrangler/

temp
temp
tests/container/output
3 changes: 3 additions & 0 deletions README.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -49,4 +49,7 @@ All commands are run from the root of the project, from a terminal:
| `npm run build:cli` | Create a JS build of the documentation core CLI |
| `npm run build:cli:watch` | Run the CLI builder in watch mode |
| `npm run build:props` | Create a json file of your TsDoc compatible in code documentation |
| `npm run test:api:integration` | Build local doc-core, resolve the latest PatternFly Org commit once, then run two builds against the reviewed API snapshot |
| `ORG_REF=<commit-SHA> npm run test:api:integration` | Run that audit against a specific PatternFly Org commit |
| `npm run test:api:integration-dev` | Run the paired audit and update the reviewed SHA snapshot |
| `patternfly-doc-core generate-package-props` | Create a package metadata artifact at `schema/props.json` containing its format version, package identity, and components |
120 changes: 120 additions & 0 deletions cli/__tests__/precomputeExamplesByPath.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'fs/promises'
import { join } from 'path'
import { tmpdir } from 'os'

import {
precomputeExamplesByPath,
writePrecomputedExamplesCache,
} from '../precomputeExamplesByPath.js'
import type { DocsConfig } from '../getConfig.js'

describe('precomputeExamplesByPath', () => {
let tempRoot = ''
let configDir = ''

beforeEach(async () => {
tempRoot = await mkdtemp(join(tmpdir(), 'pf-precompute-'))
configDir = join(tempRoot, 'site')
await mkdir(join(configDir, 'src', 'content', 'components', 'alert'), {
recursive: true,
})
})

afterEach(async () => {
await rm(tempRoot, { recursive: true, force: true })
})

it('reads the generated MDX for a normal Markdown content glob', async () => {
await writeFile(
join(configDir, 'src/content/components/alert/Alert.md'),
'---\nsection: components\nid: Alert\n---\n',
)
const mdxPath = join(configDir, 'src/content/components/alert/Alert.mdx')
await writeFile(
mdxPath,
`---
section: components
id: Alert
---
### Default
<LiveExample src={AlertBasic} />
`,
)

const config: DocsConfig = {
outputDir: 'dist',
propsGlobs: [],
content: [
{
name: 'content',
base: 'src/content',
pattern: '**/*.md',
version: 'v6',
},
],
}

const byPath = await precomputeExamplesByPath(config, configDir, configDir)

expect(byPath['src/content/components/alert/Alert.mdx']).toEqual([
{ exampleName: 'AlertBasic', title: 'Default' },
])
})

it('uses generated MDX for a brace glob', async () => {
const base = join(configDir, 'src/content/components/button')
await mkdir(base, { recursive: true })
await writeFile(
join(base, 'Button.md'),
`---
section: components
id: Button
---
### Should ignore
<LiveExample src={Ignored} />
`,
)
await writeFile(
join(base, 'Button.mdx'),
`---
section: components
id: Button
---
### From MDX
<LiveExample src={ButtonBasic} />
`,
)

const config: DocsConfig = {
outputDir: 'dist',
propsGlobs: [],
content: [
{
name: 'content',
base: 'src/content',
pattern: '**/*.{md,mdx}',
version: 'v6',
},
],
}

const byPath = await precomputeExamplesByPath(config, configDir, configDir)
const examples = byPath['src/content/components/button/Button.mdx'] ?? []
expect(examples.map((item) => item.exampleName)).toEqual(['ButtonBasic'])
})

it('writes precomputed cache', async () => {
const outDir = join(tempRoot, 'dist')
const sample = {
'src/content/components/alert/Alert.mdx': [
{ exampleName: 'AlertBasic', title: 'Default' },
],
}
await writePrecomputedExamplesCache(outDir, sample)
const raw = await readFile(
join(outDir, '.precomputed-examples.json'),
'utf8',
)
expect(JSON.parse(raw)).toEqual(sample)
})
})
43 changes: 16 additions & 27 deletions cli/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@
/* eslint-disable no-console */
import { Command } from 'commander'
import { build, dev, preview, sync } from 'astro'
import {
precomputeExamplesByPath,
writePrecomputedExamplesCache,
} from './precomputeExamplesByPath.js'
import { dirname, join, resolve } from 'path'
import {
createCollectionContent,
Expand All @@ -20,7 +24,6 @@ import { hasFile } from './hasFile.js'
import { convertToMDX } from './convertToMDX.js'
import { mkdir, copyFile } from 'fs/promises'
import { fileURLToPath } from 'url'
import { fileExists } from './fileExists.js'

const currentDir = process.cwd()
const config = await getConfig(`${currentDir}/pf-docs.config.mjs`)
Expand Down Expand Up @@ -120,30 +123,6 @@ async function transformMDContentToMDX(verbose = false) {
)
}

async function initializeApiIndex(program: Command) {
const { verbose } = program.opts()
const templateIndexPath = join(astroRoot, 'cli', 'templates', 'apiIndex.json')
const targetIndexPath = join(absoluteOutputDir, 'apiIndex.json')
const indexExists = await fileExists(targetIndexPath)

// early return if the file exists from a previous build
if (indexExists) {
if (verbose) {
console.log('apiIndex.json already exists, skipping initialization')
}
return
}

try {
await copyFile(templateIndexPath, targetIndexPath)
if (verbose) {
console.log('Initialized apiIndex.json')
}
} catch (e: any) {
console.error('Error copying apiIndex.json template:', e)
}
}

async function buildProject(program: Command): Promise<DocsConfig | undefined> {
const { verbose, apiOnly } = program.opts()

Expand All @@ -167,14 +146,24 @@ async function buildProject(program: Command): Promise<DocsConfig | undefined> {
await updateContent(program)
await transformMDContentToMDX(verbose)
await generateProps(program, true)
await initializeApiIndex(program)

process.env.PF_DOCS_ROOT = currentDir
process.env.PF_DOCS_REQUIRE_PRECOMPUTED_EXAMPLES = 'true'
await writePrecomputedExamplesCache(
absoluteOutputDir,
await precomputeExamplesByPath(config, currentDir, astroRoot),
)

const docsOutputDir = join(absoluteOutputDir, 'docs')

await build({
root: astroRoot,
outDir: docsOutputDir,
})
await copyFile(
join(docsOutputDir, 'apiIndex.json'),
join(absoluteOutputDir, 'apiIndex.json'),
)

return config
}
Expand Down Expand Up @@ -239,9 +228,9 @@ program.command('start').action(async () => {
if (apiOnly) {
process.env.PF_API_ONLY = 'true'
}
process.env.PF_DOCS_ROOT = currentDir
await updateContent(program)
await transformMDContentToMDX(verbose)
await initializeApiIndex(program)

// if a props file hasn't been generated yet, but the consumer has propsData, it will cause a runtime error so to
// prevent that we're just creating a props file regardless of what they say if one doesn't exist yet
Expand Down
81 changes: 81 additions & 0 deletions cli/precomputeExamplesByPath.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
import { mkdir, readFile, writeFile } from 'fs/promises'
import { join, relative, resolve } from 'path'
import { glob } from 'glob'
import type { DocsConfig } from './getConfig.js'
import { resolveContentEntryGlob } from './createCollectionContent.js'

const LIVE_EXAMPLE_REGEX = /<LiveExample[^>]*\ssrc=\{\s*(\w+)\s*\}[^>]*\/?>/g

export type ExampleEntry = { exampleName: string; title: string | null }

export type PrecomputedExamplesByPath = Record<string, ExampleEntry[]>

function extractExamplesWithTitles(body: string): ExampleEntry[] {
const examples: ExampleEntry[] = []
const seen = new Set<string>()
let match

while ((match = LIVE_EXAMPLE_REGEX.exec(body)) !== null) {
const exampleName = match[1]
if (exampleName && !seen.has(exampleName)) {
seen.add(exampleName)
const textBeforeExample = body.substring(0, match.index)
const h3Matches = [...textBeforeExample.matchAll(/^### (.+)$/gm)]
const title =
h3Matches.length > 0 ? h3Matches[h3Matches.length - 1][1].trim() : null
examples.push({ exampleName, title })
}
}

return examples
}

export async function precomputeExamplesByPath(
config: DocsConfig,
configDir: string,
astroRoot: string,
): Promise<PrecomputedExamplesByPath> {
const repoRootDir = config.repoRoot
? resolve(configDir, config.repoRoot)
: configDir
const byPath: PrecomputedExamplesByPath = {}

for (const contentObj of config.content ?? []) {
const globPath = resolveContentEntryGlob(
contentObj,
configDir,
repoRootDir,
false,
)
if (!globPath) {
continue
}

const mdxGlobPath = globPath.replace(/\.(?:md|\{md,mdx\})$/, '.mdx')
const files = (await glob(mdxGlobPath))
.filter((filePath) => filePath.endsWith('.mdx'))
.sort()

for (const filePath of files) {
const examples = extractExamplesWithTitles(
await readFile(filePath, 'utf8'),
)
if (examples.length > 0) {
byPath[relative(astroRoot, resolve(filePath)).replace(/\\/g, '/')] =
examples
}
}
}

return byPath
}

export async function writePrecomputedExamplesCache(
outputDir: string,
byPath: PrecomputedExamplesByPath,
): Promise<string> {
const cachePath = join(outputDir, '.precomputed-examples.json')
await mkdir(outputDir, { recursive: true })
await writeFile(cachePath, `${JSON.stringify(byPath, null, 2)}\n`)
return cachePath
}
6 changes: 0 additions & 6 deletions cli/templates/apiIndex.json

This file was deleted.

10 changes: 10 additions & 0 deletions jest.org-audit.config.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import type { Config } from 'jest'

const config: Config = {
preset: 'ts-jest',
testEnvironment: 'node',
roots: ['<rootDir>/tests/container'],
testMatch: ['<rootDir>/tests/container/**/*.test.ts'],
}

export default config
3 changes: 3 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@
"lint": "eslint . --cache --cache-strategy content",
"test": "jest",
"test:watch": "jest --watch",
"test:api:integration-dev": "ORG_REF=${ORG_REF:-latest} tests/container/run.sh && npm run test:api:integration-jest -- --testPathPattern=apiIntegration -u",
"test:api:integration": "ORG_REF=${ORG_REF:-latest} tests/container/run.sh && npm run test:api:integration-jest -- --testPathPattern=apiIntegration",
"test:api:integration-jest": "jest -c jest.org-audit.config.ts",
"semantic-release": "semantic-release",
"cf-typegen": "wrangler types",
"clean": "rm -rf dist .astro .wrangler"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ jest.mock('../../../../../../../../../utils', () => ({
}))

jest.mock('../../../../../../../../../utils/apiIndex/generate', () => ({
generateAndWriteApiIndex: jest.fn().mockResolvedValue({
generateApiIndex: jest.fn().mockResolvedValue({
versions: ['v6'],
sections: { v6: ['components'] },
pages: { 'v6::components': ['alert'] },
Expand Down
4 changes: 2 additions & 2 deletions src/content.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ function defineContent(contentObj: CollectionDefinition) {
'core-component-docs': 'html',
}

// Conversion is completed by the CLI before Astro loads collections.
const mdxPattern = pattern.replace(/\.md$/, '.mdx')
// Load only the generated form: source Markdown and generated MDX have the same IDs.
const mdxPattern = pattern.replace(/\.(?:md|\{md,mdx\})$/, '.mdx')

const hasExternalFrontmatter = !!(frontmatterDefaults || frontmatterMapping)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,16 @@ import type { APIRoute, GetStaticPaths } from 'astro'
import { access, readFile } from 'fs/promises'
import { isAbsolute, resolve } from 'path'
import { createJsonResponse, createTextResponse } from '../../../../../../../utils/apiHelpers'
import { generateAndWriteApiIndex } from '../../../../../../../utils/apiIndex/generate'
import { generateApiIndex } from '../../../../../../../utils/apiIndex/generate'
import { getEnrichedCollections } from '../../../../../../../utils/apiRoutes/collections'
import { findContentEntryFilePath } from '../../../../../../../utils/apiRoutes/contentMatching'
import { extractImports, extractExampleFilePath } from '../../../../../../../utils/apiRoutes/exampleParsing'

export const prerender = true

export const getStaticPaths: GetStaticPaths = async () => {
// Generate index file (will be cached if already generated)
const index = await generateAndWriteApiIndex()
// Generate the build-time index.
const index = await generateApiIndex()

const paths: {
params: {
Expand Down Expand Up @@ -153,4 +153,4 @@ export const GET: APIRoute = async ({ params }) => {
500
)
}
}
}
Loading
Loading