github-pages documentation

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Build Documentation
+
+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
+
+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 (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: Publish
+        uses: cloudflare/wrangler-action@v3
+        id: cf_publish
+        with:
+          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}}"

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)
 

docs/_redirects

@@ -0,0 +1 @@
+/ /current/ 301

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;
+}

docs/header-javadoc.html.jinja

@@ -0,0 +1 @@
+{% set version_root = '{@docroot}/..' %}{% include "header.html.jinja" %}

docs/header.html.jinja

@@ -0,0 +1,30 @@
+<ul id="lz4-header" class="nav-list">
+  {% if selected_version != latest_version_name and selected_version != latest_version %}
+    <li class="outdated"><span>Outdated Version!</span></li>
+  {% endif %}
+  <li><a href="{{ version_root }}">Readme</a></li>
+  <li><a href="{{ version_root }}/{{ path_javadoc }}">Javadoc</a></li>
+  <li><a href="https://github.com/yawkat/lz4-java{% if selected_version != latest_version_name %}/releases/tag/{{ selected_version_actual }}{% endif %}">GitHub</a></li>
+  <li>
+    <span>{% if selected_version == latest_version_name %}{{ latest_version }} ({{ selected_version }}){% else %}{{ selected_version }}{% endif %} ▼</span>
+    <ul class="dropdown">
+      {% if latest_version not in all_versions %}
+        <li>
+          {% if latest_version_name == selected_version %}<span class="selected">{{ latest_version }} (snapshot)</span>
+          {% else %}<a href="REWRITE_PATH_{{ latest_version_name }}">{{ latest_version }} (snapshot)</a>{% endif %}
+        </li>
+      {% endif %}
+      {% for v in all_versions %}
+        <li>
+          {% if v == selected_version %}<span class="selected">{{ v }}</span>
+          {% else %}<a href="REWRITE_PATH_{{ v }}">{{ v }}</a>{% endif %}
+
+          {% if v == latest_version %}
+            {% if latest_version_name == selected_version %}(<span class="selected">{{ latest_version_name }}</span>)
+            {% else %}(<a href="REWRITE_PATH_{{ latest_version_name }}">{{ latest_version_name }}</a>){% endif %}
+          {% endif %}
+        </li>
+      {% endfor %}
+    </ul>
+  </li>
+</ul>

docs/index.html.jinja

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>lz4-java {% if selected_version == latest_version_name %}{{ latest_version }}{% else %}{{ selected_version }}{% endif %}</title>
+  <link rel="stylesheet" href="../common.css"/>
+  <link rel="stylesheet" href="../markdown.css"/>
+  <style>{{ pygments_style() }}</style>
+</head>
+<body>
+  {% set version_root = '.' %}
+  {% include "header.html.jinja" %}
+  {{ readme()|safe }}
+</body>
+</html>

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);
+}

docs/justfile

@@ -0,0 +1,105 @@
+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}}'
+  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)
+  #!/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="<br>")
+  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('</title>', '</title><link rel="stylesheet" href="' + str(to_root) + '/common.css"><link rel="stylesheet" href="' + str(to_root) + '/javadoc.css">')
+    p.write_text(html)
+
+prepare:
+  rm -rf '{{build}}/site'
+  mkdir -p '{{build}}/site'
+  ln -s ../../javadoc.css ../../common.css ../../markdown.css ../../_redirects '{{build}}/site'
+
+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

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;
+}