Publish documentation on GitHub Pages (#1602)

## Summary

- Replace the old DocBook XML documentation (`querydsl-docs/` module)
with a modern Jekyll + just-the-docs GitHub Pages site under `docs/`
- Convert all existing documentation from DocBook XML to Markdown with
updated content for the OpenFeign fork
- Add new documentation for R2DBC and Kotlin modules
- Add comprehensive migration guide from the defunct upstream querydsl
project
- Update README links to point to the new documentation site
- Add GitHub Actions workflow that auto-deploys on changes to `docs/**`

## What changed

**New documentation site (`docs/`):**
- Landing page with supported backends table and quick example
- Tutorials: JPA, SQL, R2DBC (new), MongoDB, Collections, Spatial,
Kotlin (new), Scala
- Guides: Creating Queries, Result Handling, Code Generation, Alias
Usage
- Troubleshooting guide
- Migration guide from defunct `com.querydsl` project
- Jekyll config with `just-the-docs` theme, search, edit-on-GitHub links

**Deleted:**
- `querydsl-docs/` module (DocBook XML, XSL stylesheets, jdocbook
config)
- `docs` Maven profile from root `pom.xml`
- DocBook build lines from `dist.sh`

**Updated:**
- `README.md` — replaced dead querydsl.com links with
openfeign.github.io/querydsl
- Added `CONTRIBUTING.md` with docs contribution guide

**Content updates applied during conversion:**
- All Maven examples use `maven-compiler-plugin` with
`annotationProcessorPaths` instead of the old `apt-maven-plugin`
- Version references use `{{ site.querydsl_version }}` (resolves to
`7.1`)
- GroupId uses `{{ site.group_id }}` (resolves to
`io.github.openfeign.querydsl`)
- Dropped references to removed modules (JDO, Lucene, Hibernate Search)
- Updated supported backends list (added R2DBC, Kotlin)
- Grammar and clarity improvements throughout

## Post-merge setup

After merging, enable GitHub Pages in repository Settings > Pages >
Source: **GitHub Actions**. The site will be available at
`https://openfeign.github.io/querydsl`.

## Note

This PR was entirely generated by Claude (claude.ai/code).

Author: velo

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: ["master"]
+    paths:
+      - "docs/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./docs
+          destination: ./_site
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to Querydsl
+
+GitHub pull requests are the way to contribute to Querydsl.
+
+## Documentation
+
+The documentation site is built with [Jekyll](https://jekyllrb.com/) using the
+[just-the-docs](https://just-the-docs.com/) theme and hosted on GitHub Pages.
+
+Source files live in the `docs/` directory. Changes to `docs/**` on the
+`master` branch automatically trigger a rebuild and deploy.
+
+### Editing Documentation
+
+1. Fork the repository and create a branch from `master`.
+2. Edit or add Markdown files under `docs/`.
+3. Use Liquid variables for version and groupId:
+   - `{{ site.querydsl_version }}` — current release version
+   - `{{ site.group_id }}` — Maven groupId
+4. Open a pull request.
+
+### Local Preview
+
+To preview the site locally:
+
+```bash
+cd docs
+bundle install
+bundle exec jekyll serve
+```
+
+Then open `http://localhost:4000/querydsl/` in your browser.
+
+### Structure
+
+```
+docs/
+├── _config.yml           # Jekyll configuration and variables
+├── Gemfile               # Ruby dependencies
+├── index.md              # Landing page
+├── introduction.md       # Background and principles
+├── tutorials/            # Backend-specific tutorials
+├── guides/               # Cross-cutting guides
+├── troubleshooting.md    # Common issues
+└── migration.md          # Migration from upstream querydsl
+```
+
+## Code Contributions
+
+### Building
+
+```bash
+./mvnw -Pquickbuild clean install
+```
+
+### Running Tests
+
+```bash
+# Without external databases
+./mvnw -Pdev verify
+
+# CI profile
+./mvnw -Pci verify
+```
+
+### Code Formatting
+
+```bash
+./mvnw -Pdev initialize
+```
+
+### Pull Request Process
+
+1. Fork the repository and create a feature branch.
+2. Make your changes and add tests where appropriate.
+3. Run `./mvnw -Pdev verify` to make sure tests pass.
+4. Open a pull request against `master`.

README.md

@@ -42,17 +42,23 @@ Get a querydsl project active!  May be as a fork, may be as a wake up call to pr
 
 Well, you will need to get your hands dirty.  I might fix bugs or create features, but mostly when they affect my day job. Sorry, just a single guy here doing free work on spare time.
 
+**Documentation**
+
+Full reference documentation is available at **[openfeign.github.io/querydsl](https://openfeign.github.io/querydsl)**.
+
 **Getting started**
 
 Use these tutorials to get started
 
-* [Querying JPA](http://www.querydsl.com/static/querydsl/latest/reference/html/ch02.html#jpa_integration)
-* [Querying SQL](http://www.querydsl.com/static/querydsl/latest/reference/html/ch02s03.html)
-* [Querying Mongodb](http://www.querydsl.com/static/querydsl/latest/reference/html/ch02s07.html)
-* [Querying Lucene](http://www.querydsl.com/static/querydsl/latest/reference/html/ch02s05.html)
-* [Querying Collections](http://www.querydsl.com/static/querydsl/latest/reference/html/ch02s08.html)
-* [Querydsl Spatial](http://www.querydsl.com/static/querydsl/latest/reference/html/ch02s04.html)
-* [Querying JDO](http://www.querydsl.com/static/querydsl/latest/reference/html/ch02s02.html)
+* [Querying JPA](https://openfeign.github.io/querydsl/tutorials/jpa)
+* [Querying SQL](https://openfeign.github.io/querydsl/tutorials/sql)
+* [Querying R2DBC](https://openfeign.github.io/querydsl/tutorials/r2dbc)
+* [Querying MongoDB](https://openfeign.github.io/querydsl/tutorials/mongodb)
+* [Querying Collections](https://openfeign.github.io/querydsl/tutorials/collections)
+* [Querydsl Spatial](https://openfeign.github.io/querydsl/tutorials/spatial)
+* [Querying in Kotlin](https://openfeign.github.io/querydsl/tutorials/kotlin)
+* [Querying in Scala](https://openfeign.github.io/querydsl/tutorials/scala)
+* [Migration Guide](https://openfeign.github.io/querydsl/migration)
 
 **Examples**
 
@@ -72,7 +78,7 @@ $ mvn -Pquickbuild,{projectname} clean install
 ```
 Where projectname is one of the Maven profiles (e.g. `jpa`, `sql`, `mongodb`, etc. or `all`)
 
-For more information visit the project homepage at https://querydsl.github.io.
+For more information visit the [documentation site](https://openfeign.github.io/querydsl).
 
 **Docker Compose setup**
 

dist.sh

@@ -8,6 +8,3 @@ do
   mvn -pl querydsl-$module -Dtest=X clean assembly:assembly
 done
 
-mkdir -p target/dist/reference
-mvn -f querydsl-docs/pom.xml -Dxslthl.config=http://docbook.sourceforge.net/release/xsl/current/highlighting/xslthl-config.xml clean package
-cp -R querydsl-docs/target/docbook/publish/en-US/* target/dist/reference/

docs/.gitignore

@@ -0,0 +1,3 @@
+_site/
+.jekyll-cache/
+Gemfile.lock

docs/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "just-the-docs", "~> 0.10"
+gem "jekyll-remote-theme"
+
+group :jekyll_plugins do
+  gem "jekyll-seo-tag"
+  gem "jekyll-include-cache"
+end

docs/_config.yml

@@ -0,0 +1,62 @@
+title: Querydsl
+description: >-
+  Type-safe SQL-like queries for Java — JPA, SQL, MongoDB, R2DBC, Collections, and more.
+url: "https://openfeign.github.io"
+baseurl: "/querydsl"
+
+remote_theme: just-the-docs/just-the-docs@v0.10.0
+
+querydsl_version: "7.1"
+group_id: "io.github.openfeign.querydsl"
+
+permalink: pretty
+
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - node_modules
+  - vendor
+
+search_enabled: true
+
+heading_anchors: true
+
+nav_enabled: true
+
+back_to_top: true
+back_to_top_text: "Back to top"
+
+aux_links:
+  GitHub:
+    - "https://github.com/OpenFeign/querydsl"
+  Maven Central:
+    - "https://central.sonatype.com/namespace/io.github.openfeign.querydsl"
+
+aux_links_new_tab: true
+
+gh_edit_link: true
+gh_edit_link_text: "Edit this page on GitHub"
+gh_edit_repository: "https://github.com/OpenFeign/querydsl"
+gh_edit_branch: "master"
+gh_edit_source: "docs"
+gh_edit_view_mode: "edit"
+
+footer_content: >-
+  Copyright © 2007–2026 Querydsl team. Maintained by the
+  <a href="https://github.com/OpenFeign/querydsl">OpenFeign community</a>.
+  Distributed under the
+  <a href="https://github.com/OpenFeign/querydsl/blob/master/LICENSE">Apache License 2.0</a>.
+
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+callouts:
+  warning:
+    title: Warning
+    color: red
+  note:
+    title: Note
+    color: blue
+  tip:
+    title: Tip
+    color: green

…-docs/src/main/docbook/media/spatial.svg docs/assets/images/spatial.svgquerydsl-docs/src/main/docbook/media/spatial.svg renamed to docs/assets/images/spatial.svg querydsl-docs/src/main/docbook/media/spatial.svg renamed to docs/assets/images/spatial.svg

@@ -0,0 +1,78 @@
+---
+layout: default
+title: Alias Usage
+parent: Guides
+nav_order: 4
+---
+
+# Alias Usage
+
+In cases where code generation is not an option, alias objects can be used as
+path references for expression construction. They work via proxied Java Bean
+objects through getter method invocations.
+
+The following examples demonstrate how alias objects can be used as
+replacements for expression creation based on generated types.
+
+First, an example query with APT-generated domain types:
+
+```java
+QCat cat = new QCat("cat");
+for (String name : queryFactory.select(cat.name).from(cat,cats)
+    .where(cat.kittens.size().gt(0))
+    .fetch()) {
+    System.out.println(name);
+}
+```
+
+And now with an alias instance for the `Cat` class. The call
+`c.getKittens()` inside the dollar-method is internally transformed into the
+property path `c.kittens`.
+
+```java
+Cat c = alias(Cat.class, "cat");
+for (String name : select($(c.getName())).from($(c),cats)
+    .where($(c.getKittens()).size().gt(0))
+    .fetch()) {
+    System.out.println(name);
+}
+```
+
+To use the alias functionality, add the following two imports:
+
+```java
+import static com.querydsl.core.alias.Alias.$;
+import static com.querydsl.core.alias.Alias.alias;
+```
+
+The following example is a variation where the access to the list size happens
+inside the dollar-method invocation:
+
+```java
+Cat c = alias(Cat.class, "cat");
+for (String name : queryFactory.select($(c.getName())).from($(c),cats)
+    .where($(c.getKittens().size()).gt(0))
+    .fetch()) {
+    System.out.println(name);
+}
+```
+
+All non-primitive and non-final typed properties of aliases are aliases
+themselves. You may cascade method calls until you hit a primitive or final
+type in the dollar-method scope, e.g.:
+
+```java
+$(c.getMate().getName())
+```
+
+is transformed into `c.mate.name` internally, but:
+
+```java
+$(c.getMate().getName().toLowerCase())
+```
+
+is not transformed properly, since the `toLowerCase()` invocation is not
+tracked.
+
+You may only invoke getters, `size()`, `contains(Object)`, and `get(int)` on
+alias types. All other invocations throw exceptions.