Skip to content

Commit 4ce1d5d

Browse files
leerholeerho
committed
Rewrite Readme, Update javadoc.yml
1 parent 337b342 commit 4ce1d5d

File tree

2 files changed

+186
-42
lines changed

2 files changed

+186
-42
lines changed

‎.github/workflows/javadoc.yml‎

Lines changed: 180 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,201 @@
1-
name: JavaDoc
1+
name: JavaDoc Releases
22

33
on:
44
push:
5-
branches: main
5+
tags:
6+
- "*" # Only publish docs for tags
7+
delete:
8+
tags:
9+
- "*" # Auto-remove docs when tags are deleted
610
workflow_dispatch:
711

812
permissions:
913
contents: write
14+
pages: write
15+
id-token: write
1016

1117
jobs:
12-
javadoc:
18+
build:
19+
name: Build JavaDoc
1320
runs-on: ubuntu-latest
1421

1522
steps:
16-
- name: Checkout
23+
- name: Checkout source
1724
uses: actions/checkout@v5
1825

19-
- name: Setup Java
26+
- name: Set up JDK
2027
uses: actions/setup-java@v5
2128
with:
22-
java-version: '25'
23-
distribution: 'temurin'
29+
distribution: temurin
30+
java-version: 25
2431

25-
- name: Echo Java Version
26-
run: java -version
32+
- name: Set up Maven cache
33+
uses: actions/cache@v4
34+
with:
35+
path: |
36+
~/.m2/repository
37+
key: maven-${{ runner.os }}-${{ hashFiles('**/pom.xml') }}
38+
restore-keys: |
39+
maven-${{ runner.os }}-
40+
41+
- name: Build JavaDoc
42+
run: mvn -B javadoc:javadoc
43+
44+
# Upload for GitHub Pages preview (this is optional)
45+
- name: Upload Pages Artifact
46+
uses: actions/upload-pages-artifact@v4
47+
with:
48+
path: target/site/apidocs
49+
50+
update-gh-pages:
51+
name: Update gh-pages
52+
needs: build
53+
runs-on: ubuntu-latest
54+
55+
if: github.event_name != 'delete' # skip this job on delete events
56+
57+
steps:
58+
- name: Checkout gh-pages branch
59+
uses: actions/checkout@v5
60+
with:
61+
ref: gh-pages
62+
path: gh-pages
63+
64+
- name: Copy Javadoc into versioned folder
65+
run: |
66+
TAG="${GITHUB_REF_NAME}"
67+
VERSION_DIR="docs/${TAG}"
68+
69+
rm -rf "gh-pages/${VERSION_DIR}"
70+
mkdir -p "gh-pages/${VERSION_DIR}"
71+
cp -r target/site/apidocs/* "gh-pages/${VERSION_DIR}/"
72+
73+
- name: Regenerate multi-version index.html
74+
run: |
75+
cd gh-pages
76+
77+
# Create index header
78+
cat > index.html << 'EOF'
79+
<!DOCTYPE html>
80+
<html>
81+
<head>
82+
<meta charset="UTF-8"/>
83+
<title>Javadoc Versions</title>
84+
<style>
85+
body { font-family: Arial; padding: 2rem; max-width: 800px; margin: auto; }
86+
h1 { font-size: 2rem; }
87+
ul { line-height: 1.8; font-size: 1.1rem; }
88+
</style>
89+
</head>
90+
<body>
91+
<h1>Available Javadoc Versions</h1>
92+
<ul>
93+
EOF
94+
95+
# Insert entries for each version directory
96+
for dir in docs/*; do
97+
[ -d "$dir" ] || continue
98+
ver=$(basename "$dir")
99+
echo "<li><a href=\"docs/$ver/\">$ver</a></li>" >> index.html
100+
done
27101
28-
- name: Print Current workflow
29-
run: >
30-
cat .github/workflows/javadoc.yml
102+
# Close HTML
103+
cat >> index.html << 'EOF'
104+
</ul>
105+
</body>
106+
</html>
107+
EOF
31108
32-
- name: Generate JavaDoc
33-
run: mvn javadoc:javadoc
109+
- name: Commit & push changes
110+
run: |
111+
cd gh-pages
112+
git config user.email "github-actions[bot]@users.noreply.github.com"
113+
git config user.name "github-actions[bot]"
34114
35-
- name: Deploy JavaDoc
36-
uses: JamesIves/github-pages-deploy-action@881db5376404c5c8d621010bcbec0310b58d5e29
115+
if git diff --quiet; then
116+
echo "No changes to commit"
117+
exit 0
118+
fi
119+
120+
git add .
121+
git commit -m "Update release Javadoc for ${GITHUB_REF_NAME}"
122+
git push origin gh-pages
123+
124+
delete-tag-docs:
125+
name: Remove deleted tag docs
126+
runs-on: ubuntu-latest
127+
128+
if: github.event_name == 'delete' && github.event.ref_type == 'tag'
129+
130+
steps:
131+
- name: Checkout gh-pages
132+
uses: actions/checkout@v5
37133
with:
38-
token: ${{ secrets.GITHUB_TOKEN }}
39-
folder: target/reports/apidocs
40-
target-folder: docs/${{ github.ref_name }}
41-
branch: gh-pages
134+
ref: gh-pages
135+
path: gh-pages
136+
137+
- name: Remove documentation for deleted tag
138+
run: |
139+
TAG="${GITHUB_REF_NAME}"
140+
VERSION_DIR="docs/${TAG}"
141+
rm -rf "gh-pages/${VERSION_DIR}"
142+
143+
- name: Rebuild index.html
144+
run: |
145+
cd gh-pages
146+
147+
# Regenerate index.html (same as above)
148+
cat > index.html << 'EOF'
149+
<!DOCTYPE html>
150+
<html>
151+
<head>
152+
<meta charset="UTF-8"/>
153+
<title>Javadoc Versions</title>
154+
<style>
155+
body { font-family: Arial; padding: 2rem; max-width: 800px; margin: auto; }
156+
h1 { font-size: 2rem; }
157+
ul { line-height: 1.8; font-size: 1.1rem; }
158+
</style>
159+
</head>
160+
<body>
161+
<h1>Available Javadoc Versions</h1>
162+
<ul>
163+
EOF
164+
165+
for dir in docs/*; do
166+
[ -d "$dir" ] || continue
167+
ver=$(basename "$dir")
168+
echo "<li><a href=\"docs/$ver/\">$ver</a></li>" >> index.html
169+
done
170+
171+
cat >> index.html << 'EOF'
172+
</ul>
173+
</body>
174+
</html>
175+
EOF
176+
177+
- name: Commit & push removal
178+
run: |
179+
cd gh-pages
180+
git config user.email "github-actions[bot]@users.noreply.github.com"
181+
git config user.name "github-actions[bot]"
182+
183+
if git diff --quiet; then
184+
echo "No changes to commit"
185+
exit 0
186+
fi
187+
188+
git add .
189+
git commit -m "Remove Javadoc for deleted tag ${GITHUB_REF_NAME}"
190+
git push origin gh-pages
191+
192+
# Summary of Features
193+
# Multi-version docs (docs/<tag>/)
194+
# Auto-generated index.html
195+
# Only publish for tags
196+
# Delete docs when tags are deleted
197+
# Upload Pages artifact
198+
# Maven dependency caching
199+
# No third-party actions
200+
# No force-push
201+
# Clean HTML layout

‎README.md‎

Lines changed: 6 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ This is the core Java component of the DataSketches library. It contains all of
2727

2828
This component is also a dependency of other components of the library that create adaptors for target systems, such as the [Apache Pig adaptor](https://github.com/apache/datasketches-pig), the [Apache Hive adaptor](https://github.com/apache/datasketches-hive), and others.
2929

30-
Note that we have parallel core components for C++, Python and GO implementations of many of the same sketch algorithms:
30+
Note that we have parallel core library components for C++, Python and GO implementations of many of the same sketch algorithms:
3131

3232
- [datasketches-cpp](https://github.com/apache/datasketches-cpp),
3333
- [datasketches-python](https://github.com/apache/datasketches-python),
@@ -37,26 +37,6 @@ Please visit the main [DataSketches website](https://datasketches.apache.org) fo
3737

3838
If you are interested in making contributions to this site please see our [Community](https://datasketches.apache.org/docs/Community/) page for how to contact us.
3939

40-
---
41-
## Major Changes with this Release
42-
This release is a major release where we took the opportunity to do some significant refactoring that will constitute incompatible changes from previous releases. Any incompatibility with prior releases is always an inconvenience to users who wish to just upgrade to the latest release and run. However, some of the code in this library was written in 2013 and meanwhile the Java language has evolved enormously since then. We chose to use this major release as the opportunity to modernize some of the code to achieve the following goals:
43-
44-
### Eliminate the dependency on the DataSketches-Memory component.
45-
The DataSketches-Memory component was originally developed in 2014 to address the need for fast access to off-heap memory data structures and used Unsafe and other JVM internals as there were no satisfactory Java language features to do this at the time.
46-
47-
The FFM capabilities introduced into the language in Java 22, are now part of the Java 25 LTS release, which we support. Since the capabilities of FFM are a superset of the original DataSketches-Memory component, it made sense to rewrite the code to eliminate the dependency on DataSketches-Memory and use FFM instead. This impacted code across the entire library.
48-
49-
This provided several advantages to the code base. By removing this dependency on DataSketches-Memory, there are now no runtime dependencies! This should make integrating this library into other Java systems much simpler. Since FFM is tightly integrated into the Java language, it has improved performance, especially with bulk operations.
50-
51-
- As an added note: There are numerous other improvements to the Java language that we could perhaps take advantage of in a rewrite, e.g., Records, text blocks, switch expressions, sealed, var, modules, patterns, etc. However, faced with the risk of accidentally creating bugs due to too many changes at one time, we focused on FFM, which actually improve performance as opposed to just syntactic sugar.
52-
53-
### Align public sketch class names so that the sketch family name is part of the class name.
54-
For example, the Theta sketch was the first sketch written for the library and its base class was called *Sketch*. Obviously, because it was the only sketch! The Tuple sketch evolved soon after and its base class was also called *Sketch*. Oops, bad idea. If a user wanted to use both the Theta and Tuple sketches in the same class one of them had to be fully qualified every time it was referenced. Ugh!
55-
56-
Unfortunately, this habit propagated so some of the other early sketches where we ended up with two different sketches with a *ItemsSketch*, for example. For the more recent additions to the library we started including the sketch family name in all the relevant sketch-like public classes of a sketch family.
57-
58-
In this release we have refactored these older sketches with new names that now include the sketch family name. Yes, this is an incompatible change for user code moving from earlier releases, but this can be usually fixed with search-and-replace tools. This release is not perfect, but hopefully more consistent across all the different sketch families.
59-
6040

6141
## Build & Runtime Dependencies
6242

@@ -73,7 +53,7 @@ This DataSketches component is structured as a Maven project and Maven is the re
7353
#### A Toolchain is required
7454

7555
* You must have a JDK type toolchain defined in location *~/.m2/toolchains.xml* that specifies where to find a locally installed OpenJDK-compatible version 25.
76-
* Your default \$JAVA\_HOME compiler must be OpenJDK compatible, specified in the toolchain, and may be a version greater than 25. Note that if your \$JAVA\_HOME is set to a Java version greater than 25, Maven will automatically use the Java 25 version specified in the toolchain instead. The included pom.xml specifies the necessary JVM flags, if required, so no further action is needed.
56+
* Your default \$JAVA\_HOME compiler must be OpenJDK compatible, specified in the toolchain, and may be a version greater than 25. Note that if your \$JAVA\_HOME is set to a Java version greater than 25, Maven will automatically use the Java 25 version specified in the toolchain instead. The pom.xml specifies any necessary JVM flags, if required, so no further action is needed.
7757
* Note that the paths specified in the toolchain must be fully qualified direct paths to the OpenJDK version locations. Using environment variables will not work.
7858

7959
#### To run normal unit tests:
@@ -98,3 +78,7 @@ This will create the following jars:
9878

9979
* Make sure you configure SpotBugs with the /tools/FindBugsExcludeFilter.xml file. Otherwise, you may get a lot of false positive or low risk issues that we have examined and eliminated with this exclusion file.
10080

81+
### Checkstyle
82+
83+
* At the time of this writing, Checkstyle had not been upgraded to handle Java 25 features.
84+

0 commit comments

Comments
 (0)