Skip to content

Commit 3575873

Browse files
jackye1995jackye1995
authored
feat: add mkdocs documentation (#114)
Closes #45 Preview: https://jackye1995.github.io/lance-namespace/
1 parent 54621e7 commit 3575873

25 files changed

Lines changed: 262 additions & 80 deletions

‎.github/workflows/docs-check.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Check docs
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
pull_request:
7+
paths:
8+
- docs/**
9+
- .github/workflows/docs-check.yml
10+
11+
env:
12+
RUSTFLAGS: "-C debuginfo=0"
13+
# according to: https://matklad.github.io/2021/09/04/fast-rust-builds.html
14+
# CI builds are faster with incremental disabled.
15+
CARGO_INCREMENTAL: "0"
16+
17+
jobs:
18+
# Single deploy job since we're just deploying
19+
check-docs:
20+
runs-on: ubuntu-24.04
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
- uses: actions/setup-python@v5
25+
with:
26+
python-version: 3.11
27+
cache: 'pip'
28+
cache-dependency-path: "docs/requirements.txt"
29+
- run: pip install -r docs/requirements.txt
30+
- name: Check links
31+
working-directory: docs
32+
run: |
33+
mkdocs-linkcheck src
34+

‎.github/workflows/docs-deploy.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Licensed under the Apache License, Version 2.0 (the "License");
2+
# you may not use this file except in compliance with the License.
3+
# You may obtain a copy of the License at
4+
#
5+
# http://www.apache.org/licenses/LICENSE-2.0
6+
#
7+
# Unless required by applicable law or agreed to in writing,
8+
# software distributed under the License is distributed on an
9+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
10+
# KIND, either express or implied. See the License for the
11+
# specific language governing permissions and limitations
12+
# under the License.
13+
14+
name: publish-site
15+
on:
16+
push:
17+
branches:
18+
- main
19+
20+
permissions:
21+
contents: write
22+
23+
jobs:
24+
deploy:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- uses: actions/checkout@v4
28+
- name: Configure Git Credentials
29+
run: |
30+
git config user.name github-actions[bot]
31+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
32+
- uses: actions/setup-python@v5
33+
with:
34+
python-version: 3.11
35+
cache: 'pip'
36+
cache-dependency-path: "docs/requirements.txt"
37+
- uses: actions/cache@v4
38+
with:
39+
key: mkdocs-material-${{ env.cache_id }}
40+
path: .cache
41+
restore-keys: |
42+
mkdocs-material-
43+
- run: pip install -r docs/requirements.txt
44+
- name: Deploy
45+
working-directory: docs
46+
run: mkdocs gh-deploy --force

‎.github/workflows/java.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ on:
2323
- ready_for_review
2424
- reopened
2525
paths:
26-
- spec/**
26+
- docs/src/spec/**
2727
- java/**
2828
- .github/workflows/java.yml
2929

‎.github/workflows/python.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ on:
2323
- ready_for_review
2424
- reopened
2525
paths:
26-
- spec/**
26+
- docs/src/spec/**
2727
- python/**
2828
- .github/workflows/python.yml
2929

‎.github/workflows/rust.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ on:
2323
- ready_for_review
2424
- reopened
2525
paths:
26-
- spec/**
26+
- docs/src/spec/**
2727
- rust/**
2828
- .github/workflows/rust.yml
2929

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,4 +114,7 @@ env/
114114
venv/
115115
ENV/
116116
env.bak/
117-
venv.bak/
117+
venv.bak/
118+
119+
# Docs
120+
docs/site

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
# limitations under the License.
1212

1313
lint:
14-
openapi-spec-validator --errors all spec/rest.yaml
14+
openapi-spec-validator --errors all docs/src/spec/rest.yaml
1515

1616
clean-rust:
1717
cd rust; make clean

‎README.md‎

Lines changed: 5 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,10 @@
1-
# Lance Namespace Specification
1+
# Lance Namespace
22

3-
**Lance Namespace Specification** is an open specification on top of the storage-based Lance data format
3+
![logo](./docs/src/logo/wide.png)
4+
5+
**Lance Namespace** is an open specification on top of the storage-based Lance data format
46
to standardize access to a collection of Lance tables (a.k.a. Lance datasets).
57
It describes how a metadata service like Apache Hive MetaStore (HMS), Apache Gravitino, Unity Catalog, etc.
68
should store and use Lance tables, as well as how ML/AI tools and analytics compute engines should integrate with Lance tables.
79

8-
## Repository structure
9-
10-
| Directory | Description |
11-
|------------------------------------------------------------------------------------|------------------------------------------------------------|
12-
| [spec](./spec) | Lance Namespace Specification |
13-
| [rust/lance-namespace-reqwest-client](./rust/lance-namespace-reqwest-client) | Generated Rust reqwest client for Lance REST Namespace |
14-
| [python/lance_namespace_urllib3_client](./python/lance_namespace_urllib3_client) | Generated Python urllib3 client for Lance REST Namespace |
15-
| [java/lance-namespace-apache-client](./java/lance-namespace-apache-client) | Generated Java Apache HTTP client for Lance REST Namespace |
16-
| [java/lance-namespace-springboot-server](./java/lance-namespace-springboot-server) | Generated Java SpringBoot server for Lance REST Namespace |
17-
18-
## Development Guide
19-
20-
### Install OpenAPI Generator
21-
22-
We use [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator)
23-
to generate various clients and servers for the namespace specification.
24-
We recommend installing the tool through [pip](https://pypi.org/project/openapi-generator-cli/)
25-
for consistent experience across platforms.
26-
First time setup of virtual environment and installation:
27-
28-
```bash
29-
python3 -m venv .env
30-
source .env/bin/activate
31-
pip install -r requirements.txt
32-
```
33-
34-
### Install Poetry for Python
35-
36-
If you want to build the entire project, or develop python specifically,
37-
you need to install [poetry](https://python-poetry.org/).
38-
To quickly install it in your virtual environment:
39-
40-
```bash
41-
pip install -r python/requirements.txt
42-
```
43-
44-
### Lint
45-
To ensure the OpenAPI definition is valid, you can use the lint command to check it.
46-
47-
```bash
48-
make lint
49-
```
50-
51-
### Build
52-
53-
There are 3 commands that is available at top level as well as inside each language folder:
54-
55-
- `make clean`: remove all codegen modules
56-
- `make gen`: codegen and lint all modules (depends on `clean`)
57-
- `make build`: build all modules (depends on `gen`)
58-
59-
You can also run `make <command>-<language>` to only run the command in the specific language, for example:
60-
61-
- `make gen-python`: codegen and lint all Python modules
62-
- `make build-rust`: build all Rust modules
63-
64-
You can also run `make <command>-<language>-<module>` inside a language folder to run the command against a specific module, for example:
65-
66-
- `make gen-rust-reqwest-client`: codegen and lint the Rust reqwest client module
67-
- `make build-java-springboot-server`: build the Java Spring Boot server module
10+
For more details, please visit the [documentation website](https://lancedb.github.io/lance-namespace).

‎docs/mkdocs.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
site_name: Lance Namespace
2+
site_description: open specification on top of the storage-based Lance data format to standardize access to a collection of Lance tables
3+
site_url: https://lancedb.github.io/lance-namespace/
4+
docs_dir: src
5+
6+
repo_name: lancedb/lance-namespace
7+
repo_url: https://github.com/lancedb/lance-namespace
8+
9+
theme:
10+
name: material
11+
logo: logo/white.png
12+
favicon: logo/logo.png
13+
palette:
14+
- scheme: default
15+
primary: indigo
16+
accent: indigo
17+
toggle:
18+
icon: material/brightness-7
19+
name: Switch to dark mode
20+
- scheme: slate
21+
primary: indigo
22+
accent: indigo
23+
toggle:
24+
icon: material/brightness-4
25+
name: Switch to light mode
26+
features:
27+
- navigation.sections
28+
- navigation.expand
29+
- navigation.top
30+
- search.highlight
31+
- search.share
32+
- content.code.copy
33+
- content.code.annotate
34+
icon:
35+
repo: fontawesome/brands/github
36+
37+
markdown_extensions:
38+
- admonition
39+
- pymdownx.details
40+
- pymdownx.superfences
41+
- pymdownx.highlight:
42+
anchor_linenums: true
43+
line_spans: __span
44+
pygments_lang_class: true
45+
- pymdownx.inlinehilite
46+
- pymdownx.snippets
47+
- pymdownx.tabbed:
48+
alternate_style: true
49+
- attr_list
50+
- md_in_html
51+
- tables
52+
- toc:
53+
permalink: true
54+
55+
plugins:
56+
- search
57+
58+
extra:
59+
social:
60+
- icon: fontawesome/brands/github
61+
link: https://github.com/lancedb/lance-namespace
62+
- icon: fontawesome/brands/discord
63+
link: https://discord.gg/zMM32dvNtd
64+
- icon: fontawesome/brands/twitter
65+
link: https://twitter.com/lancedb
66+
67+
nav:
68+
- Introduction: index.md
69+
- Spec:
70+
- Text: spec/spec.md
71+
- OpenAPI: https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/lancedb/lance-namespace/refs/heads/main/docs/src/docs/src/spec/rest.yaml
72+
- Native Implementations:
73+
- Overview: spec/impls/overview.md
74+
- Rest: spec/impls/rest.md
75+
- Directory: spec/impls/dir.md
76+
- Apache Hive MetaStore: spec/impls/hive.md
77+
- Contributing: contributing.md
78+
- Lance: https://lancedb.github.io/lance

‎docs/requirements.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
mkdocs-material
2+
mkdocs-linkcheck

0 commit comments

Comments
 (0)