Skip to content

🎥 Make videos programmatically with React

7.2 KB
Raw Blame
import fs from 'node:fs';
import path from 'node:path';
import type {AnyRemotionOption} from '@remotion/renderer';
import {BrowserSafeApis} from '@remotion/renderer/client';
import {format} from 'oxfmt';
// eslint-disable-next-line no-restricted-imports -- Generate from source-only CLI metadata.
import {cliCommandHelp} from '../cli/src/print-help';
// eslint-disable-next-line no-restricted-imports -- Generate from source-only CLI metadata.
import {cloudrunCommandHelp} from '../cloudrun/src/cli/help';
// eslint-disable-next-line no-restricted-imports -- Generate from source-only CLI metadata.
import {lambdaCommandHelp} from '../lambda/src/cli/help';
import {optionDescriptionToMarkdown} from './option-description';
import {collectOptionReferences} from './option-references';

const generateOptionDocs = async () => {
	const check = process.argv.includes('--check');
	const options: AnyRemotionOption<unknown>[] = Object.values(
		BrowserSafeApis.options,
	).sort(
		(a, b) =>
			a.name.localeCompare(b.name, 'en') || a.id.localeCompare(b.id, 'en'),
	);
	const references = collectOptionReferences(options);
	const commands = [
		...cliCommandHelp.map((command) => ({...command, binary: 'remotion'})),
		...lambdaCommandHelp.map((command) => ({
			...command,
			binary: 'remotion lambda',
		})),
		...cloudrunCommandHelp.map((command) => ({
			...command,
			binary: 'remotion cloudrun',
		})),
	];
	const directory = path.join(__dirname, 'docs', 'options');
	const files = new Map<string, string>();
	const indexItems: string[] = [];
	const registrySource = fs.readFileSync(
		path.join(__dirname, '../renderer/src/options/index.tsx'),
		'utf8',
	);
	const sourceFiles = new Map(
		Array.from(
			registrySource.matchAll(/import \{(\w+)\} from '\.\/(.+)';/g),
			(match) => [match[1], match[2]],
		),
	);

	for (const option of options) {
		if (!/^[a-z0-9-]+$/.test(option.id) || files.has(`${option.id}.mdx`)) {
			throw new Error(`Invalid or duplicate option id: ${option.id}`);
		}

		const supportedCommands = commands.filter(
			(command) =>
				(!('listed' in command) || command.listed !== false) &&
				command.options.some((entry) => entry.optionIds.includes(option.id)),
		);
		const usages = (references.get(option.id) ?? []).filter(
			(reference) => !reference.cli,
		);
		const cliDescription = optionDescriptionToMarkdown(
			option.description('cli'),
		).trim();
		const apiDescription = optionDescriptionToMarkdown(
			option.description('ssr'),
		).trim();
		const registryKey = Object.entries(BrowserSafeApis.options).find(
			([, value]) => value.id === option.id,
		)?.[0];
		const importName = registryKey
			? (registrySource.match(new RegExp(`\\b${registryKey}: (\\w+),`))?.[1] ??
				registryKey)
			: null;
		const sourceFile = importName ? sourceFiles.get(importName) : null;
		if (!sourceFile) {
			throw new Error(`No source file found for option ${option.id}`);
		}

		const sections = [
			'---',
			`image: /generated/articles-docs-options-${option.id}.png`,
			'# Generated by packages/docs/generate-option-docs.ts. Do not edit directly.',
			'# Regenerate: cd packages/docs && bun run generate-option-docs',
			`title: ${JSON.stringify(option.name)}`,
			'crumb: Options',
			`custom_edit_url: https://github.com/remotion-dev/remotion/edit/main/packages/renderer/src/options/${sourceFile}.tsx`,
			'---',
			'',
			`# ${option.name.replaceAll('<', '&lt;').replaceAll('>', '&gt;')}<AvailableFrom v="${option.addedIn}" />`,
			'',
			apiDescription === cliDescription || supportedCommands.length === 0
				? apiDescription
				: `## JavaScript API\n\n${apiDescription}\n\n## Command line\n\n${cliDescription}`,
		];

		if (supportedCommands.length > 0) {
			const flagSyntax = [
				...new Set(
					supportedCommands.map(
						(command) =>
							command.options.find((entry) =>
								entry.optionIds.includes(option.id),
							)!.flag,
					),
				),
			];
			sections.push(
				'',
				'## CLI flag',
				'',
				'```text',
				...flagSyntax,
				'```',
				'',
				'The following CLI commands accept this option:',
				'',
				...supportedCommands.map((command) => {
					const url = command.documentation.replace(
						/^https:\/\/(www\.)?remotion\.dev/,
						'',
					);
					return `- [\`${command.binary} ${command.path.join(' ')}\`](${url})`;
				}),
			);
		}

		const apiReferences = [
			...new Map(
				usages
					.filter((usage) => !usage.config)
					.map((usage) => [usage.url, usage]),
			).values(),
		];
		if (apiReferences.length > 0) {
			sections.push(
				'',
				'## APIs that have this option',
				'',
				'The following APIs accept this option:',
				'',
				...apiReferences.map(
					(usage) =>
						`- [\`${usage.title}\`](${usage.url})${usage.deprecated ? ' (deprecated)' : ''}`,
				),
			);
		}

		const configReferences = usages.filter(
			(usage) => usage.config && !usage.deprecated,
		);
		if (configReferences.length > 0) {
			sections.push('', '## Config file');
			for (const usage of configReferences) {
				if (usage.configExample === null) {
					throw new Error(`No config example found for ${usage.url}`);
				}

				sections.push('', usage.configExample);
			}
		}

		sections.push('', '## See also', '', '- [All options](/docs/options)');

		files.set(`${option.id}.mdx`, sections.join('\n'));
		indexItems.push(
			`- [${option.name}](/docs/options/${option.id})${supportedCommands.length > 0 ? ` (\`--${option.cliFlag}\`)` : ''}`,
		);
	}

	files.set(
		'index.mdx',
		[
			'---',
			'image: /generated/articles-docs-options-index.png',
			'# Generated by packages/docs/generate-option-docs.ts. Do not edit directly.',
			'# Regenerate: cd packages/docs && bun run generate-option-docs',
			'title: Options',
			'slug: /options',
			'crumb: API',
			'custom_edit_url: https://github.com/remotion-dev/remotion/edit/main/packages/docs/generate-option-docs.ts',
			'---',
			'',
			'A list of options that Remotion supports.',
			'',
			'CLI flags override [configuration file defaults](/docs/config).',
			'',
			'Only the CLI reads the config file. In programmatic APIs, you need to pass all options explicitly.',
			'',
			...indexItems,
		].join('\n'),
	);

	fs.mkdirSync(directory, {recursive: true});
	const outdated: string[] = [];
	for (const [file, content] of files) {
		const filePath = path.join(directory, file);
		const formatted = await format(filePath, content, {
			useTabs: false,
			printWidth: 300,
			embeddedLanguageFormatting: 'off',
		});
		if (formatted.errors.length > 0) {
			throw new Error(
				`Could not format ${file}: ${JSON.stringify(formatted.errors)}`,
			);
		}

		if (
			fs.existsSync(filePath) &&
			fs.readFileSync(filePath, 'utf8') === formatted.code
		) {
			continue;
		}

		outdated.push(file);
		if (!check) {
			fs.writeFileSync(filePath, formatted.code);
		}
	}

	for (const file of fs.readdirSync(directory)) {
		if (file.endsWith('.mdx') && !files.has(file)) {
			outdated.push(file);
			if (!check) {
				fs.unlinkSync(path.join(directory, file));
			}
		}
	}

	if (check && outdated.length > 0) {
		throw new Error(
			`Option docs are outdated: ${outdated.join(', ')}. Run bun run generate-option-docs in packages/docs.`,
		);
	}

	console.log(
		`${check ? 'Checked' : 'Generated'} ${options.length} option pages and the options index.`,
	);
};

generateOptionDocs().catch((err) => {
	console.error(err);
	process.exitCode = 1;
});