Re: [PR] Site redesign: modern responsive docs theme and tooling [openjpa-site]

[solomax (via GitHub) via dev]

solomax commented on code in PR #8:
URL: https://github.com/apache/openjpa-site/pull/8#discussion_r4488230670


##########
theme/apache/templates/base.html:
##########
@@ -15,276 +15,156 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
-<html lang="en" data-bs-theme="auto">
-    <head>
-        {% block head %}
-        <meta charset="utf-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1, 
shrink-to-fit=no">
-        <title>{{ SITENAME }} - {{ page.title }}</title>
-        {% endblock %}
+<html lang="en" data-bs-theme="light">
+<head>
+    {% block head %}
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, 
shrink-to-fit=no">
+    <title>{{ SITENAME }}{% if page and page.title and page.title != SITENAME 
%} - {{ page.title }}{% endif %}</title>
+    <meta name="description" content="{% if page and page.summary %}{{ 
page.summary|striptags }}{% else %}Apache OpenJPA is an open source Java 
persistence (JPA) project at The Apache Software Foundation.{% endif %}">
+    {% endblock %}
 
-        <!-- Start favicon styles - use apache feather -->
-        <link rel="shortcut icon" 
href="https://www.apache.org/favicons/favicon.ico";>
-        <link rel="apple-touch-icon" sizes="57x57" 
href="https://www.apache.org/favicons/apple-touch-icon-57x57.png";>
-        <link rel="apple-touch-icon" sizes="60x60" 
href="https://www.apache.org/favicons/apple-touch-icon-60x60.png";>
-        <link rel="apple-touch-icon" sizes="72x72" 
href="https://www.apache.org/favicons/apple-touch-icon-72x72.png";>
-        <link rel="apple-touch-icon" sizes="76x76" 
href="https://www.apache.org/favicons/apple-touch-icon-76x76.png";>
-        <link rel="apple-touch-icon" sizes="114x114" 
href="https://www.apache.org/favicons/apple-touch-icon-114x114.png";>
-        <link rel="apple-touch-icon" sizes="120x120" 
href="https://www.apache.org/favicons/apple-touch-icon-120x120.png";>
-        <link rel="apple-touch-icon" sizes="144x144" 
href="https://www.apache.org/favicons/apple-touch-icon-144x144.png";>
-        <link rel="apple-touch-icon" sizes="152x152" 
href="https://www.apache.org/favicons/apple-touch-icon-152x152.png";>
-        <link rel="apple-touch-icon" sizes="180x180" 
href="https://www.apache.org/favicons/apple-touch-icon-180x180.png";>
-        <link rel="icon" type="image/png" 
href="https://www.apache.org/favicons/favicon-32x32.png"; sizes="32x32">
-        <link rel="icon" type="image/png" 
href="https://www.apache.org/favicons/favicon-194x194.png"; sizes="194x194">
-        <link rel="icon" type="image/png" 
href="https://www.apache.org/favicons/favicon-96x96.png"; sizes="96x96">
-        <link rel="icon" type="image/png" 
href="https://www.apache.org/favicons/android-chrome-192x192.png"; 
sizes="192x192">
-        <link rel="icon" type="image/png" 
href="https://www.apache.org/favicons/favicon-16x16.png"; sizes="16x16">
-        <meta name="msapplication-TileColor" content="#603cba">
-        <meta name="msapplication-TileImage" 
content="https://www.apache.org/favicons/mstile-144x144.png";>
-        <meta name="msapplication-config" 
content="https://www.apache.org/favicons/browserconfig.xml";>
-        <meta name="theme-color" content="#282661">
-        <!-- End favicon styles - use apache feather -->
+    <!-- Favicons -->
+    <link rel="shortcut icon" href="/favicon.ico">

Review Comment:
   ```suggestion
       <link rel="shortcut icon" href="favicon.ico">
   ```
   
   We have plain site (no nested folders)
   Could you please make these paths relative
   otherwise it looks like this: https://nightlies.apache.org/openjpa/ :(



##########
.gitignore:
##########
@@ -1,5 +1,100 @@
+# ============================================================================
+# Apache OpenJPA Project .gitignore
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+
+# Dependencies lock files - keep these for reproducible builds
+package-lock.json
+
+# Node modules - always excluded
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build output directories - excluded from repo
+output/
+dist/
+
+# Generated static assets - NOT committed to repo, generated during build
+# These are created from npm packages during CI/CD build
+theme/apache/static/css/bootstrap.min.css

Review Comment:
   Maybe it would be possible to generate `static` content in some "outside" 
folder?
   I would prefer to have sources clean :)
   
   BTW it is enough to specify one line only `theme/apache/static` :)



##########
README.md:
##########
@@ -1,13 +1,166 @@
-# Pelican ASF Website
+# Apache OpenJPA Documentation Site
 
-See [ASF-Pelican](https://infra.apache.org/asf-pelican.html)
+This repository contains the documentation for Apache OpenJPA, a Java 
persistence project at The Apache Software Foundation.
 
-See [migration notes](migration/README.md)
+## Building the Site
 
-# Documentation Branches
+### Prerequisites
 
-The following branches contain documentation which is directly published:
-1. [Builds](../../tree/builds) - release documentation.
-2. [Docs](../../tree/docs) - incubating release documentation.
+- **Node.js** 22.x or later
+- **Python** 3.12+
+- **pip** (Python package manager)
+- **make** (optional, for convenience)
 
-Commit to the [builds branch](../../tree/builds) when releasing new 
documentation.
+### Setting up the Development Environment
+
+Since your environment has PEP 668 (externally-managed environment), you need 
to use a virtual environment:
+
+```bash
+# Create a virtual environment
+python3 -m venv venv
+
+# Activate the virtual environment
+# On Linux/macOS:
+source venv/bin/activate
+
+# On Windows:
+# venv\Scripts\activate
+```
+
+### Installing Dependencies
+
+Once the virtual environment is activated:
+
+```bash
+# Install Python dependencies
+pip install pelican markdown beautifulsoup4
+
+# Install npm dependencies
+npm install
+```
+
+### Building the Site
+
+#### Development Build (with live reload)
+```bash
+# Build static assets (Bootstrap CSS/JS from npm packages)
+npm run prepare
+
+# Build and serve with live reload
+pelican content -s pelican.auto.py -l

Review Comment:
   for whatever reason this step doesn't work for me :(
   
   I have to do
   ```
   npm run prepare
   pelican content -s pelican.auto.py
   pelican content -s pelican.auto.py -l
   ```
   
   otherwise I got "no index file" error



##########
.github/workflows/build.yml:
##########
@@ -0,0 +1,117 @@
+name: Build and Deploy Apache OpenJPA Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'content/**'
+      - 'theme/**'
+      - 'scripts/**'
+      - 'pelican.auto.py'
+      - 'pelicanconf.yaml'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.gitignore'
+      - '.asf.yaml'
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install npm dependencies
+        run: |
+          npm ci --ignore-scripts
+
+      - name: Install Python dependencies
+        run: |
+          pip install pelican markdown
+          pip install -r requirements.txt
+
+      - name: Build static assets
+        run: |
+          node scripts/build-assets.js
+
+      - name: Build documentation
+        run: |
+          pelican content -s pelican.auto.py
+
+      - name: List build output
+        run: |
+          echo "=== Generated Files ==="
+          ls -la output/
+          ls -la output/css/ 2>/dev/null || true
+          ls -la output/js/ 2>/dev/null || true
+
+      - name: Check for critical files
+        run: |
+          test -f output/index.html || (echo "ERROR: index.html missing" && 
exit 1)
+          echo "✓ Build validation passed"
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          npm ci --ignore-scripts
+          pip install pelican markdown
+          pip install -r requirements.txt
+
+      - name: Build static assets
+        run: |
+          node scripts/build-assets.js
+
+      - name: Build documentation
+        run: |
+          pelican content -s pelican.auto.py
+
+      - name: Deploy to asf-site
+        uses: apache/infrastructure-actions/pelican@main
+        with:
+          destination: asf-site
+          gfm: 'true'
+          publish: true

Review Comment:
   I would add missing `\n` in all places :))



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscr...@openjpa.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org