index.ts

import childProcess from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
import { DocspecTransformer } from './transformation';
import type { DocspecObject } from './types';

export { groupSort } from './utils';

/**
 * Processes the Python documentation generated by `pydoc-markdown` and transforms it into a format
 * accepted by the TypeDoc JSON generator.
 */
export function processPythonDocs({
	pythonModulePath,
	moduleShortcutsPath,
	outPath,
	gitRevision,
}: {
	pythonModulePath: string;
	moduleShortcutsPath: string;
	outPath: string;
	gitRevision: string;
}) {
	const pydocMarkdownDumpPath = path.join(__dirname, './pydoc-markdown-dump.json');

	const out = childProcess.spawnSync('python', [
		path.join(__dirname,  '..', '..', '..', './python-scripts/docspec-gen/generate_ast.py'),
		'-i',
		pythonModulePath,
		pydocMarkdownDumpPath,
	]);

	if (out.error) {
		throw new Error(`Failed to spawn the generate_ast.py script: ${out.error.message}`);
	}

	if (out.status !== 0) {
		throw new Error(
			`The generate_ast.py script failed with exit code ${out.status}:\n${out.stderr.toString()}`,
		);
	}

	const moduleShortcuts = JSON.parse(fs.readFileSync(moduleShortcutsPath, 'utf8')) as Record<
		string,
		string
	>;

	const pydocMarkdownDump = JSON.parse(
		fs.readFileSync(pydocMarkdownDumpPath, 'utf8'),
	) as DocspecObject[];

	const docspecTransformer = new DocspecTransformer({
		gitRevision,
		moduleShortcuts,
	});

	const typedocApiReference = docspecTransformer.transform(pydocMarkdownDump);

	fs.writeFileSync(outPath, JSON.stringify(typedocApiReference, null, 4));
}