From cad5ef59db0bdf9a51067e3e323ecde0f6b794fe Mon Sep 17 00:00:00 2001 From: LeonardoBai12 <69223422+LeonardoBai12@users.noreply.github.com> Date: Mon, 22 Jun 2026 17:48:54 -0300 Subject: [PATCH 01/12] Add GitHub Pages documentation site Jekyll site (Chirpy theme) built from documentation/ folder with the same sidebar template as AdvancedKotlinAndroidEngineering. KDoc is generated from source on every push to main via Dokka and copied into _site/kdoc/ before deployment, keeping the API reference always current. Pages covered: home, how it works, key features, mapping rules, mapping request (including X-Mapped-Auth), preview route, endpoints overview, Postman collection, and KDoc reference. Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/pages_workflow.yml | 71 +++++++ documentation/Gemfile | 9 + documentation/Gemfile.lock | 108 ++++++++++ documentation/_config.yml | 89 ++++++++ documentation/_data/navigation.yml | 35 ++++ documentation/_includes/metadata-hook.html | 1 + documentation/_includes/sidebar.html | 167 +++++++++++++++ documentation/api-reference/index.md | 33 +++ documentation/assets/css/custom.css | 198 ++++++++++++++++++ documentation/endpoints/index.md | 66 ++++++ documentation/endpoints/postman.md | 45 ++++ .../getting-started/mapping-request/index.md | 169 +++++++++++++++ .../getting-started/mapping-rules/index.md | 116 ++++++++++ .../getting-started/preview-route/index.md | 109 ++++++++++ documentation/index.md | 43 ++++ documentation/overview/index.md | 82 ++++++++ documentation/overview/key-features.md | 69 ++++++ 17 files changed, 1410 insertions(+) create mode 100644 .github/workflows/pages_workflow.yml create mode 100644 documentation/Gemfile create mode 100644 documentation/Gemfile.lock create mode 100644 documentation/_config.yml create mode 100644 documentation/_data/navigation.yml create mode 100644 documentation/_includes/metadata-hook.html create mode 100644 documentation/_includes/sidebar.html create mode 100644 documentation/api-reference/index.md create mode 100644 documentation/assets/css/custom.css create mode 100644 documentation/endpoints/index.md create mode 100644 documentation/endpoints/postman.md create mode 100644 documentation/getting-started/mapping-request/index.md create mode 100644 documentation/getting-started/mapping-rules/index.md create mode 100644 documentation/getting-started/preview-route/index.md create mode 100644 documentation/index.md create mode 100644 documentation/overview/index.md create mode 100644 documentation/overview/key-features.md diff --git a/.github/workflows/pages_workflow.yml b/.github/workflows/pages_workflow.yml new file mode 100644 index 0000000..f8dfcc0 --- /dev/null +++ b/.github/workflows/pages_workflow.yml @@ -0,0 +1,71 @@ +name: Deploy Documentation to GitHub Pages + +on: + push: + branches: ["main"] + 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: Set up JDK 17 + uses: actions/setup-java@v4 + with: + java-version: 17 + distribution: temurin + + - name: Make gradlew executable + run: chmod +x ./gradlew + + - name: Generate KDoc + run: ./gradlew dokkaHtmlMultiModule + + - name: Setup Ruby + uses: ruby/setup-ruby@4a9ddd6f338a97768b8006bf671dfbad383215f4 + with: + ruby-version: '3.3' + bundler-cache: true + cache-version: 0 + working-directory: documentation + + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + + - name: Build Jekyll site + working-directory: documentation + run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + env: + JEKYLL_ENV: production + + - name: Copy KDoc into site + run: cp -r build/dokka/htmlMultiModule documentation/_site/kdoc + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: documentation/_site + + 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@v5 diff --git a/documentation/Gemfile b/documentation/Gemfile new file mode 100644 index 0000000..f63a769 --- /dev/null +++ b/documentation/Gemfile @@ -0,0 +1,9 @@ +source "https://rubygems.org" + +gem "jekyll", "~> 4.3" +gem "jekyll-theme-chirpy", "~> 7.2" + +group :jekyll_plugins do + gem "jekyll-sitemap" + gem "jekyll-seo-tag", "~> 2.8" +end diff --git a/documentation/Gemfile.lock b/documentation/Gemfile.lock new file mode 100644 index 0000000..51f3282 --- /dev/null +++ b/documentation/Gemfile.lock @@ -0,0 +1,108 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.9.0) + public_suffix (>= 2.0.2, < 8.0) + base64 (0.3.0) + bigdecimal (4.1.2) + colorator (1.1.0) + concurrent-ruby (1.3.6) + csv (3.3.5) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + ffi (1.17.4-arm64-darwin) + ffi (1.17.4-x86_64-linux-gnu) + forwardable-extended (2.6.0) + google-protobuf (4.35.0-arm64-darwin) + bigdecimal + rake (~> 13.3) + google-protobuf (4.35.0-x86_64-linux-gnu) + bigdecimal + rake (~> 13.3) + http_parser.rb (0.8.1) + i18n (1.14.8) + concurrent-ruby (~> 1.0) + jekyll (4.4.1) + addressable (~> 2.4) + base64 (~> 0.2) + colorator (~> 1.0) + csv (~> 3.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + json (~> 2.6) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (~> 0.3, >= 0.3.6) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-archives (2.3.0) + jekyll (>= 3.6, < 5.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-paginate (1.1.0) + jekyll-sass-converter (3.1.0) + sass-embedded (~> 1.75) + jekyll-seo-tag (2.9.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-theme-chirpy (7.5.0) + jekyll (~> 4.3) + jekyll-archives (~> 2.2) + jekyll-include-cache (~> 0.2) + jekyll-paginate (~> 1.1) + jekyll-seo-tag (~> 2.8) + jekyll-sitemap (~> 1.4) + jekyll-watch (2.2.1) + listen (~> 3.0) + json (2.19.8) + kramdown (2.5.2) + rexml (>= 3.4.4) + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.10.0) + logger + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + logger (1.7.0) + mercenary (0.4.0) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (7.0.5) + rake (13.4.2) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.4.4) + rouge (4.7.0) + safe_yaml (1.0.5) + sass-embedded (1.100.0-arm64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.100.0-x86_64-linux-gnu) + google-protobuf (~> 4.31) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.6.0) + webrick (1.9.2) + +PLATFORMS + arm64-darwin-22 + x86_64-linux + +DEPENDENCIES + jekyll (~> 4.3) + jekyll-seo-tag (~> 2.8) + jekyll-sitemap + jekyll-theme-chirpy (~> 7.2) + +BUNDLED WITH + 2.4.10 diff --git a/documentation/_config.yml b/documentation/_config.yml new file mode 100644 index 0000000..0689ce0 --- /dev/null +++ b/documentation/_config.yml @@ -0,0 +1,89 @@ +theme: jekyll-theme-chirpy + +# ------------------------- +# Site metadata +# ------------------------- +title: ProjectMiddleware +tagline: A Kotlin/Ktor middleware for transforming and mapping external API responses +description: >- + ProjectMiddleware is an API transformation layer that lets clients register + mapping rules, call external APIs, and receive clean transformed responses — + all without changing upstream services. + +url: "https://leonardobai12.github.io" +baseurl: "/ProjectMiddleware" + +lang: en +timezone: America/Sao_Paulo + +# ------------------------- +# Author +# ------------------------- +github: + username: "LeonardoBai12" + +social: + name: "Leonardo Bai" + email: "lb.io.dev@gmail.com" + links: + - https://github.com/LeonardoBai12 + +# ------------------------- +# Theme preferences +# ------------------------- +theme_mode: # leave blank to follow system default; or "light" / "dark" + +avatar: "/assets/img/logo.png" + +toc: true + +# ------------------------- +# Analytics (optional) +# ------------------------- +google_analytics: + id: "" + +# ------------------------- +# SEO +# ------------------------- +google_site_verification: "" + +# ------------------------- +# Jekyll build settings +# ------------------------- +permalink: pretty + +exclude: + - "*.gem" + - "*.gemspec" + - Gemfile + - Gemfile.lock + - README.md + - node_modules + - vendor + - .bundle + - .sass-cache + - .jekyll-cache + - MappingRules.md + - MappingRequest.md + - PreviewRoute.md + +markdown: kramdown +highlighter: rouge + +kramdown: + syntax_highlighter: rouge + syntax_highlighter_opts: + css_class: highlight + span: + line_numbers: false + block: + line_numbers: true + start_line: 1 + +# ------------------------- +# Plugins +# ------------------------- +plugins: + - jekyll-sitemap + - jekyll-seo-tag diff --git a/documentation/_data/navigation.yml b/documentation/_data/navigation.yml new file mode 100644 index 0000000..3c52d43 --- /dev/null +++ b/documentation/_data/navigation.yml @@ -0,0 +1,35 @@ +- title: "Overview" + url_prefix: "overview" + url: "/overview/" + chapters: + - title: "How It Works" + url: "/overview/" + - title: "Key Features" + url: "/overview/key-features/" + +- title: "Getting Started" + url_prefix: "getting-started" + url: "/getting-started/mapping-rules/" + chapters: + - title: "Mapping Rules" + url: "/getting-started/mapping-rules/" + - title: "Mapping Request" + url: "/getting-started/mapping-request/" + - title: "Preview Route" + url: "/getting-started/preview-route/" + +- title: "Endpoints" + url_prefix: "endpoints" + url: "/endpoints/" + chapters: + - title: "Endpoints Overview" + url: "/endpoints/" + - title: "Postman Collection" + url: "/endpoints/postman/" + +- title: "API Reference" + url_prefix: "api-reference" + url: "/api-reference/" + chapters: + - title: "KDoc Reference" + url: "/api-reference/" diff --git a/documentation/_includes/metadata-hook.html b/documentation/_includes/metadata-hook.html new file mode 100644 index 0000000..34359db --- /dev/null +++ b/documentation/_includes/metadata-hook.html @@ -0,0 +1 @@ + diff --git a/documentation/_includes/sidebar.html b/documentation/_includes/sidebar.html new file mode 100644 index 0000000..8fe0a45 --- /dev/null +++ b/documentation/_includes/sidebar.html @@ -0,0 +1,167 @@ + + + + diff --git a/documentation/api-reference/index.md b/documentation/api-reference/index.md new file mode 100644 index 0000000..fcd1164 --- /dev/null +++ b/documentation/api-reference/index.md @@ -0,0 +1,33 @@ +--- +layout: page +title: KDoc Reference +--- + +The KDoc reference is auto-generated from the source code on every push to `main` using [Dokka](https://github.com/Kotlin/dokka). It documents all public and internal declarations across every module. + +--- + +## View the KDoc + +[**Open KDoc Reference →**](../kdoc/index.html){:target="_blank"} + +--- + +## Modules covered + +| Module | Description | +|--------|-------------| +| `common:shared` | `MiddlewareException`, `Resource` | +| `common:data` | Core models (`MappedRoute`, `OriginalRoute`, `MappedResponse`) and service interfaces | +| `middleware:domain` | Use cases, state machine, repository interface | +| `middleware:data` | `MiddlewareRepositoryImpl`, `MiddlewareDataSource` | +| `middleware:mapper` | JSON transformation engine | +| `impl:ktor-server` | HTTP server routing and `ServerServiceImpl` | +| `impl:ktor-client` | HTTP client, JWT token generation, `ClientServiceImpl` | +| `impl:mongo-database` | MongoDB persistence, `DatabaseServiceImpl` | + +--- + +## How it stays up to date + +The GitHub Actions workflow regenerates KDoc from the source on every push to `main`, then publishes the updated HTML alongside this site. No manual steps required. diff --git a/documentation/assets/css/custom.css b/documentation/assets/css/custom.css new file mode 100644 index 0000000..3df37c7 --- /dev/null +++ b/documentation/assets/css/custom.css @@ -0,0 +1,198 @@ +/* Avatar: square image fills the circle edge-to-edge */ +#avatar img { + object-fit: cover; + object-position: center; +} + + +/* ── Documentation navigation tree ── */ + +.docs-divider { + margin: 0.5rem 1rem; + opacity: 0.2; +} + +.docs-nav { + list-style: none; + margin: 0; + padding: 0 0 0.5rem 0; + overflow-y: auto; + overflow-x: hidden; + max-height: calc(100vh - 300px); + scrollbar-width: thin; + scrollbar-color: rgba(128,128,128,0.25) transparent; +} + +/* #sidebar specificity (1,0,1) beats Chirpy's #sidebar ul { margin-bottom: 2rem } */ +#sidebar .docs-nav ul { + margin: 0; +} + +/* ── Part headers ── */ +.docs-part-item { + margin-bottom: 0.25rem; +} + +.docs-part-summary { + display: flex; + align-items: center; + flex-wrap: nowrap; + width: 100%; + padding: 0.6rem 1rem; + cursor: pointer; + border: none; + background: none; + border-radius: 0.75rem; + color: var(--sidebar-btn-color, inherit); + font-size: 0.88rem; + font-weight: 600; + user-select: none; + transition: background-color 0.3s ease-in-out; + text-align: left; +} + +.docs-part-summary:hover { + background: var(--sidebar-hover-bg, rgba(128,128,128,0.12)); +} + +.docs-part-summary i { + margin-right: 0.5rem; + font-size: 0.85rem; + opacity: 0.75; + flex-shrink: 0; +} + +.docs-part-summary span { + flex: 1; + min-width: 0; +} + +/* Part collapse arrow — rotates when open, via Bootstrap .collapsed class */ +.docs-part-summary::after { + content: "\f105"; + font-family: "Font Awesome 5 Free"; + font-weight: 900; + flex-shrink: 0; + margin-left: 0.4rem; + font-size: 0.75rem; + opacity: 0.5; + transition: transform 0.2s; + transform: rotate(90deg); +} + +.docs-part-summary.collapsed::after { + transform: rotate(0deg); +} + +/* ── Chapter links ── */ +.docs-chapters-list { + list-style: none; + padding: 0.1rem 0 0.4rem 1rem; + margin: 0; +} + +.docs-chapter-item { + margin-bottom: 0.1rem; +} + +/* Shared base for both and