@ts-for-gir/generator-html-doc 4.0.0-beta.9 → 4.0.0-rc.1

package/README.md

@@ -16,5 +16,18 @@
   <img src="https://raw.githubusercontent.com/gjsify/ts-for-gir/main/.github/feeling.gif" />
 </p>
 
-# Generator base
-HTML Documentation generator for ts-for-gir.
+# HTML Documentation Generator
+
+## Status: Not Yet Implemented
+
+This package currently serves as a placeholder and basic framework for implementing an HTML documentation generator based on GIR types. It does not contain actual functionality yet.
+
+## Purpose
+
+The intended purpose of this package is to provide a way to generate HTML documentation from GObject introspection data, similar to how the `generator-typescript` package generates TypeScript definitions. When implemented, it would allow for generating human-readable API documentation websites.
+
+## Implementation
+
+This package implements the `Generator` interface from `@ts-for-gir/generator-base` but its methods currently throw "Not implemented" errors. It provides the basic structure needed for anyone who wants to implement a full HTML documentation generator for GObject introspection types.
+
+If you're interested in implementing this feature, contributions are welcome! Feel free to use this package as a starting point for building a complete HTML documentation generator.

package/package.json

@@ -1,29 +1,23 @@
 {
   "name": "@ts-for-gir/generator-html-doc",
-  "version": "4.0.0-beta.9",
+  "version": "4.0.0-rc.1",
   "description": "HTML Documentation generator for ts-for-gir",
-  "module": "lib/index.js",
-  "main": "lib/index.js",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
   "type": "module",
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "build": "yarn lint && yarn build:ts",
-    "build:ts": "tsc",
-    "clear": "yarn clear:build",
-    "clear:build": "rimraf ./lib",
-    "watch": "yarn build:ts --watch",
-    "lint": "eslint . --ext .ts,.tsx --fix"
+    "check": "tsc --noEmit"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gjsify/ts-for-gir.git"
   },
-  "author": "Pascal Garber <pascal@artandcode.studio>",
+  "author": "Pascal Garber <pascal@mailfreun.de>",
   "files": [
-    "lib",
-    "templates"
+    "src"
   ],
   "license": "Apache-2.0",
   "bugs": {
@@ -31,21 +25,25 @@
   },
   "homepage": "https://github.com/gjsify/ts-for-gir#readme",
   "keywords": [
-    "generator"
+    "generator",
+    "html",
+    "documentation",
+    "gir"
   ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "devDependencies": {
-    "@types/node": "^20.14.11",
-    "@typescript-eslint/eslint-plugin": "^7.16.1",
-    "@typescript-eslint/parser": "^7.16.1",
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.2.1",
-    "prettier": "^3.3.3",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.5.3"
+    "@ts-for-gir/tsconfig": "^4.0.0-rc.1",
+    "@types/node": "^24.12.2",
+    "rimraf": "^6.1.3",
+    "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@ts-for-gir/generator-base": "^4.0.0-beta.9",
-    "@ts-for-gir/lib": "^4.0.0-beta.9"
+    "@ts-for-gir/generator-base": "^4.0.0-rc.1",
+    "@ts-for-gir/generator-json": "^4.0.0-rc.1",
+    "@ts-for-gir/lib": "^4.0.0-rc.1",
+    "@ts-for-gir/typedoc-theme": "^4.0.0-rc.1",
+    "typedoc": "^0.28.18"
   }
 }

package/src/html-doc-generator.ts

@@ -0,0 +1,105 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import { type TypeDocAppResult, TypeDocPipeline } from "@ts-for-gir/generator-json";
+import { type GirModule, type NSRegistry, type OptionsGeneration, Reporter, ReporterService } from "@ts-for-gir/lib";
+import { load as loadGiDocgenTheme } from "@ts-for-gir/typedoc-theme";
+import type { Application } from "typedoc";
+
+/**
+ * Generator that produces HTML documentation from GIR modules using TypeDoc.
+ *
+ * Uses {@link TypeDocPipeline} for the shared .d.ts → TypeDoc conversion,
+ * then generates HTML documentation via TypeDoc's built-in renderer.
+ */
+export class HtmlDocGenerator {
+	readonly log: Reporter;
+	readonly config: OptionsGeneration;
+	readonly registry: NSRegistry;
+
+	private readonly pipeline: TypeDocPipeline;
+
+	constructor(config: OptionsGeneration, registry: NSRegistry) {
+		this.config = config;
+		this.registry = registry;
+		this.pipeline = new TypeDocPipeline(config, registry);
+		this.log = new Reporter(
+			this.config.verbose,
+			HtmlDocGenerator.name,
+			this.config.reporter,
+			this.config.reporterOutput,
+		);
+
+		if (this.config.reporter) {
+			ReporterService.getInstance().registerReporter(HtmlDocGenerator.name, this.log);
+		}
+	}
+
+	public async start(): Promise<void> {
+		this.log.info("Starting HTML documentation generation via TypeDoc...");
+		await this.pipeline.start();
+	}
+
+	public async generate(module: GirModule): Promise<void> {
+		await this.pipeline.generate(module);
+	}
+
+	public async finish(girModules: GirModule[]): Promise<void> {
+		await this.pipeline.finishTypescriptGeneration(girModules);
+
+		try {
+			const outdir = this.requireOutdir();
+			await mkdir(outdir, { recursive: true });
+
+			if (this.config.combined) {
+				const result = await this.pipeline.createCombinedTypeDocApp();
+				await this.generateDocsWithTheme(result, outdir);
+			} else {
+				for (const module of this.pipeline.modules) {
+					const result = await this.pipeline.createTypeDocApp(module);
+					await this.generateDocsWithTheme(result, join(outdir, module.packageName));
+				}
+			}
+
+			this.log.success(`HTML documentation generated for ${this.pipeline.modules.length} modules in ${outdir}`);
+		} finally {
+			await this.pipeline.cleanup();
+		}
+	}
+
+	/**
+	 * Generate combined HTML documentation from pre-generated TypeDoc JSON files.
+	 * This bypasses the normal .d.ts generation pipeline entirely, using TypeDoc's merge mode.
+	 */
+	public async generateFromJson(jsonDir: string): Promise<void> {
+		const outdir = this.requireOutdir();
+		await mkdir(outdir, { recursive: true });
+
+		this.log.info(`Generating HTML documentation from JSON files in ${jsonDir}...`);
+		const result = await this.pipeline.createMergedTypeDocApp(jsonDir);
+		await this.generateDocsWithTheme(result, outdir);
+		this.log.success(`Generated merged HTML docs from JSON in ${outdir}`);
+	}
+
+	/** Apply the configured theme and generate HTML docs into the given directory. */
+	private async generateDocsWithTheme({ app, project }: TypeDocAppResult, outdir: string): Promise<void> {
+		this.applyTheme(app);
+		await app.generateDocs(project, outdir);
+	}
+
+	private applyTheme(app: Application): void {
+		const themeName = this.config.theme || "gi-docgen";
+		if (themeName === "gi-docgen") {
+			loadGiDocgenTheme(app);
+		}
+		app.options.setValue("theme", themeName);
+	}
+
+	/** Returns outdir or throws if not configured. */
+	private requireOutdir(): string {
+		if (!this.config.outdir) {
+			throw new Error("HTML documentation requires --outdir to be specified");
+		}
+		return this.config.outdir;
+	}
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./html-doc-generator.ts";

package/lib/html-doc-generator.d.ts

@@ -1,14 +0,0 @@
-import { Logger } from '@ts-for-gir/lib';
-import { Generator } from '@ts-for-gir/generator-base';
-import type { OptionsGeneration, GirModule, NSRegistry } from '@ts-for-gir/lib';
-/**
- * A template that can be used to implement an HTML Documentation Generator
- */
-export declare class HtmlDocGenerator implements Generator {
-    protected readonly config: OptionsGeneration;
-    protected log: Logger;
-    constructor(config: OptionsGeneration);
-    start(_registry: NSRegistry): Promise<void>;
-    generate(_registry: NSRegistry, _module: GirModule): Promise<void>;
-    finish(_registry: NSRegistry, _girModules: GirModule[]): Promise<void>;
-}

package/lib/html-doc-generator.js

@@ -1,23 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-import { Logger, DANGER_HTML_DOC_GENERATOR_NOT_IMPLEMENTED } from '@ts-for-gir/lib';
-/**
- * A template that can be used to implement an HTML Documentation Generator
- */
-export class HtmlDocGenerator {
-    config;
-    log;
-    constructor(config) {
-        this.config = config;
-        this.log = new Logger(config.verbose, HtmlDocGenerator.name);
-    }
-    async start(_registry) {
-        return Promise.resolve(this.log.danger(DANGER_HTML_DOC_GENERATOR_NOT_IMPLEMENTED));
-    }
-    generate(_registry, _module) {
-        throw new Error('Method not implemented.');
-    }
-    finish(_registry, _girModules) {
-        throw new Error('Method not implemented.');
-    }
-}
-//# sourceMappingURL=html-doc-generator.js.map

package/lib/html-doc-generator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"html-doc-generator.js","sourceRoot":"","sources":["../src/html-doc-generator.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,OAAO,EAAE,MAAM,EAAE,yCAAyC,EAAE,MAAM,iBAAiB,CAAA;AAKnF;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAEM;IADrB,GAAG,CAAQ;IACrB,YAA+B,MAAyB;QAAzB,WAAM,GAAN,MAAM,CAAmB;QACpD,IAAI,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAA;IAChE,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,SAAqB;QAC7B,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,yCAAyC,CAAC,CAAC,CAAA;IACtF,CAAC;IAED,QAAQ,CAAC,SAAqB,EAAE,OAAkB;QAC9C,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAA;IAC9C,CAAC;IAED,MAAM,CAAC,SAAqB,EAAE,WAAwB;QAClD,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAA;IAC9C,CAAC;CACJ"}

package/lib/index.d.ts

@@ -1 +0,0 @@
-export * from './html-doc-generator.js';

package/lib/index.js

@@ -1,2 +0,0 @@
-export * from './html-doc-generator.js';
-//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAA"}