From 5a5a92d6f0467992f19969190dec292053cbf61e Mon Sep 17 00:00:00 2001 From: yawkat Date: Tue, 16 Dec 2025 14:17:16 +0100 Subject: [PATCH 1/7] github-pages documentation --- .github/workflows/docs.yml | 47 ++++++++++++++++ docs/common.css | 17 ++++++ docs/header-javadoc.html.jinja | 1 + docs/header.html.jinja | 24 ++++++++ docs/index.html.jinja | 16 ++++++ docs/javadoc.css | 16 ++++++ docs/justfile | 100 +++++++++++++++++++++++++++++++++ docs/markdown.css | 38 +++++++++++++ 8 files changed, 259 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/common.css create mode 100644 docs/header-javadoc.html.jinja create mode 100644 docs/header.html.jinja create mode 100644 docs/index.html.jinja create mode 100644 docs/javadoc.css create mode 100644 docs/justfile create mode 100644 docs/markdown.css diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..0289ffa --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,47 @@ +name: Build Documentation + +on: + release: + types: [published] + workflow_dispatch: + pull_request: # TODO + +jobs: + build: + name: Build documentation + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Setup Temurin JDK 21 + uses: actions/setup-java@v5 + with: + distribution: temurin + java-version: '21' + cache: maven + - name: Install uv + uses: astral-sh/setup-uv@v7 + - name: Install just + run: sudo apt install -y just + - name: Build documentation + run: cd docs && just all + - name: Upload pages artifact + id: deployment + uses: actions/upload-pages-artifact@v3 + with: + path: 'docs/target/site/' + deploy: + needs: build + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/common.css b/docs/common.css new file mode 100644 index 0000000..ef2aa83 --- /dev/null +++ b/docs/common.css @@ -0,0 +1,17 @@ +#lz4-header .dropdown { + position: absolute; + display: none; + width: auto; + right: 0; +} +#lz4-header:hover .dropdown { + display: block; +} +#lz4-header .dropdown li { + display: block; + float: left; + clear: both; +} +#lz4-header .selected { + font-weight: bold; +} \ No newline at end of file diff --git a/docs/header-javadoc.html.jinja b/docs/header-javadoc.html.jinja new file mode 100644 index 0000000..0829bf1 --- /dev/null +++ b/docs/header-javadoc.html.jinja @@ -0,0 +1 @@ +{% set version_root = '{@docroot}/..' %}{% include "header.html.jinja" %} \ No newline at end of file diff --git a/docs/header.html.jinja b/docs/header.html.jinja new file mode 100644 index 0000000..d4ccabb --- /dev/null +++ b/docs/header.html.jinja @@ -0,0 +1,24 @@ + \ No newline at end of file diff --git a/docs/index.html.jinja b/docs/index.html.jinja new file mode 100644 index 0000000..3e465de --- /dev/null +++ b/docs/index.html.jinja @@ -0,0 +1,16 @@ + + + + + + lz4-java {% if selected_version == latest_version_name %}{{ latest_version }}{% else %}{{ selected_version }}{% endif %} + + + + + + {% set version_root = '.' %} + {% include "header.html.jinja" %} + {{ readme()|safe }} + + \ No newline at end of file diff --git a/docs/javadoc.css b/docs/javadoc.css new file mode 100644 index 0000000..994cbcc --- /dev/null +++ b/docs/javadoc.css @@ -0,0 +1,16 @@ +#lz4-header .dropdown { + background: var(--navbar-background-color); + z-index: 9999; + margin: 0; + padding: 1em 0 0 0; +} +.about-language { + padding: 0 !important; + margin-top: 0 !important; + font-size: inherit !important; + height: auto !important; +} +#lz4-header .outdated { + background-color: var(--selected-background-color); + color: var(--selected-text-color); +} \ No newline at end of file diff --git a/docs/justfile b/docs/justfile new file mode 100644 index 0000000..da652df --- /dev/null +++ b/docs/justfile @@ -0,0 +1,100 @@ +all_versions := `git tag --list 'v*' | tr '\n' ' '` +latest_version := `git describe --tags --match='v*'` + +build := "target" +path_javadoc := "javadoc" +latest_version_name := "current" + +repo TAG: + rm -rf '{{build}}/repo/lz4-java-{{TAG}}' + if [ '{{TAG}}' = '{{latest_version_name}}' ]; then ln -s ../../.. '{{build}}/repo/lz4-java-{{TAG}}'; else git clone --shared --branch='{{TAG}}' .. '{{build}}/repo/lz4-java-{{TAG}}'; fi + +template NAME TAG: (repo TAG) + #!/usr/bin/env -S uv run --script + # /// script + # dependencies = [ + # "semver", + # "mistune", + # "pygments", + # "Jinja2" + # ] + # /// + import semver + import mistune + import os + import pygments + import pygments.lexers + import pygments.formatters + from jinja2 import Environment, FileSystemLoader, select_autoescape + env = Environment(loader=FileSystemLoader("."), autoescape=True) + + semantic_versions = '{{all_versions}}'.split() + semantic_versions.sort(reverse=True, key=lambda v: semver.VersionInfo.parse(v[1:])) + + selected_version_actual = '{{TAG}}' if '{{TAG}}' != '{{latest_version_name}}' else '{{latest_version}}' + + html_formatter = pygments.formatters.HtmlFormatter(lineseparator="
") + class PygmentsRenderer(mistune.HTMLRenderer): + def block_code(self, code, info=None): + if info: + lang = info.split(None, 1)[0] + else: + lang = None + if lang: + return pygments.highlight(code, pygments.lexers.get_lexer_by_name(lang), html_formatter) + else: + return super().block_code(code, lang) + + try: + os.makedirs('{{build}}/templates/{{TAG}}') + except: + pass + with open('{{build}}/templates/{{TAG}}/{{ NAME }}', 'w') as f: + f.write(env.get_template("{{ NAME }}.jinja").render( + all_versions=semantic_versions, + latest_version='{{latest_version}}', + latest_version_name='{{latest_version_name}}', + selected_version='{{TAG}}', + selected_version_actual=selected_version_actual, + path_javadoc='{{path_javadoc}}', + readme=lambda: mistune.create_markdown(renderer=PygmentsRenderer())(open('{{build}}/repo/lz4-java-{{TAG}}/README.md').read()), + pygments_style=lambda: html_formatter.get_style_defs() + )) + +#[arg('TAG', pattern='v\d+\.\d+\.\d+')] +javadoc TAG: (template "header-javadoc.html" TAG) + header=$(cat '{{build}}/templates/{{TAG}}/header-javadoc.html') && cd '{{build}}/repo/lz4-java-{{TAG}}' && ./mvnw javadoc:javadoc "-Dheader=$header" + mkdir -p '{{build}}/site/{{TAG}}' + cp -rf '{{build}}/repo/lz4-java-{{TAG}}/target/site/apidocs' '{{build}}/site/{{TAG}}/{{path_javadoc}}' + +version TAG: (javadoc TAG) (template "index.html" TAG) + cp -f '{{build}}/templates/{{TAG}}/index.html' '{{build}}/site/{{TAG}}/index.html' + +rewrite-version-links: + #!/usr/bin/env -S uv run --script + # /// script + # /// + import pathlib + + root = pathlib.Path("target/site") + for p in root.glob("**/*.html"): + to_root = root.relative_to(p.parent, walk_up=True) + + html = p.read_text() + for v in ['{{latest_version_name}}'] + '{{all_versions}}'.split(): + # walk up to root, enter the new version, then walk back down to same path. + new_parts = [*to_root.parts, v, *p.relative_to(root).parts[1:]] + if new_parts[-1] == 'index.html': + new_parts[-1] = '' + html = html.replace('REWRITE_PATH_' + v, str(pathlib.Path(*new_parts))) + if '{{path_javadoc}}' in p.relative_to(root).parts: + html = html.replace('', '') + p.write_text(html) + +prepare: + rm -rf '{{build}}/site' + mkdir -p '{{build}}/site' + ln -s ../../javadoc.css ../../common.css ../../markdown.css '{{build}}/site' + +all: prepare (version latest_version_name) && rewrite-version-links + set -e; for v in {{all_versions}}; do just 'all_versions={{all_versions}}' 'latest_version={{latest_version}}' version "$v"; done diff --git a/docs/markdown.css b/docs/markdown.css new file mode 100644 index 0000000..915208e --- /dev/null +++ b/docs/markdown.css @@ -0,0 +1,38 @@ +#lz4-header .dropdown { + padding: 0; + margin: 0; + background: #ddd; +} + +body { + max-width: 80em; + font-family: sans-serif; + display: inline-block; + text-align: left; + padding-top: 3em; +} +html { + text-align: center; +} + +#lz4-header { + margin: 0; + padding: 0; + background: #ddd; + position: fixed; + max-width: 80em; + width: 100%; + top: 0; + text-align: right; +} +#lz4-header li { + display: inline-block; +} +#lz4-header li > span, #lz4-header li > a { + padding: 0.5em; + display: inline-block; +} +#lz4-header .outdated { + background-color: #aa0000; + color: #fff; +} \ No newline at end of file From 48f52da065a44a71f57a4a5ffae4ae71234fa1d1 Mon Sep 17 00:00:00 2001 From: yawkat Date: Tue, 16 Dec 2025 14:18:54 +0100 Subject: [PATCH 2/7] fix --- docs/justfile | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/justfile b/docs/justfile index da652df..0ef6e97 100644 --- a/docs/justfile +++ b/docs/justfile @@ -7,6 +7,7 @@ latest_version_name := "current" repo TAG: rm -rf '{{build}}/repo/lz4-java-{{TAG}}' + mkdir -p '{{build}}/repo' if [ '{{TAG}}' = '{{latest_version_name}}' ]; then ln -s ../../.. '{{build}}/repo/lz4-java-{{TAG}}'; else git clone --shared --branch='{{TAG}}' .. '{{build}}/repo/lz4-java-{{TAG}}'; fi template NAME TAG: (repo TAG) From 61f3c17ec79cb50d0e55252ccdfa551d1fc0edc2 Mon Sep 17 00:00:00 2001 From: yawkat Date: Tue, 16 Dec 2025 14:37:50 +0100 Subject: [PATCH 3/7] versioning --- .github/workflows/docs.yml | 9 +++++++++ docs/header.html.jinja | 8 +++++++- docs/justfile | 6 +++++- 3 files changed, 21 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0289ffa..5c9d2d6 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,6 +4,11 @@ on: release: types: [published] workflow_dispatch: + inputs: + selected_version: + description: 'Tag to associate with current working tree. If unset, `git describe` is used.' + type: string + required: false pull_request: # TODO jobs: @@ -25,7 +30,11 @@ jobs: uses: astral-sh/setup-uv@v7 - name: Install just run: sudo apt install -y just + - name: Build documentation (explicit selected version) + if: github.event_name == 'workflow_dispatch' && inputs.selected_version + run: cd docs && just latest_version=${{ inputs.selected_version }} all - name: Build documentation + if: github.event_name != 'workflow_dispatch' || !inputs.selected_version run: cd docs && just all - name: Upload pages artifact id: deployment diff --git a/docs/header.html.jinja b/docs/header.html.jinja index d4ccabb..da92182 100644 --- a/docs/header.html.jinja +++ b/docs/header.html.jinja @@ -6,8 +6,14 @@
  • Javadoc
  • GitHub
  • - {{ selected_version }} ▼ + {% if selected_version == latest_version_name %}{{ latest_version }} ({{ selected_version }}){% else %}{{ selected_version }}{% endif %} ▼
      + {% if latest_version not in all_versions %} +
    • + {% if latest_version_name == selected_version %}{{ latest_version }} (snapshot) + {% else %}{{ latest_version }} (snapshot){% endif %} +
      • + {% endif %} {% for v in all_versions %}
    • {% if v == selected_version %}{{ v }} diff --git a/docs/justfile b/docs/justfile index 0ef6e97..d3a4e3c 100644 --- a/docs/justfile +++ b/docs/justfile @@ -97,5 +97,9 @@ prepare: mkdir -p '{{build}}/site' ln -s ../../javadoc.css ../../common.css ../../markdown.css '{{build}}/site' -all: prepare (version latest_version_name) && rewrite-version-links +log: + @echo "Available tags: {{all_versions}}" + @echo "Current tag: {{latest_version}}" + +all: log prepare (version latest_version_name) && rewrite-version-links set -e; for v in {{all_versions}}; do just 'all_versions={{all_versions}}' 'latest_version={{latest_version}}' version "$v"; done From da65a0fb4ac3d0c5e8ecaecb74ee518a195cc874 Mon Sep 17 00:00:00 2001 From: yawkat Date: Tue, 16 Dec 2025 14:45:38 +0100 Subject: [PATCH 4/7] use cloudflare pages instead --- .github/workflows/docs.yml | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5c9d2d6..111d20d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -36,21 +36,20 @@ jobs: - name: Build documentation if: github.event_name != 'workflow_dispatch' || !inputs.selected_version run: cd docs && just all - - name: Upload pages artifact - id: deployment - uses: actions/upload-pages-artifact@v3 + - name: Publish + uses: cloudflare/wrangler-action@v3 + id: cf_publish with: - path: 'docs/target/site/' - deploy: - needs: build - permissions: - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + command: pages deploy docs/target/site/ --project-name=lz4-java-yawk-at + - name: Check PR + uses: 8BitJonny/gh-get-current-pr@3.0.0 + id: pr + - name: Comment on PR + if: steps.pr.outputs.pr_found + uses: thollander/actions-comment-pull-request@v3 + with: + message: ":rocket: Preview deployed to ${{steps.cf_publish.outputs.deployment-url}}" + comment-tag: deployment + pr-number: "${{steps.pr.outputs.number}}" From 110989a0ca4f14e98bc77aef7fe1bc65d2c965b1 Mon Sep 17 00:00:00 2001 From: yawkat Date: Tue, 16 Dec 2025 14:55:24 +0100 Subject: [PATCH 5/7] top-level redirect --- docs/_redirects | 1 + docs/justfile | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 docs/_redirects diff --git a/docs/_redirects b/docs/_redirects new file mode 100644 index 0000000..196d2ff --- /dev/null +++ b/docs/_redirects @@ -0,0 +1 @@ +/ /current/ 301 \ No newline at end of file diff --git a/docs/justfile b/docs/justfile index d3a4e3c..3f51395 100644 --- a/docs/justfile +++ b/docs/justfile @@ -95,7 +95,7 @@ rewrite-version-links: prepare: rm -rf '{{build}}/site' mkdir -p '{{build}}/site' - ln -s ../../javadoc.css ../../common.css ../../markdown.css '{{build}}/site' + ln -s ../../javadoc.css ../../common.css ../../markdown.css ../../_redirects '{{build}}/site' log: @echo "Available tags: {{all_versions}}" From ecee02a5047524d34231249792f7cc93d397f0f4 Mon Sep 17 00:00:00 2001 From: yawkat Date: Tue, 16 Dec 2025 15:04:42 +0100 Subject: [PATCH 6/7] update readme links --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e294811..773b17a 100644 --- a/README.md +++ b/README.md @@ -147,8 +147,8 @@ Prior to 1.8.1, there was also a lz4-pure-java artifact that excluded the JNI bi # Documentation - - [lz4](https://javadoc.io/doc/at.yawk.lz4/lz4-java/latest/org.lz4.java/net/jpountz/lz4/package-summary.html) - - [xxhash](https://javadoc.io/doc/at.yawk.lz4/lz4-java/latest/org.lz4.java/net/jpountz/xxhash/package-summary.html) + - [lz4](https://lz4-java.yawk.at/current/javadoc/net/jpountz/lz4/package-summary.html) + - [xxhash](https://lz4-java.yawk.at/current/javadoc/net/jpountz/xxhash/package-summary.html) - [changelog (versions <= 1.8.0)](https://github.com/yawkat/lz4-java/blob/main/CHANGES.md) - [changelog / GitHub releases (versions >= 1.8.1)](https://github.com/yawkat/lz4-java/releases) From 38cdb08c7ae0c4d00e5d511c98831b954f23da37 Mon Sep 17 00:00:00 2001 From: yawkat Date: Tue, 16 Dec 2025 15:05:03 +0100 Subject: [PATCH 7/7] disable pull_request trigger --- .github/workflows/docs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 111d20d..228aa0f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -9,7 +9,6 @@ on: description: 'Tag to associate with current working tree. If unset, `git describe` is used.' type: string required: false - pull_request: # TODO jobs: build: