From bc031f2d8be27052b961a35273c676f685873b76 Mon Sep 17 00:00:00 2001 From: Leo Galambos Date: Sat, 18 Apr 2026 02:14:45 +0200 Subject: [PATCH] feat: add MkDocs Material site and publish docs + CI reports to GitHub Pages --- .classpath | 8 +- .github/workflows/pages.yml | 120 ++++++++++++++++------------- docs/architecture-and-reduction.md | 2 - docs/benchmarking.md | 2 - docs/built-in-languages.md | 2 - docs/cli-compilation.md | 2 - docs/dictionary-format.md | 2 - docs/index.md | 20 +++++ docs/programmatic-usage.md | 2 - docs/quality-and-operations.md | 2 - docs/quick-start.md | 2 - docs/reports.md | 27 +++++++ mkdocs.yml | 42 ++++++++++ 13 files changed, 158 insertions(+), 75 deletions(-) create mode 100644 docs/index.md create mode 100644 docs/reports.md create mode 100644 mkdocs.yml diff --git a/.classpath b/.classpath index ad520db..562e771 100644 --- a/.classpath +++ b/.classpath @@ -3,20 +3,20 @@ - + - + - + @@ -36,7 +36,7 @@ - + diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 5873298..b32dbf7 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -5,6 +5,8 @@ on: branches: - main paths: + - 'docs/**' + - 'mkdocs.yml' - 'src/main/**' - 'src/test/**' - 'src/jmh/**' @@ -50,6 +52,14 @@ jobs: - name: Set up Gradle caching and instrumentation uses: gradle/actions/setup-gradle@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' + + - name: Install MkDocs Material + run: python -m pip install --upgrade pip mkdocs-material + - name: Verify reproducibility inputs shell: bash run: | @@ -111,12 +121,17 @@ jobs: JMH_CSV_LINK='' JMH_TXT_LATEST_LINK='' JMH_CSV_LATEST_LINK='' + JMH_TXT_REPORT_MD='- Benchmark results (TXT): not currently available' + JMH_CSV_REPORT_MD='- Benchmark results (CSV): not currently available' DEPENDENCY_CHECK_LINK='' DEPENDENCY_CHECK_LATEST_LINK='' + DEPENDENCY_CHECK_REPORT_MD='- Dependency vulnerability report: not currently available' SBOM_JSON_LINK='' SBOM_XML_LINK='' SBOM_JSON_LATEST_LINK='' SBOM_XML_LATEST_LINK='' + SBOM_JSON_REPORT_MD='- SBOM (JSON): not currently available' + SBOM_XML_REPORT_MD='- SBOM (XML): not currently available' if [ -d "build/reports/jmh" ]; then cp -R build/reports/jmh "${RUN_DIR}/jmh" @@ -125,10 +140,12 @@ jobs: if [ -f "${RUN_DIR}/jmh/jmh-results.txt" ]; then JMH_TXT_LINK='
  • Benchmark Results (TXT)
    • ' JMH_TXT_LATEST_LINK='
  • Benchmark Results (TXT)
    • ' + JMH_TXT_REPORT_MD='- [JMH benchmark results (TXT)](../builds/latest/jmh/jmh-results.txt)' fi if [ -f "${RUN_DIR}/jmh/jmh-results.csv" ]; then JMH_CSV_LINK='
  • Benchmark Results (CSV)
    • ' JMH_CSV_LATEST_LINK='
  • Benchmark Results (CSV)
    • ' + JMH_CSV_REPORT_MD='- [JMH benchmark results (CSV)](../builds/latest/jmh/jmh-results.csv)' fi HAS_JMH="true" @@ -143,6 +160,7 @@ jobs: if [ -f "${RUN_DIR}/dependency-check/dependency-check-report.html" ]; then DEPENDENCY_CHECK_LINK='
  • Dependency Vulnerability Report
    • ' DEPENDENCY_CHECK_LATEST_LINK='
  • Dependency Vulnerability Report
    • ' + DEPENDENCY_CHECK_REPORT_MD='- [Dependency vulnerability report](../builds/latest/dependency-check/dependency-check-report.html)' fi fi @@ -153,6 +171,8 @@ jobs: SBOM_XML_LINK='
  • SBOM (XML)
    • ' SBOM_JSON_LATEST_LINK='
  • SBOM (JSON)
    • ' SBOM_XML_LATEST_LINK='
  • SBOM (XML)
    • ' + SBOM_JSON_REPORT_MD='- [SBOM (JSON)](../builds/latest/sbom/radixor-sbom.json)' + SBOM_XML_REPORT_MD='- [SBOM (XML)](../builds/latest/sbom/radixor-sbom.xml)' fi python3 \ @@ -169,10 +189,22 @@ jobs: MUTATION_BADGE_LATEST_LINK='
  • Mutation Badge Metadata
    • ' JMH_BADGE_LINK='
  • Benchmark Badge Metadata
    • ' JMH_BADGE_LATEST_LINK='
  • Benchmark Badge Metadata
    • ' + COVERAGE_BADGE_REPORT_MD='- [Coverage badge metadata](../builds/latest/metrics/coverage-badge.json)' + MUTATION_BADGE_REPORT_MD='- [Mutation badge metadata](../builds/latest/metrics/pitest-badge.json)' + JMH_BADGE_REPORT_MD='- [Benchmark badge metadata](../builds/latest/metrics/jmh-badge.json)' if [ ! -f "${RUN_METRICS_DIR}/coverage-badge.json" ]; then COVERAGE_BADGE_LINK='
  • Coverage Badge Metadata: not available
    • ' COVERAGE_BADGE_LATEST_LINK='
  • Coverage Badge Metadata: not available
    • ' + COVERAGE_BADGE_REPORT_MD='- Coverage badge metadata: not currently available' + fi + + if [ ! -f "${RUN_METRICS_DIR}/pitest-badge.json" ]; then + MUTATION_BADGE_REPORT_MD='- Mutation badge metadata: not currently available' + fi + + if [ ! -f "${RUN_METRICS_DIR}/jmh-badge.json" ]; then + JMH_BADGE_REPORT_MD='- Benchmark badge metadata: not currently available' fi cat > "${RUN_DIR}/index.html" < "${SITE_DIR}/.nojekyll" < docs/reports.md < - - - - - Radixor Reports - - - -

    Radixor Published Reports

    -

    Durable CI reports published from GitHub Actions to the gh-pages branch.

    + Radixor publishes durable CI artifacts to GitHub Pages on every qualifying run of \`.github/workflows/pages.yml\`. -

    Latest

    -
      -
    • Latest build summary
      • -
    • Javadoc
      • -
    • Test Report
      • -
    • PMD Report
      • -
    • Coverage Report
      • - ${DEPENDENCY_CHECK_LATEST_LINK:-
    • Dependency Vulnerability Report: not currently available
      • } - ${SBOM_JSON_LATEST_LINK:-
    • SBOM (JSON): not available
      • } - ${SBOM_XML_LATEST_LINK:-
    • SBOM (XML): not available
      • } - ${COVERAGE_BADGE_LATEST_LINK} - ${MUTATION_BADGE_LATEST_LINK} - ${JMH_BADGE_LATEST_LINK} -
    • Mutation Testing Report
      • - $( - [ "${HAS_JMH}" = "true" ] && { echo "${JMH_TXT_LATEST_LINK:-
    • Benchmark Results (TXT): not available
      • }"; echo "${JMH_CSV_LATEST_LINK:-
    • Benchmark Results (CSV): not available
      • }"; } \ - || echo '
    • Benchmark results: not currently available
      • ' - ) + ## Primary report entry points + + - [Latest build summary](../builds/latest/) + - [Javadoc](../builds/latest/javadoc/) + - [Unit test report](../builds/latest/test/) + - [PMD report](../builds/latest/pmd/main.html) + - [JaCoCo coverage report](../builds/latest/coverage/) + - [PIT mutation testing report](../builds/latest/pitest/) + ${DEPENDENCY_CHECK_REPORT_MD} + ${SBOM_JSON_REPORT_MD} + ${SBOM_XML_REPORT_MD} + + ## Benchmark and badge metadata + + ${JMH_TXT_REPORT_MD} + ${JMH_CSV_REPORT_MD} + ${COVERAGE_BADGE_REPORT_MD} + ${MUTATION_BADGE_REPORT_MD} + ${JMH_BADGE_REPORT_MD} + + ## Historical runs + + - [Browse historical build reports](../builds/) EOF - cat < - -

      Recent historical builds

      -
        - EOF - - for build in ${BUILD_LIST}; do - echo "
      • Build ${build}
        • " - done - - cat < - - - EOF - } > "${SITE_DIR}/index.html" + - name: Build documentation site (MkDocs Material) + shell: bash + run: | + set -euo pipefail + mkdocs build --strict --site-dir .mkdocs-site + rsync -a --delete --exclude 'builds/' .mkdocs-site/ .gh-pages/ + rm -rf .mkdocs-site - name: Commit and push gh-pages shell: bash diff --git a/docs/architecture-and-reduction.md b/docs/architecture-and-reduction.md index d4b4a45..df0735d 100644 --- a/docs/architecture-and-reduction.md +++ b/docs/architecture-and-reduction.md @@ -1,7 +1,5 @@ # Architecture and Reduction -> ← Back to [README.md](../README.md) - This document describes the internal architecture of **Radixor** and the principles behind its **trie compilation and reduction model**. It explains: diff --git a/docs/benchmarking.md b/docs/benchmarking.md index 9cf75e3..8f5d935 100644 --- a/docs/benchmarking.md +++ b/docs/benchmarking.md @@ -1,7 +1,5 @@ # Benchmarking -> ← Back to [README.md](../README.md) - Radixor includes a JMH benchmark suite for both the internal algorithmic core and a side-by-side English comparison against the Snowball Porter stemmer family. This document explains what is benchmarked, how to run it, and how to interpret the results responsibly. diff --git a/docs/built-in-languages.md b/docs/built-in-languages.md index 2883ce8..8380889 100644 --- a/docs/built-in-languages.md +++ b/docs/built-in-languages.md @@ -1,7 +1,5 @@ # Built-in Languages -> ← Back to [README.md](../README.md) - Radixor provides a set of **bundled stemmer dictionaries** that can be loaded directly without preparing custom data. These built-in resources are useful for: diff --git a/docs/cli-compilation.md b/docs/cli-compilation.md index 04ef04a..5f7559b 100644 --- a/docs/cli-compilation.md +++ b/docs/cli-compilation.md @@ -1,7 +1,5 @@ # CLI Compilation -> ← Back to [README.md](../README.md) - Radixor provides a command-line tool for compiling dictionary files into compact, production-ready binary stemmer tables. This is the recommended workflow for deployment environments, as it separates: diff --git a/docs/dictionary-format.md b/docs/dictionary-format.md index 6994614..31d3fbe 100644 --- a/docs/dictionary-format.md +++ b/docs/dictionary-format.md @@ -1,7 +1,5 @@ # Dictionary Format -> ← Back to [README.md](../README.md) - Radixor uses a simple, line-oriented dictionary format to define mappings between **word forms** and their **canonical stems**. This format is intentionally minimal, language-agnostic, and easy to generate from existing linguistic resources or corpora. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e448a66 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,20 @@ +# Radixor + +**Radixor** is a high-performance, multi-language stemmer for Java, designed for production-grade search and text-processing systems. + +It modernizes the proven Egothor patch-command trie approach and delivers: + +- **Fast runtime stemming** with compact lookup structures +- **Multi-language adaptability** through dictionary-driven compilation +- **Deterministic behavior** suitable for reproducible processing pipelines +- **Flexible integration paths**, including CLI-based and programmatic workflows +- **Operational transparency** via continuously published quality and benchmark reports + +Radixor is built for teams that need consistent stemming quality at scale without sacrificing maintainability or deployment efficiency. + +## Start here + +- Read [Quick Start](quick-start.md) for immediate implementation guidance. +- Use [Programmatic Usage](programmatic-usage.md) for application integration patterns. +- Review [Benchmarking](benchmarking.md) for reproducible performance methodology. +- Open [CI Reports](reports.md) to inspect published build artifacts and quality metrics. diff --git a/docs/programmatic-usage.md b/docs/programmatic-usage.md index b407430..a19dc94 100644 --- a/docs/programmatic-usage.md +++ b/docs/programmatic-usage.md @@ -1,7 +1,5 @@ # Programmatic Usage -> ← Back to [README.md](../README.md) - This document describes how to use **Radixor** programmatically from Java. It covers: diff --git a/docs/quality-and-operations.md b/docs/quality-and-operations.md index e070eb3..9e2368c 100644 --- a/docs/quality-and-operations.md +++ b/docs/quality-and-operations.md @@ -1,7 +1,5 @@ # Quality and Operations -> ← Back to [README.md](../README.md) - This document describes quality, testing, and operational practices for **Radixor**. It focuses on: diff --git a/docs/quick-start.md b/docs/quick-start.md index 59cc958..4b81ec0 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -1,7 +1,5 @@ # Quick Start -> ← Back to [README.md](../README.md) - This guide shows the fastest way to start using **Radixor** and the most common next steps. ## Hello world diff --git a/docs/reports.md b/docs/reports.md new file mode 100644 index 0000000..a7054c3 --- /dev/null +++ b/docs/reports.md @@ -0,0 +1,27 @@ +# CI Reports + +Radixor publishes durable CI artifacts to GitHub Pages on every qualifying run of `.github/workflows/pages.yml`. + +## Primary report entry points + +- [Latest build summary](../builds/latest/) +- [Javadoc](../builds/latest/javadoc/) +- [Unit test report](../builds/latest/test/) +- [PMD report](../builds/latest/pmd/main.html) +- [JaCoCo coverage report](../builds/latest/coverage/) +- [PIT mutation testing report](../builds/latest/pitest/) +- [Dependency vulnerability report](../builds/latest/dependency-check/dependency-check-report.html) +- [SBOM (JSON)](../builds/latest/sbom/radixor-sbom.json) +- [SBOM (XML)](../builds/latest/sbom/radixor-sbom.xml) + +## Benchmark and badge metadata + +- [JMH benchmark results (TXT)](../builds/latest/jmh/jmh-results.txt) +- [JMH benchmark results (CSV)](../builds/latest/jmh/jmh-results.csv) +- [Coverage badge metadata](../builds/latest/metrics/coverage-badge.json) +- [Mutation badge metadata](../builds/latest/metrics/pitest-badge.json) +- [Benchmark badge metadata](../builds/latest/metrics/jmh-badge.json) + +## Historical runs + +- [Browse historical build reports](../builds/) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..8077180 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,42 @@ +site_name: Radixor +site_description: High-performance multi-language stemming toolkit for Java +site_url: https://leogalambos.github.io/Radixor/ +repo_url: https://github.com/leogalambos/Radixor +repo_name: leogalambos/Radixor +copyright: "© ${year} Egothor. Licensed under BSD-3-Clause." + +theme: + name: material + language: en + features: + - navigation.instant + - navigation.sections + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + palette: + - scheme: default + primary: indigo + accent: indigo + +markdown_extensions: + - admonition + - attr_list + - md_in_html + - pymdownx.details + - pymdownx.highlight + - pymdownx.superfences + - tables + +nav: + - Home: index.md + - Quick Start: quick-start.md + - Dictionary Format: dictionary-format.md + - CLI Compilation: cli-compilation.md + - Programmatic Usage: programmatic-usage.md + - Built-in Languages: built-in-languages.md + - Architecture and Reduction: architecture-and-reduction.md + - Quality and Operations: quality-and-operations.md + - Benchmarking: benchmarking.md + - CI Reports: reports.md