Update hyperlink terminology and add documentation generation (#89)

* config-libraries.go: Add documentation header

* emitzig.go: Update hyperlink terminology

* build.zig: Add documentation step

* docs.yml: Add documentation generation workflow

* README: Update badges and add demo

* threading: Update hyperlink terminology

* Update wrappers

Author: rcalixte

.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+---
+name: Documentation
+
+on:
+  push:
+    branches: ["master"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Setup Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+      - run: zig build docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: "zig-out/docs"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -5,7 +5,9 @@
 
 ![MIT License](https://img.shields.io/badge/License-MIT-green)
 [![Go Report Card](https://goreportcard.com/badge/github.com/rcalixte/libqt6zig)](https://goreportcard.com/report/github.com/rcalixte/libqt6zig)
-[![Static Badge](https://img.shields.io/badge/v0.15%20(stable)-f7a41d?logo=zig&logoColor=f7a41d&label=Zig)](https://ziglang.org/download/)
+[![Static Badge](https://img.shields.io/badge/v0.15%20(stable)-fdc009?logo=zig&logoColor=f7a41d&label=Zig)](https://ziglang.org/download/)
+
+[![Documentation](https://github.com/rcalixte/libqt6zig/actions/workflows/docs.yml/badge.svg?branch=master)](https://github.com/rcalixte/libqt6zig/actions/workflows/docs.yml)
 </div>
 
 ---
@@ -18,7 +20,7 @@ For previous libqt6zig versions supporting Qt 6.4+, there are branches correspon
 
 This library is designed to be used as a dependency in a larger application and not as a standalone library. The versioning scheme used by this library is based on the Qt version used as a base to generate the bindings with an additional nod to the library revision number. Any breaking changes to the library will be reflected in the changelog.
 
-These bindings are based on the [MIQT bindings for Go](https://github.com/mappu/miqt) that were released in August 2024. This library features support for Qt Core, GUI, Widgets, and Network as well as [additional Qt modules](https://doc.qt.io/qt-6/qt-additional-modules.html) such as Multimedia, Print Support, Spatial Audio, SQL, SVG, WebChannel, WebEngine, and more. In addition to Qt modules, this library also features support for third-party libraries such as [QCustomPlot](https://www.qcustomplot.com), [QScintilla](https://riverbankcomputing.com/software/qscintilla), various [KDE Frameworks](https://develop.kde.org/products/frameworks/), and others. This library has support for slots/signals, subclassing, custom widgets, async via Qt, etc. In addition, there is library tooling that provides native support for Qt Creator/Designer forms and the Qt Resource System. With improper handling, it is fairly easy to encounter segmentation faults or errors. Q3 of the [FAQ](#faq) is a decent entry point for newcomers in addition to the [examples](https://github.com/rcalixte/libqt6zig-examples). Please try out the library and start a [discussion](https://github.com/rcalixte/libqt6zig/discussions) if you have any questions or issues directly relevant to this library.
+These bindings are based on the [MIQT bindings for Go](https://github.com/mappu/miqt) that were released in August 2024. This library features support for Qt Core, GUI, Widgets, and Network as well as [additional Qt modules](https://doc.qt.io/qt-6/qt-additional-modules.html) such as Multimedia, Print Support, Spatial Audio, SQL, SVG, WebChannel, WebEngine, and more. In addition to Qt modules, this library also features support for third-party libraries such as [QCustomPlot](https://www.qcustomplot.com), [QScintilla](https://riverbankcomputing.com/software/qscintilla), various [KDE Frameworks](https://develop.kde.org/products/frameworks/), and others. This library has support for slots/signals, subclassing, custom widgets, async via Qt, etc. In addition, there is library tooling that provides native support for Qt Creator/Designer forms and the Qt Resource System. With improper handling, it is fairly easy to encounter segmentation faults or errors. Q3 of the [FAQ](#faq) is a decent entry point for newcomers in addition to the [examples](https://github.com/rcalixte/libqt6zig-examples) and the [demo application](https://github.com/rcalixte/libqt6zig-demo). Please try out the library and start a [discussion](https://github.com/rcalixte/libqt6zig/discussions) if you have any questions or issues directly relevant to this library.
 
 ---
 

build.zig

@@ -192,6 +192,25 @@ pub fn build(b: *std.Build) !void {
     libqt6zig.addImport("qtzig", qtzig_types);
 
     try b.modules.put("libqt6zig", libqt6zig);
+
+    // Documentation build step
+    const docs_step = b.step("docs", "Emit libqt6zig documentation");
+    const libqt6zig_docs = b.addLibrary(.{
+        .name = "libqt6",
+        .root_module = b.createModule(.{
+            .target = target,
+            .root_source_file = b.path("include/libqt6.zig"),
+        }),
+    });
+
+    const docs_install = b.addInstallDirectory(.{
+        .source_dir = libqt6zig_docs.getEmittedDocs(),
+        .install_dir = .prefix,
+        .install_subdir = "docs",
+    });
+
+    docs_step.dependOn(&docs_install.step);
+    b.default_step.dependOn(docs_step);
 }
 
 const is_bsd_host = switch (host_os) {

cmd/genbindings/config-libraries.go

@@ -811,8 +811,38 @@ func ProcessLibraries(clangBin, outDir, extraLibsDir string) {
 		zigIncList = append(zigIncList, v)
 	}
 	sort.Strings(zigIncList)
-	zigDefs := "// THIS FILE IS AUTOMATICALLY GENERATED\n\npub const C = @import(\"qtzig\");\n\n"
-	zigDefs = zigDefs + strings.Join(zigIncList, "\n")
+	zigDocs := `//! # Qt 6 for Zig
+	//!
+	//! ## Introduction
+	//!
+	//! This library provides Qt 6 bindings and wrappers for Zig. This online
+	//! documentation is meant to simplify browsing the user-facing API for
+	//! Zig, augmenting the official Qt documentation as well as auxiliary
+	//! libraries that provide online documentation. The goal of this library
+	//! is to facilitate single-language, cross-platform native desktop
+	//! application development.
+	//!
+	//! This online documentation also includes third-party libraries in the Qt
+	//! ecosystem such as [QCustomPlot](https://www.qcustomplot.com), [QScintilla](https://riverbankcomputing.com/software/qscintilla),
+	//! various [KDE Frameworks](https://develop.kde.org/products/frameworks/), and others.
+	//!
+	//! For the [library tooling](https://github.com/rcalixte/libqt6zig?tab=readme-ov-file#tools), the documentation for each tool
+	//! is available next to the tool's source code.
+	//!
+	//! ## Getting Started
+	//!
+	//! The main library documentation is outlined in the
+	//! [table of contents](https://github.com/rcalixte/libqt6zig?tab=readme-ov-file#table-of-contents).
+	//!
+	//! Full examples are available in the [examples](https://github.com/rcalixte/libqt6zig-examples) repository.
+	//!
+	//! There is also a [demo application](https://github.com/rcalixte/libqt6zig-demo) that demonstrates the use of the library
+	//! with a simpler build system than the examples, while also demonstrating a
+	//! more realistic use of the library for a single application. The demo also
+	//! includes exercises designed to help developers onboard to the library.
+`
+	zigDefs := "\n// THIS FILE IS AUTOMATICALLY GENERATED\n\npub const C = @import(\"qtzig\");\n\n"
+	zigDefs = zigDocs + zigDefs + strings.Join(zigIncList, "\n")
 	zigQtPath := filepath.Join(outDir, "src", "libqt6.zig")
 	err = os.WriteFile(zigQtPath, []byte(zigDefs), 0644)
 	if err != nil {

cmd/genbindings/emitzig.go

@@ -1692,7 +1692,7 @@ const qtc = @import("qt6c");%%_IMPORTLIBS_%% %%_STRUCTDEFS_%%
 			if subjectURL != "" {
 				maybeCharts := ifv(strings.Contains(src.Filename, "QtCharts") && inheritedFrom == "" && subjectURL != "qobject", "-qtcharts", "")
 				pageURL := getPageUrl(QtPage, subjectURL+maybeCharts, cmdURL, className)
-				docCommentUrl = "\n/// [Qt documentation](" + pageURL + ")\n///\n"
+				docCommentUrl = "\n/// [Upstream resources](" + pageURL + ")\n///\n"
 				ret.WriteString(docCommentUrl)
 			}
 
@@ -1908,7 +1908,7 @@ const qtc = @import("qt6c");%%_IMPORTLIBS_%% %%_STRUCTDEFS_%%
 			}
 			maybeCharts := ifv(strings.Contains(src.Filename, "QtCharts") && inheritedFrom == "", "-qtcharts", "")
 			pageURL := getPageUrl(QtPage, subjectURL+maybeCharts, cmdURL, className)
-			documentationURL := "\n/// [Qt documentation](" + pageURL + ")\n///\n"
+			documentationURL := "\n/// [Upstream resources](" + pageURL + ")\n///\n"
 
 			// Add a package-private function to call the C++ base class method
 			// QWidget_PaintEvent
@@ -2015,7 +2015,7 @@ const qtc = @import("qt6c");%%_IMPORTLIBS_%% %%_STRUCTDEFS_%%
 			if subjectURL != "" {
 				maybeCharts := ifv(strings.Contains(src.Filename, "QtCharts") && inheritedFrom == "" && subjectURL != "qobject", "-qtcharts", "")
 				pageURL := getPageUrl(QtPage, subjectURL+maybeCharts, cmdURL, className)
-				docCommentUrl = "\n/// [Qt documentation](" + pageURL + ")\n///\n"
+				docCommentUrl = "\n/// [Upstream resources](" + pageURL + ")\n///\n"
 			}
 
 			slotComma := ifv(len(m.Parameters) != 0, ", ", "")
@@ -2036,7 +2036,7 @@ const qtc = @import("qt6c");%%_IMPORTLIBS_%% %%_STRUCTDEFS_%%
 				(strings.Contains(src.Filename, "signon-qt") && zigStructName[0] != 'Q')
 
 			pageUrl := getPageUrl(DtorPage, ifv(isSpecialCase, zigStructName, getPageName(zigStructName))+maybeCharts, "", zigStructName)
-			ret.WriteString(ifv(pageUrl != "", "\n/// [Qt documentation]("+pageUrl+")\n///\n", "\n") +
+			ret.WriteString(ifv(pageUrl != "", "\n/// [Upstream resources]("+pageUrl+")\n///\n", "\n") +
 				"    /// Delete this object from C++ memory.\n///\n" +
 				"    /// ``` self: QtC." + zigStructName + " ```\n" +
 				"    pub fn QDelete(self: ?*anyopaque) void {\n" +