Skip to content

Documentation page and GitHub action #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SiyaoIsHiding merged 1 commit into from
Dec 17, 2025
Merged

Documentation page and GitHub action #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 0 additions & 60 deletions .github/workflows/build-docs-gh-pages.yml
View file
Open in desktop

This file was deleted.

105 changes: 105 additions & 0 deletions .github/workflows/publish-docs-gp-pages.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
name: publish-docs-gp-pages
Copy link

Copilot AI Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The workflow name 'publish-docs-gp-pages' uses inconsistent naming conventions. It should either use spaces like 'Publish docs to gh-pages' for display purposes, or maintain the hyphenated format but spell out 'gh-pages' instead of 'gp-pages'.

Suggested change
name: publish-docs-gp-pages
name: Publish docs to gh-pages

Copilot uses AI. Check for mistakes.

on:
# TODO: Can we trigger action manually?
# push:
# branches:
# - 4.x
Comment on lines +4 to +7
Copy link

Copilot AI Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The TODO comment is unnecessary since workflow_dispatch on line 8 already enables manual triggering. The commented-out push trigger should either be uncommented if automatic triggering on push to 4.x is desired, or removed entirely along with the TODO.

Suggested change
# TODO: Can we trigger action manually?
# push:
# branches:
# - 4.x

Copilot uses AI. Check for mistakes.
workflow_dispatch:

jobs:
build-docs:
runs-on: ubuntu-latest
permissions:
contents: write

steps:
# 1. Checkout doc branch
- name: Checkout current branch
uses: actions/checkout@v4
with:
path: java-driver

# 2. Java 8
- name: Set up Java 8
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "8"
cache: maven

# 3. Python 3.10.19 + MkDocs + plugins
- name: Set up Python 3.10.19
uses: actions/setup-python@v5
with:
python-version: "3.10.19"

- name: Install MkDocs dependencies
run: |
python -m pip install --upgrade pip
pip install \
mkdocs \
mkdocs-material \
mkdocs-awesome-pages-plugin \
mkdocs-macros-plugin \
mike

# 4. Build docs via build-doc.sh
- name: Build documentation
working-directory: java-driver
run: |
chmod +x ./build-doc.sh
./build-doc.sh

# 5. Checkout gh-pages branch
- name: Checkout GH pages branch
uses: actions/checkout@v4
with:
ref: gh-pages
path: gh-pages

- name: Copy and version documentation
working-directory: gh-pages
run: |
git config --global user.email "gha@cassandra.apache.org"
git config --global user.name "GHA for Apache Cassandra Website"

cd ../java-driver
# lookup current project version
release_version=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout | cut -d- -f1)
# update links to contain version prefix
mike deploy --update-aliases $release_version
# copy documentation web page folder
cd ../gh-pages
cp -r ../java-driver/docs ./
rm -rf $release_version
mv docs $release_version

# update latest symlink
rm latest
ln -s $release_version latest

# remove latest tag
sed -i 's/\"latest\"//g' versions.json
# remove already present line if exists
sed -i '/'"$release_version"'/d' versions.json
# insert new version at the beginning
sed -i '2s/^/ { "version": "'"$release_version"'", "title": "'"$release_version"'", "aliases": ["latest"] },\'$'\n/g' versions.json

Comment on lines +82 to +88
Copy link

Copilot AI Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sed command is complex and fragile with nested quotes and escape sequences. Consider using a more maintainable approach such as jq for JSON manipulation or a Python script to modify versions.json, which would be more readable and less error-prone.

Suggested change
# remove latest tag
sed -i 's/\"latest\"//g' versions.json
# remove already present line if exists
sed -i '/'"$release_version"'/d' versions.json
# insert new version at the beginning
sed -i '2s/^/ { "version": "'"$release_version"'", "title": "'"$release_version"'", "aliases": ["latest"] },\'$'\n/g' versions.json
# update versions.json: remove any existing "latest" aliases and existing entry for this
# release_version, then insert the new version as the first entry with aliases ["latest"].
python - << PY
import json
from pathlib import Path
versions_path = Path("versions.json")
data = json.loads(versions_path.read_text())
release_version = "${release_version}"
# Remove "latest" from aliases in all existing entries
for entry in data:
aliases = entry.get("aliases")
if isinstance(aliases, list):
entry["aliases"] = [alias for alias in aliases if alias != "latest"]
# Remove any existing entry for this release_version
data = [entry for entry in data if entry.get("version") != release_version]
# Insert new version at the beginning
data.insert(0, {
"version": release_version,
"title": release_version,
"aliases": ["latest"],
})
versions_path.write_text(json.dumps(data, indent=2) + "\n")
PY

Copilot uses AI. Check for mistakes.
echo "release_version=$release_version" >> "$GITHUB_ENV"

- name: Commit and push documentation
working-directory: gh-pages
run: |
git config --global user.email "gha@cassandra.apache.org"
git config --global user.name "GHA for Apache Cassandra Website"

git add .

if git diff --cached --quiet; then
echo "No changes to push to gh-pages"
exit 0
fi

git commit -m "Update generated docs for release ${release_version}"
git push origin gh-pages
81 changes: 0 additions & 81 deletions .github/workflows/update-docs-staging.yml
View file
Open in desktop

This file was deleted.

Binary file added faq/favicon.ico
View file
Open in desktop
Binary file not shown.
Binary file added faq/logo.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
20 changes: 13 additions & 7 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,12 @@ site_dir: docs

theme:
name: material
palette:
- scheme: default
primary: blue
accent: blue
logo: faq/logo.png
favicon: faq/favicon.ico
features:
- navigation.tabs
- navigation.sections
- navigation.top
- navigation.path
- search.highlight
- search.share

Expand All @@ -26,6 +24,7 @@ markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed
- toc:
toc_depth: 1
permalink: true

nav:
Expand All @@ -39,8 +38,8 @@ nav:
- Overview: manual/core/README.md
- Integration: manual/core/integration/README.md
- Configuration:
- Overview: manual/core/configuration/README.md
- Reference: manual/core/configuration/reference/README.md
- Overview: manual/core/configuration/README.md
- Reference: manual/core/configuration/reference/README.md
- Authentication: manual/core/authentication/README.md
- SSL: manual/core/ssl/README.md
- Load Balancing: manual/core/load_balancing/README.md
Expand Down Expand Up @@ -162,3 +161,10 @@ plugins:
- search
- awesome-pages
- macros
- mike:
alias_type: copy

extra:
generator: false
version:
provider: mike
Copy link
Copy Markdown
Owner

@SiyaoIsHiding SiyaoIsHiding Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice!