Skip to content

Commit b8af362

Browse files
authored
github-pages documentation (#32)
* github-pages documentation * fix * versioning * use cloudflare pages instead * top-level redirect * update readme links * disable pull_request trigger
1 parent e3aa42c commit b8af362

File tree

10 files changed

+280
-2
lines changed

10 files changed

+280
-2
lines changed

.github/workflows/docs.yml

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Build Documentation
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
inputs:
8+
selected_version:
9+
description: 'Tag to associate with current working tree. If unset, `git describe` is used.'
10+
type: string
11+
required: false
12+
13+
jobs:
14+
build:
15+
name: Build documentation
16+
runs-on: ubuntu-latest
17+
steps:
18+
- name: Checkout
19+
uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
- name: Setup Temurin JDK 21
23+
uses: actions/setup-java@v5
24+
with:
25+
distribution: temurin
26+
java-version: '21'
27+
cache: maven
28+
- name: Install uv
29+
uses: astral-sh/setup-uv@v7
30+
- name: Install just
31+
run: sudo apt install -y just
32+
- name: Build documentation (explicit selected version)
33+
if: github.event_name == 'workflow_dispatch' && inputs.selected_version
34+
run: cd docs && just latest_version=${{ inputs.selected_version }} all
35+
- name: Build documentation
36+
if: github.event_name != 'workflow_dispatch' || !inputs.selected_version
37+
run: cd docs && just all
38+
- name: Publish
39+
uses: cloudflare/wrangler-action@v3
40+
id: cf_publish
41+
with:
42+
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
43+
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
44+
command: pages deploy docs/target/site/ --project-name=lz4-java-yawk-at
45+
- name: Check PR
46+
uses: 8BitJonny/[email protected]
47+
id: pr
48+
- name: Comment on PR
49+
if: steps.pr.outputs.pr_found
50+
uses: thollander/actions-comment-pull-request@v3
51+
with:
52+
message: ":rocket: Preview deployed to ${{steps.cf_publish.outputs.deployment-url}}"
53+
comment-tag: deployment
54+
pr-number: "${{steps.pr.outputs.number}}"

README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -147,8 +147,8 @@ Prior to 1.8.1, there was also a lz4-pure-java artifact that excluded the JNI bi
147147

148148
# Documentation
149149

150-
- [lz4](https://javadoc.io/doc/at.yawk.lz4/lz4-java/latest/org.lz4.java/net/jpountz/lz4/package-summary.html)
151-
- [xxhash](https://javadoc.io/doc/at.yawk.lz4/lz4-java/latest/org.lz4.java/net/jpountz/xxhash/package-summary.html)
150+
- [lz4](https://lz4-java.yawk.at/current/javadoc/net/jpountz/lz4/package-summary.html)
151+
- [xxhash](https://lz4-java.yawk.at/current/javadoc/net/jpountz/xxhash/package-summary.html)
152152
- [changelog (versions <= 1.8.0)](https://github.com/yawkat/lz4-java/blob/main/CHANGES.md)
153153
- [changelog / GitHub releases (versions >= 1.8.1)](https://github.com/yawkat/lz4-java/releases)
154154

docs/_redirects

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/ /current/ 301

docs/common.css

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#lz4-header .dropdown {
2+
position: absolute;
3+
display: none;
4+
width: auto;
5+
right: 0;
6+
}
7+
#lz4-header:hover .dropdown {
8+
display: block;
9+
}
10+
#lz4-header .dropdown li {
11+
display: block;
12+
float: left;
13+
clear: both;
14+
}
15+
#lz4-header .selected {
16+
font-weight: bold;
17+
}

docs/header-javadoc.html.jinja

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{% set version_root = '{@docroot}/..' %}{% include "header.html.jinja" %}

docs/header.html.jinja

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<ul id="lz4-header" class="nav-list">
2+
{% if selected_version != latest_version_name and selected_version != latest_version %}
3+
<li class="outdated"><span>Outdated Version!</span></li>
4+
{% endif %}
5+
<li><a href="{{ version_root }}">Readme</a></li>
6+
<li><a href="{{ version_root }}/{{ path_javadoc }}">Javadoc</a></li>
7+
<li><a href="https://github.com/yawkat/lz4-java{% if selected_version != latest_version_name %}/releases/tag/{{ selected_version_actual }}{% endif %}">GitHub</a></li>
8+
<li>
9+
<span>{% if selected_version == latest_version_name %}{{ latest_version }} ({{ selected_version }}){% else %}{{ selected_version }}{% endif %} ▼</span>
10+
<ul class="dropdown">
11+
{% if latest_version not in all_versions %}
12+
<li>
13+
{% if latest_version_name == selected_version %}<span class="selected">{{ latest_version }} (snapshot)</span>
14+
{% else %}<a href="REWRITE_PATH_{{ latest_version_name }}">{{ latest_version }} (snapshot)</a>{% endif %}
15+
</li>
16+
{% endif %}
17+
{% for v in all_versions %}
18+
<li>
19+
{% if v == selected_version %}<span class="selected">{{ v }}</span>
20+
{% else %}<a href="REWRITE_PATH_{{ v }}">{{ v }}</a>{% endif %}
21+
22+
{% if v == latest_version %}
23+
{% if latest_version_name == selected_version %}(<span class="selected">{{ latest_version_name }}</span>)
24+
{% else %}(<a href="REWRITE_PATH_{{ latest_version_name }}">{{ latest_version_name }}</a>){% endif %}
25+
{% endif %}
26+
</li>
27+
{% endfor %}
28+
</ul>
29+
</li>
30+
</ul>

docs/index.html.jinja

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<title>lz4-java {% if selected_version == latest_version_name %}{{ latest_version }}{% else %}{{ selected_version }}{% endif %}</title>
7+
<link rel="stylesheet" href="../common.css"/>
8+
<link rel="stylesheet" href="../markdown.css"/>
9+
<style>{{ pygments_style() }}</style>
10+
</head>
11+
<body>
12+
{% set version_root = '.' %}
13+
{% include "header.html.jinja" %}
14+
{{ readme()|safe }}
15+
</body>
16+
</html>

docs/javadoc.css

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#lz4-header .dropdown {
2+
background: var(--navbar-background-color);
3+
z-index: 9999;
4+
margin: 0;
5+
padding: 1em 0 0 0;
6+
}
7+
.about-language {
8+
padding: 0 !important;
9+
margin-top: 0 !important;
10+
font-size: inherit !important;
11+
height: auto !important;
12+
}
13+
#lz4-header .outdated {
14+
background-color: var(--selected-background-color);
15+
color: var(--selected-text-color);
16+
}

docs/justfile

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
all_versions := `git tag --list 'v*' | tr '\n' ' '`
2+
latest_version := `git describe --tags --match='v*'`
3+
4+
build := "target"
5+
path_javadoc := "javadoc"
6+
latest_version_name := "current"
7+
8+
repo TAG:
9+
rm -rf '{{build}}/repo/lz4-java-{{TAG}}'
10+
mkdir -p '{{build}}/repo'
11+
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
12+
13+
template NAME TAG: (repo TAG)
14+
#!/usr/bin/env -S uv run --script
15+
# /// script
16+
# dependencies = [
17+
# "semver",
18+
# "mistune",
19+
# "pygments",
20+
# "Jinja2"
21+
# ]
22+
# ///
23+
import semver
24+
import mistune
25+
import os
26+
import pygments
27+
import pygments.lexers
28+
import pygments.formatters
29+
from jinja2 import Environment, FileSystemLoader, select_autoescape
30+
env = Environment(loader=FileSystemLoader("."), autoescape=True)
31+
32+
semantic_versions = '{{all_versions}}'.split()
33+
semantic_versions.sort(reverse=True, key=lambda v: semver.VersionInfo.parse(v[1:]))
34+
35+
selected_version_actual = '{{TAG}}' if '{{TAG}}' != '{{latest_version_name}}' else '{{latest_version}}'
36+
37+
html_formatter = pygments.formatters.HtmlFormatter(lineseparator="<br>")
38+
class PygmentsRenderer(mistune.HTMLRenderer):
39+
def block_code(self, code, info=None):
40+
if info:
41+
lang = info.split(None, 1)[0]
42+
else:
43+
lang = None
44+
if lang:
45+
return pygments.highlight(code, pygments.lexers.get_lexer_by_name(lang), html_formatter)
46+
else:
47+
return super().block_code(code, lang)
48+
49+
try:
50+
os.makedirs('{{build}}/templates/{{TAG}}')
51+
except:
52+
pass
53+
with open('{{build}}/templates/{{TAG}}/{{ NAME }}', 'w') as f:
54+
f.write(env.get_template("{{ NAME }}.jinja").render(
55+
all_versions=semantic_versions,
56+
latest_version='{{latest_version}}',
57+
latest_version_name='{{latest_version_name}}',
58+
selected_version='{{TAG}}',
59+
selected_version_actual=selected_version_actual,
60+
path_javadoc='{{path_javadoc}}',
61+
readme=lambda: mistune.create_markdown(renderer=PygmentsRenderer())(open('{{build}}/repo/lz4-java-{{TAG}}/README.md').read()),
62+
pygments_style=lambda: html_formatter.get_style_defs()
63+
))
64+
65+
#[arg('TAG', pattern='v\d+\.\d+\.\d+')]
66+
javadoc TAG: (template "header-javadoc.html" TAG)
67+
header=$(cat '{{build}}/templates/{{TAG}}/header-javadoc.html') && cd '{{build}}/repo/lz4-java-{{TAG}}' && ./mvnw javadoc:javadoc "-Dheader=$header"
68+
mkdir -p '{{build}}/site/{{TAG}}'
69+
cp -rf '{{build}}/repo/lz4-java-{{TAG}}/target/site/apidocs' '{{build}}/site/{{TAG}}/{{path_javadoc}}'
70+
71+
version TAG: (javadoc TAG) (template "index.html" TAG)
72+
cp -f '{{build}}/templates/{{TAG}}/index.html' '{{build}}/site/{{TAG}}/index.html'
73+
74+
rewrite-version-links:
75+
#!/usr/bin/env -S uv run --script
76+
# /// script
77+
# ///
78+
import pathlib
79+
80+
root = pathlib.Path("target/site")
81+
for p in root.glob("**/*.html"):
82+
to_root = root.relative_to(p.parent, walk_up=True)
83+
84+
html = p.read_text()
85+
for v in ['{{latest_version_name}}'] + '{{all_versions}}'.split():
86+
# walk up to root, enter the new version, then walk back down to same path.
87+
new_parts = [*to_root.parts, v, *p.relative_to(root).parts[1:]]
88+
if new_parts[-1] == 'index.html':
89+
new_parts[-1] = ''
90+
html = html.replace('REWRITE_PATH_' + v, str(pathlib.Path(*new_parts)))
91+
if '{{path_javadoc}}' in p.relative_to(root).parts:
92+
html = html.replace('</title>', '</title><link rel="stylesheet" href="' + str(to_root) + '/common.css"><link rel="stylesheet" href="' + str(to_root) + '/javadoc.css">')
93+
p.write_text(html)
94+
95+
prepare:
96+
rm -rf '{{build}}/site'
97+
mkdir -p '{{build}}/site'
98+
ln -s ../../javadoc.css ../../common.css ../../markdown.css ../../_redirects '{{build}}/site'
99+
100+
log:
101+
@echo "Available tags: {{all_versions}}"
102+
@echo "Current tag: {{latest_version}}"
103+
104+
all: log prepare (version latest_version_name) && rewrite-version-links
105+
set -e; for v in {{all_versions}}; do just 'all_versions={{all_versions}}' 'latest_version={{latest_version}}' version "$v"; done

docs/markdown.css

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
#lz4-header .dropdown {
2+
padding: 0;
3+
margin: 0;
4+
background: #ddd;
5+
}
6+
7+
body {
8+
max-width: 80em;
9+
font-family: sans-serif;
10+
display: inline-block;
11+
text-align: left;
12+
padding-top: 3em;
13+
}
14+
html {
15+
text-align: center;
16+
}
17+
18+
#lz4-header {
19+
margin: 0;
20+
padding: 0;
21+
background: #ddd;
22+
position: fixed;
23+
max-width: 80em;
24+
width: 100%;
25+
top: 0;
26+
text-align: right;
27+
}
28+
#lz4-header li {
29+
display: inline-block;
30+
}
31+
#lz4-header li > span, #lz4-header li > a {
32+
padding: 0.5em;
33+
display: inline-block;
34+
}
35+
#lz4-header .outdated {
36+
background-color: #aa0000;
37+
color: #fff;
38+
}

0 commit comments

Comments
 (0)