Skip to content

Commit 102e4f0

Browse files
JingsongLiJingsongLi
authored
feat: Introduce docs for paimon-rust (#157)
1 parent 6f34239 commit 102e4f0

8 files changed

Lines changed: 516 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,15 @@ Apache Paimon Rust is an exciting project currently under active development. Wh
3939
- Start discussion thread at [dev mailing list](mailto:dev@paimon.apache.org) ([subscribe](<mailto:dev-subscribe@paimon.apache.org?subject=(send%20this%20email%20to%20subscribe)>) / [unsubscribe](<mailto:dev-unsubscribe@paimon.apache.org?subject=(send%20this%20email%20to%20unsubscribe)>) / [archives](https://lists.apache.org/list.html?dev@paimon.apache.org))
4040
- Talk to community directly at [Slack #paimon channel](https://join.slack.com/t/the-asf/shared_invite/zt-2l9rns8pz-H8PE2Xnz6KraVd2Ap40z4g).
4141

42+
## Documentation
43+
44+
The project documentation is built with [MkDocs](https://www.mkdocs.org/). See [docs/README.md](docs/README.md) for details.
45+
46+
```bash
47+
pip3 install mkdocs-material
48+
cd docs && mkdocs serve
49+
```
50+
4251
## Getting help
4352

4453
Submit [issues](https://github.com/apache/paimon-rust/issues/new/choose) for bug report or asking questions in [discussion](https://github.com/apache/paimon-rust/discussions/new?category=q-a).

‎docs/README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
-->
19+
20+
# Documentation
21+
22+
This directory contains the source files for the Apache Paimon Rust documentation site, built with [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
23+
24+
## Prerequisites
25+
26+
- Python 3.8+
27+
- pip3
28+
29+
## Setup
30+
31+
```bash
32+
pip3 install mkdocs-material
33+
```
34+
35+
## Development
36+
37+
Preview the docs locally with live reload:
38+
39+
```bash
40+
cd docs
41+
mkdocs serve
42+
```
43+
44+
Then open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser.
45+
46+
## Build
47+
48+
Generate the static site:
49+
50+
```bash
51+
cd docs
52+
mkdocs build
53+
```
54+
55+
The output will be in the `docs/site/` directory.

‎docs/mkdocs.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
site_name: Apache Paimon Rust
19+
site_description: The Rust implementation of Apache Paimon
20+
site_url: https://apache.github.io/paimon-rust/
21+
repo_url: https://github.com/apache/paimon-rust
22+
repo_name: apache/paimon-rust
23+
24+
docs_dir: src
25+
26+
theme:
27+
name: material
28+
palette:
29+
- scheme: default
30+
primary: indigo
31+
accent: indigo
32+
toggle:
33+
icon: material/brightness-7
34+
name: Switch to dark mode
35+
- scheme: slate
36+
primary: indigo
37+
accent: indigo
38+
toggle:
39+
icon: material/brightness-4
40+
name: Switch to light mode
41+
features:
42+
- navigation.sections
43+
- navigation.expand
44+
- navigation.top
45+
- search.suggest
46+
- content.code.copy
47+
48+
nav:
49+
- Home: index.md
50+
- Getting Started: getting-started.md
51+
- Architecture: architecture.md
52+
- Releases: releases.md
53+
- Contributing: contributing.md
54+
55+
markdown_extensions:
56+
- admonition
57+
- pymdownx.details
58+
- pymdownx.superfences
59+
- pymdownx.highlight:
60+
anchor_linenums: true
61+
- pymdownx.inlinehilite
62+
- pymdownx.tabbed:
63+
alternate_style: true
64+
- toc:
65+
permalink: true

‎docs/src/architecture.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
-->
19+
20+
# Architecture
21+
22+
## Overview
23+
24+
Apache Paimon Rust is organized as a Cargo workspace with multiple crates, each responsible for a distinct layer of functionality.
25+
26+
## Crate Structure
27+
28+
### `crates/paimon` — Core Library
29+
30+
The core crate implements the Paimon table format, including:
31+
32+
- **Catalog** — Catalog client for discovering and managing databases and tables
33+
- **Table** — Table abstraction for reading Paimon tables
34+
- **Snapshot & Manifest** — Reading snapshot and manifest metadata
35+
- **Schema** — Table schema management and evolution
36+
- **File IO** — Abstraction layer for storage backends (local filesystem, S3)
37+
- **File Format** — Parquet file reading and writing via Apache Arrow
38+
39+
### `crates/integrations/datafusion` — DataFusion Integration
40+
41+
Provides a `TableProvider` implementation that allows querying Paimon tables using [Apache DataFusion](https://datafusion.apache.org/)'s SQL engine.
42+
43+
## Data Model
44+
45+
Paimon organizes data in a layered structure:
46+
47+
```
48+
Catalog
49+
└── Database
50+
└── Table
51+
├── Schema
52+
└── Snapshot
53+
└── Manifest
54+
└── Data Files (Parquet)
55+
```
56+
57+
- **Catalog** manages databases and tables, accessed via REST API
58+
- **Snapshot** represents a consistent view of a table at a point in time
59+
- **Manifest** lists the data files that belong to a snapshot
60+
- **Data Files** store the actual data in Parquet format

‎docs/src/contributing.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
-->
19+
20+
# Contributing
21+
22+
Apache Paimon Rust welcomes contributions from everyone. See the full [Contributing Guide](https://github.com/apache/paimon-rust/blob/main/CONTRIBUTING.md) for detailed instructions.
23+
24+
## Quick Start
25+
26+
1. Fork the [repository](https://github.com/apache/paimon-rust)
27+
2. Clone your fork: `git clone https://github.com/<your-username>/paimon-rust.git`
28+
3. Create a feature branch: `git checkout -b feature/my-feature`
29+
4. Make your changes and add tests
30+
5. Run checks locally before submitting
31+
6. Open a Pull Request
32+
33+
## Development Setup
34+
35+
```bash
36+
# Ensure you have the correct Rust toolchain
37+
rustup show
38+
39+
# Build the project
40+
cargo build
41+
42+
# Run all tests
43+
cargo test
44+
45+
# Format code
46+
cargo fmt
47+
48+
# Lint (matches CI)
49+
cargo clippy --all-targets --workspace -- -D warnings
50+
```
51+
52+
## Finding Issues
53+
54+
- Check [open issues](https://github.com/apache/paimon-rust/issues) for tasks to work on
55+
- Issues labeled `good first issue` are great starting points
56+
- See the [0.1.0 tracking issue](https://github.com/apache/paimon-rust/issues/3) for the current roadmap
57+
58+
## Community
59+
60+
- **GitHub Issues**: [apache/paimon-rust/issues](https://github.com/apache/paimon-rust/issues)
61+
- **Mailing List**: [dev@paimon.apache.org](mailto:dev@paimon.apache.org) ([subscribe](mailto:dev-subscribe@paimon.apache.org) / [archives](https://lists.apache.org/list.html?dev@paimon.apache.org))
62+
- **Slack**: [#paimon channel](https://join.slack.com/t/the-asf/shared_invite/zt-2l9rns8pz-H8PE2Xnz6KraVd2Ap40z4g) on the ASF Slack

0 commit comments

Comments
 (0)