feat: add initial documentation website

.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,56 @@
+name: "Release Docs"
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'mkdocs/**'
+      - 'src/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - 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
+
+      - name: Deploy to gh-pages
+        if: github.event_name == 'pull_request'
+        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 ./mkdocs/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,34 @@
+.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 → 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).

mkdocs/build-docs.sh

@@ -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/"

mkdocs/docs/index.md

@@ -0,0 +1,189 @@
+<!--
+  ~ 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.
+-->
+
+# Contributing
+
+We welcome contributions to Apache Iceberg! To learn more about contributing to Apache Iceberg, please refer to the official Iceberg contribution guidelines. These guidelines are intended as helpful suggestions to make the contribution process as seamless as possible, and are not strict rules.
+
+If you would like to discuss your proposed change before contributing, we encourage you to visit our Community page. There, you will find various ways to connect with the community, including Slack and our mailing lists. Alternatively, you can open a new issue directly in the GitHub repository.
+
+For first-time contributors, feel free to check out our good first issues for an easy way to get started.
+
+## Contributing to Iceberg C++
+
+The Iceberg C++ Project is hosted on GitHub at [https://github.com/apache/iceberg-cpp](https://github.com/apache/iceberg-cpp).
+
+### Development Setup
+
+#### Prerequisites
+
+- CMake 3.25 or higher
+- C++23 compliant compiler (GCC 11+, Clang 14+, MSVC 2022+)
+- Git
+
+#### Building from Source
+
+Clone the repository for local development:
+
+```bash
+git clone https://github.com/apache/iceberg-cpp.git
+cd iceberg-cpp
+```
+
+Build the core libraries:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install -DICEBERG_BUILD_STATIC=ON -DICEBERG_BUILD_SHARED=ON
+cmake --build build
+ctest --test-dir build --output-on-failure
+cmake --install build
+```
+
+Build with bundled dependencies:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/path/to/install -DICEBERG_BUILD_BUNDLE=ON
+cmake --build build
+ctest --test-dir build --output-on-failure
+cmake --install build
+```
+
+### Code Standards
+
+#### C++ Coding Standards
+
+We follow modern C++ best practices:
+
+- **C++23 Standard**: Use C++23 features where appropriate
+- **Naming Conventions**:
+  - Classes: `PascalCase` (e.g., `TableScanBuilder`)
+  - Functions: `snake_case` (e.g., `find_field_by_name`)
+  - Variables: `snake_case` (e.g., `file_io`)
+  - Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRIES`)
+- **Memory Management**: Prefer smart pointers (`std::unique_ptr`, `std::shared_ptr`)
+- **Error Handling**: Use `Result<T>` types for error propagation
+- **Documentation**: Use Doxygen-style comments for public APIs
+
+#### API Compatibility
+
+It is important to keep the C++ public API compatible across versions. Public methods should have no leading underscores and should not be removed without deprecation notice.
+
+If you want to remove a method, please add a deprecation notice:
+
+```cpp
+[[deprecated("This method will be removed in version 2.0.0. Use new_method() instead.")]]
+void old_method();
+```
+
+#### Code Formatting
+
+We use `clang-format` for code formatting. The configuration is defined in `.clang-format` file.
+
+Format your code before submitting:
+
+```bash
+clang-format -i src/**/*.{h,cc}
+```
+
+### Testing
+
+#### Running Tests
+
+Run all tests:
+
+```bash
+ctest --test-dir build --output-on-failure
+```
+
+Run specific test:
+
+```bash
+ctest --test-dir build -R test_name
+```
+
+### Linting
+
+Install the python package `pre-commit` and run once `pre-commit install`:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+This will setup a git pre-commit-hook that is executed on each commit and will report the linting problems. To run all hooks on all files use `pre-commit run -a`.
+
+### Submitting Changes
+
+#### Git Workflow
+
+1. **Fork the repository** on GitHub
+2. **Create a feature branch** from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. **Make your changes** following the coding standards
+4. **Add tests** for your changes
+5. **Run tests** to ensure everything passes
+6. **Commit your changes** with a clear commit message
+7. **Push to your fork** and create a Pull Request
+
+#### Commit Message Format
+
+Use clear, descriptive commit messages:
+
+```
+feat: add support for S3 file system
+fix: resolve memory leak in table reader
+docs: update API documentation
+test: add unit tests for schema validation
+```
+
+#### Pull Request Process
+
+1. **Create a Pull Request** with a clear description
+2. **Link related issues** if applicable
+3. **Ensure CI passes** - all tests must pass
+4. **Request review** from maintainers
+5. **Address feedback** and update the PR as needed
+6. **Squash commits** if requested by reviewers
+
+### Community
+
+The Apache Iceberg community is built on the principles described in the [Apache Way](https://www.apache.org/theapacheway/index.html) and all who engage with the community are expected to be respectful, open, come with the best interests of the community in mind, and abide by the Apache Foundation [Code of Conduct](https://www.apache.org/foundation/policies/conduct.html).
+
+#### Getting Help
+
+- **Submit Issues**: [GitHub Issues](https://github.com/apache/iceberg-cpp/issues/new) for bug reports or feature requests
+- **Mailing List**: [[email protected]](mailto:[email protected]) for discussions
+  - [Subscribe](mailto:[email protected]?subject=(send%20this%20email%20to%20subscribe))
+  - [Unsubscribe](mailto:[email protected]?subject=(send%20this%20email%20to%20unsubscribe))
+  - [Archives](https://lists.apache.org/[email protected])
+- **Slack**: [Apache Iceberg Slack #cpp channel](https://join.slack.com/t/apache-iceberg/shared_invite/zt-1zbov3k6e-KtJfoaxp97YfX6dPz1Bk7A)
+
+#### Good First Issues
+
+New to the project? Check out our [good first issues](https://github.com/apache/iceberg-cpp/labels/good%20first%20issue) for an easy way to get started.
+
+### Release Process
+
+Releases are managed by the Apache Iceberg project maintainers. For information about the release process, please refer to the main Iceberg project documentation.
+
+## License
+
+Licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)