Website with Hugo (apache#279)

An approach for the website using Hugo, built to support versioned docs for Polaris releases.

"Released versions" are categorized into "active" and "EOL" versions - only the "actively maintained" versions appear in the menu in the navbar.

** Quickstart **

Just run the following command to let Hugo serve files from the Polaris `site/`.
```bash
site/bin/run-hugo-in-docker.sh
```

Then point your browser to http://localhost:1313/

To stop the Hugo run
```bash
site/bin/stop-hugo-in-docker.sh
```
(or just ctrl-C)

See `README.md` in the `site/` directory for more options

** Versioned docs **

The idea here is that docs of releases live in either a separate branch or a separate Git repo.

The `/releases` folder would _not_ be in the main Polaris repository (at least not in any code branch). It would be
mounted either via `git worktree` or `git clone`. Building and testing the site locally works without the `/releases`
folder. For developers, it is probably much easier to have a separate branch in the main Polaris GitHub repository
and leverage Git worktrees.

Docs for the current code branch (e.g. `main` branch) are maintained in the `/in-dev/unreleased` folder. While we
could maintain the docs right in the `/in-dev` folder, having the in-dev docs in `/in-dev/unreleased` provides the
ability to use relative links that still work when the docs are in an `/releases/x.y.z` folder (think: links like
`../../guides/foo-bar.md`).

Within a release's versioned docs folder, the release version number can be included in the markdown using the
custom Hugo shortcode `{{< releaseVersion >}}`.

Author: snazy

.github/workflows/check-md-link.yml

@@ -41,4 +41,5 @@ jobs:
       with:
         use-quiet-mode: 'yes'
         config-file: '.github/workflows/check-md-link-config.json'
-        folder-path: '.' # checks all md files
+        folder-path: 'regtests, regtests/client/python/docs, regtests/client/python, .github, build-logic, polaris-core, polaris-service, extension, spec, k8, notebooks'
+        file-path: 'CHAT_BYLAWS.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, README.md SECURITY.md'

.github/workflows/site.yml

@@ -0,0 +1,58 @@
+#
+# 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
+#
+#   http://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.
+#
+
+name: "Hugo Site"
+on:
+  push:
+    branches: [ "main", "versioned-docs" ]
+  pull_request:
+
+jobs:
+  site:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          ref: "versioned-docs"
+          path: site/content/releases
+
+      - name: Install docker-compose
+        run: |
+          sudo curl -SL \
+            https://github.com/docker/compose/releases/download/v2.29.2/docker-compose-linux-x86_64 \
+            -o /usr/local/bin/docker-compose
+          sudo chmod 755 /usr/local/bin/docker-compose
+          sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
+
+      - name: Build Apache Site
+        run: site/bin/create-static-site.sh
+
+      # TODO Do we want to deploy from 'asf-site' in the 'polaris-site' repo or in the 'polaris' repo?
+      #   The former requires a secret
+      - name: Deploy Static Site to GitHub
+        if: github.event_name == 'push' && github.repository == 'apache/polaris'
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: asf-site
+          publish_dir: ./site/build/apache-site
+          cname: polaris.apache.org

.gitignore

@@ -64,6 +64,11 @@ gradle/wrapper/gradle-wrapper-*.sha256
 **/build/
 !src/**/build/
 
+# Possibly generated by npm from our Hugo container and leaking to the workspace - no need to track those in our case.
+node_modules/
+/package.json
+/package-lock.json
+
 # jenv
 .java-version
 

README.md

@@ -90,11 +90,12 @@ Running regression tests
 - `docker compose up --build --exit-code-from regtest` - To run regression tests in a Docker environment.
 
 Building docs
-- Docs are generated using [Redocly](https://redocly.com/docs/cli/installation). To regenerate them, run the following
-commands from the project root directory.
-```bash
-docs/build
-```
+- Docs are generated using [Hugo](https://gohugo.io/) using the [Docsy](https://www.docsy.dev/docs/) theme.
+- To view the site locally, run
+  ```bash
+  site/bin/run-hugo-in-docker.sh
+  ```
+- See [README in `site/`](site/README.md) for more information.
 
 ## License
 

build.gradle.kts

@@ -87,6 +87,13 @@ tasks.named<RatTask>("rat").configure {
   excludes.add("polaris-service/src/**/banner.txt")
   excludes.add("polaris-service/logs")
 
+  excludes.add("site/node_modules/**")
+  excludes.add("site/layouts/robots.txt")
+  // Ignore generated stuff, when the Hugo is run w/o Docker
+  excludes.add("site/public/**")
+  excludes.add("site/resources/_gen/**")
+  excludes.add("node_modules/**")
+
   excludes.add("**/polaris-venv/**")
 
   excludes.add("**/.pytest_cache/**")
@@ -110,6 +117,8 @@ tasks.named<RatTask>("rat").configure {
   excludes.add("**/*.lock")
 
   excludes.add("**/*.env*")
+
+  excludes.add("**/go.sum")
 }
 
 // Pass environment variables: