feat: add initial documentation website (#237)

Author: nullccxsy

.asf.yaml

@@ -22,10 +22,11 @@
 
 github:
   description: "Apache Iceberg C++"
-  homepage: https://iceberg.apache.org/
+  homepage: https://cpp.iceberg.apache.org/
   labels:
     - iceberg
     - apache
+    - cpp
   enabled_merge_buttons:
     merge: false
     squash: true
@@ -47,6 +48,8 @@ github:
     - raulcd
     - wgtmac
     - zhjwpku
+  ghp_branch: gh-pages
+  ghp_path: /
 
 notifications:
   commits:      [email protected]

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: "Release Docs"
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'mkdocs/**'
+      - 'src/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen
+          make install-deps
+
+      - name: Build API documentation with Doxygen
+        run: make build-api-docs
+
+      - name: Build docs
+        run:
+            make build-docs
+            mkdir -p /tmp/site
+            cp -r ./mkdocs/site/* /tmp/site/
+
+      - name: Deploy to gh-pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git config --global user.name 'GitHub Actions'
+          git config --global user.email '[email protected]'
+
+          git checkout --orphan gh-pages-tmp
+          git rm --quiet -rf .
+          cp -r /tmp/site/* .
+          echo "cpp.iceberg.apache.org" > CNAME
+          git add --all
+          git commit -m "Publish docs from commit ${{ github.sha }}"
+          git push -f origin gh-pages-tmp:gh-pages

Makefile

@@ -0,0 +1,51 @@
+# 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.
+
+.PHONY: help install-deps build-api-docs build-docs clean-docs serve-docs
+
+help:
+	@echo "Available targets:"
+	@echo "  install-deps     - Install Python dependencies"
+	@echo "  build-api-docs   - Build API documentation with Doxygen"
+	@echo "  build-docs       - Build MkDocs documentation"
+	@echo "  clean-docs       - Clean documentation build artifacts"
+	@echo "  serve-docs       - Serve documentation locally for development"
+	@echo "  all              - Build all documentation"
+
+install-deps:
+	python -m pip install --upgrade pip
+	pip install -r requirements.txt
+
+build-api-docs:
+	cd mkdocs && \
+	mkdir -p docs/api && \
+	doxygen Doxyfile && \
+	echo "Doxygen output created in docs/api/"
+
+build-docs:
+	cd mkdocs && \
+	mkdocs build --clean && \
+	echo "MkDocs site built in site/"
+
+clean-docs:
+	rm -rf mkdocs/site
+	rm -rf mkdocs/docs/api
+
+serve-docs:
+	cd mkdocs && mkdocs serve
+
+all: build-api-docs build-docs

mkdocs/CNAME

@@ -0,0 +1,18 @@
+# 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.
+
+cpp.iceberg.apache.org

docs/Doxyfile renamed to mkdocs/Doxyfile

@@ -91,7 +91,7 @@ PROJECT_ICON           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = build
+OUTPUT_DIRECTORY       = docs/api
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -1315,7 +1315,7 @@ GENERATE_HTML          = YES
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = html
+HTML_OUTPUT            = .
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).

docs/README.md renamed to mkdocs/README.md

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+# 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.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+cd "$PROJECT_ROOT"
+
+echo "Building Iceberg C++ documentation..."
+echo "Working directory: $(pwd)"
+
+if ! command -v mkdocs &> /dev/null; then
+    echo "Error: mkdocs is not installed"
+    exit 1
+fi
+
+echo "Installing dependencies..."
+pip install mkdocs-material
+
+# Check if doxygen is available
+if ! command -v doxygen &> /dev/null; then
+    echo "Warning: doxygen is not installed, skipping API documentation generation"
+else
+    echo "Building API documentation with Doxygen..."
+    cd mkdocs
+    mkdir -p docs/api
+    doxygen Doxyfile
+    cd ..
+fi
+
+echo "Building MkDocs documentation..."
+cd mkdocs
+mkdocs build --clean
+
+echo "Documentation build completed successfully!"
+echo "MkDocs site: docs/site/"