Lance 文档贡献指南主站构建、本地预览与多语言 API 文档发布全流程【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance本篇指南围绕 Lance 仓库中 docs/CONTRIBUTING.md 展开完整介绍 Lance 文档体系的技术栈MkDocs 主站、Sphinx、docs.rs、Javadoc、本地构建与预览命令、站点配置与自定义主题结构以及多仓库站点组装与链接检查流程。读完本文你将掌握在 Lance 仓库中搭建文档开发环境、贡献与验证文档改动的完整实战方法。Lance 文档体系一览Lance面向多模态 AI 的开源湖仓格式的文档由多个独立通道构成各自服务于不同读者与发布渠道文档类型构建工具发布渠道入口主站文档用户指南/格式规范/社区页MkDocsMkDocs Material 风格仓库内为自定义主题官方文档站docs/CONTRIBUTING.mdPython API 文档SphinxGitHub PagesReadTheDocs 风格docs/CONTRIBUTING.mdRust API 文档rustdocdocs.rs随发布流程自动发布docs/CONTRIBUTING.mdJava API 文档javadocMaven Central / javadoc.iodocs/CONTRIBUTING.md本指南重点讲解主站文档的本地开发闭环其余三类 API 文档简要说明其构建与发布机制。主站对应的源码全部位于仓库的 docs 目录下结构如下src/所有 Markdown 源文件用户指南、格式规范、快速上手、社区页等theme/自定义 MkDocs 主题*.html模板 theme/assets/下的样式与脚本mkdocs.ymlMkDocs 站点配置pyproject.toml基于 uv 的 Python 工程配置Makefile常用的构建/校验命令入口。环境准备安装 uv 并同步依赖Lance 文档工程使用 uv 管理 Python 依赖uv 是高性能的 Python 包管理器可自动解析pyproject.toml并生成锁定文件。安装 uv 后即可直接同步依赖无需手工逐个安装cd docs uv sync --dev这条命令是文档贡献的第一步它会读取 docs/pyproject.toml 中声明的运行依赖与[tool.uv]下的 dev 依赖并一次性安装。从该配置文件可以确认主站构建所需的完整依赖清单mkdocs1.5.0文档站生成器pymdown-extensions10.0PyMdown 扩展集提供 admonition、superfences、tabbed 等 Markdown 增强能力pygments2.16代码高亮mkdocs-protobuf0.1.0用于将protos/目录下的.proto文件渲染为文档mkdocs-linkcheck1.0.0链接检查工具mkdocs-awesome-pages-plugin2.10.1为目录生成导航awesome-pages插件requests2.31.0linkcheck 的运行依赖。dev 依赖还包括mike多版本文档、mkdocs-minify-pluginHTML 压缩、mkdocs-git-revision-date-localized-plugin显示文档最后修改时间以及ruff用于对 Markdown 代码块做 Python lint。本地构建与实时预览主站依赖同步完成后使用 MkDocs 自带的开发服务器即可在本地实时预览文档改动cd docs uv run mkdocs serveuv run会在当前工程环境中执行mkdocs serve启动后访问本地端口即可浏览站点编辑src/下的 Markdown 文件会自动触发增量重建。若想得到静态产物可改用make build构建结果输出到docs/site/目录。仓库在 docs/Makefile 中把常用操作封装成了目标便于记忆与自动化Make 目标作用make serve本地实时预览自动组装多仓库文档并启动 mkdocs servemake build构建静态站点到site/make sync按pyproject.toml同步全部依赖含所有 extrasmake check-links检查文档中的损坏链接基于 mkdocs-linkcheckmake make-full-website从本地多仓库 checkout 组装完整站点make clean-full-website清理组装生成的占位内容make clean清理site/与.cache/构建产物注意make serve与make build都依赖make-full-website目标即先执行多仓库组装脚本再构建因此首次运行前请先阅读下文的多仓库组装说明。深入 MkDocs 配置mkdocs.yml 逐项解读主站的核心配置在 docs/mkdocs.yml理解它有助于判断文档改动的影响面site_name: Lance、site_description站点名称与 SEO 描述docs_dir: src指明 Markdown 源目录themename: nullcustom_dir: theme表示完全使用仓库内自定义主题而非内置 Material 主题模板位于theme/markdown_extensions启用了admonition提示块、pymdownx.details可折叠提示、pymdownx.superfences自定义代码栅栏支持渲染 Mermaid 图、pymdownx.highlight/inlinehilite代码高亮、pymdownx.snippets从仓库根目录拉取共享文档片段base_path配置为.与..、pymdownx.tabbed选项卡、pymdownx.magiclink裸 URL 自动链接、attr_list、tables与带 permalink 的tocpluginssearch站内搜索、awesome-pages依据各目录.pages文件生成导航、mkdocs_protobuf将proto_dir: ../protos指向仓库根目录的 protos 中的 proto 文件渲染为格式文档页hooks注册了 docs/hooks/pmc_roster.py在构建期自动生成 PMC 花名册表格详见后文。自定义主题Lance Docs 设计与多数仓库直接使用 MkDocs Material 主题不同Lance 主站使用了一套自定义主题实现“Lance Docs”设计语言。主题源码位于 docs/themebase.html全局骨架模板包含head、页头品牌 Logo、顶栏导航、GitHub/Discord 按钮、主题切换、页脚与搜索遮罩层。其中主题初始化脚本会在首屏绘制前读取localStorage中的ld-theme并按prefers-color-scheme回退避免浅色模式闪烁main.html内容区模板负责侧边栏分组导航sidenav_section宏、面包屑、正文区、上一篇/下一篇分页以及“On this page”目录theme/assets/site.js主题行为脚本包括主题切换、GitHub Star 数拉取缓存 1 小时离线时降级为普通链接、移动端侧边栏、代码块语言角标、TOC 滚动跟随、搜索遮罩层以及按需从 CDN 加载 Mermaid 渲染库theme/assets/site.css、tokens.css设计令牌与样式定义。因此若你贡献的内容涉及页面级 UI 调整改动点应在theme/下而纯内容贡献只修改src/下的 Markdown 即可。多仓库站点组装make-full-website.sh 的协作机制Lance 的完整文档站并不只来自本仓库还聚合了 lance-namespace、lance-namespace-impls、lance-spark、lance-ray、lance-trino、lance-duckdb、lance-huggingface、lance-context 等多个相关仓库的文档。docs/make-full-website.sh 负责把本地这些 checkout 中的文档复制进docs/src/对应目录支持通过环境变量覆盖各仓库路径例如LANCE_NAMESPACE_REPO、LANCE_SPARK_REPO、LANCE_RAY_REPO、LANCE_DUCKDB_REPO等默认值指向$HOME/oss/下的同名目录每个仓库都有独立的复制/跳过逻辑源目录存在则复制copy_docs_dir、copy_file_if_exists不存在则仅打印警告并保留占位文档warn_missing_repo复制完成后会动态改写各目录的.pages导航文件如integrations/、community/project-specific/把外部仓库的页面按顺序并入站点导航最后还会把仓库根目录的 CONTRIBUTING.md、release_process.md、rust/CONTRIBUTING.md、python/CONTRIBUTING.md 以及 docs/CONTRIBUTING.md 分别复制为社区页下的general.md、release.md、rust.md、python.md、docs.md。与之配套的 docs/clean-full-website.sh 会先清理上一次组装留下的外部内容再重建各处的占位页如 catalog、namespace 规范页保证在缺少外部 checkout 时make build/make serve依然可运行。这也是make serve必须先经过make-full-website的原因。构建期钩子PMC 花名册自动生成docs/hooks/pmc_roster.py 是一个 MkDocs 构建钩子它以 docs/src/community/pmc.yaml 为唯一事实来源在页面渲染阶段查找!-- PMC_ROSTER_TABLE --占位符并替换为自动生成的 Markdown 表格列为 Name、GitHub Handle、Affiliation、Ecosystem Roles。这样社区页的花名册永远不需要手工维护与 CI 中格式规范投票门禁共用同一份数据源。钩子通过 docs/mkdocs.yml 中的hooks:注册。文档质量保障链接检查与依赖维护链接检查运行make check-links底层是uv run mkdocs-linkcheck src即可扫描全部 Markdown 中的损坏链接适合在提交前自检新增依赖使用uv add package普通依赖或uv add --dev package开发依赖更新 docs/pyproject.toml必要时make sync重新同步依赖升级uv add packagelatest升级单个包uv sync --upgrade全量升级代码块质量[tool.ruff]配置会把*.md乃至*.ipynb纳入检查范围对文档中的 Python 代码块执行 E/F/UP/B/SIM/I 系列 lint忽略 E501 行长度确保文档示例代码可直接运行。Python、Rust、Java API 文档的构建与发布主站之外三类语言 SDK 的 API 文档各自独立构建与发布Python由独立的 lance-python-doc 工程使用 Sphinx 构建以 ReadTheDocs 风格发布到 GitHub Pages。因此 Python API 文档的改动属于独立仓库的职责不在本仓库docs/中维护RustRust crate 文档作为发布流程的一部分构建并发布到 docs.rs 的lancecrate 页面即在发布版本时自动生成JavaJava 文档在构建后发布到 Maven Central可通过 javadoc.io 按项目查看对应 Javadoc 页面。对于普通贡献者而言若要修改主站内容只需在src/下编辑 Markdown 并运行本地预览即可若要参与 API 文档需前往各自对应的独立工程。贡献文档的推荐工作流结合以上机制向 Lance 主站贡献文档的完整流程可总结为安装 uv进入docs/执行uv sync --dev同步依赖视需要设置各LANCE_*_REPO环境变量指向本地外部仓库 checkout否则使用占位文档运行make serve启动本地预览确认改动渲染正确在docs/src/下修改 Markdown涉及导航顺序时同步更新对应目录的.pages文件运行make check-links检查链接完整性提交前确认 docs/CONTRIBUTING.md 中列出的构建与发布约定未被破坏。遵循上述流程即可在不依赖外部站点的前提下完成 Lance 主站文档从编写、本地验证到提交的全过程。【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Lance 文档贡献指南：主站构建、本地预览与多语言 API 文档发布全流程
Lance 文档贡献指南主站构建、本地预览与多语言 API 文档发布全流程【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance本篇指南围绕 Lance 仓库中 docs/CONTRIBUTING.md 展开完整介绍 Lance 文档体系的技术栈MkDocs 主站、Sphinx、docs.rs、Javadoc、本地构建与预览命令、站点配置与自定义主题结构以及多仓库站点组装与链接检查流程。读完本文你将掌握在 Lance 仓库中搭建文档开发环境、贡献与验证文档改动的完整实战方法。Lance 文档体系一览Lance面向多模态 AI 的开源湖仓格式的文档由多个独立通道构成各自服务于不同读者与发布渠道文档类型构建工具发布渠道入口主站文档用户指南/格式规范/社区页MkDocsMkDocs Material 风格仓库内为自定义主题官方文档站docs/CONTRIBUTING.mdPython API 文档SphinxGitHub PagesReadTheDocs 风格docs/CONTRIBUTING.mdRust API 文档rustdocdocs.rs随发布流程自动发布docs/CONTRIBUTING.mdJava API 文档javadocMaven Central / javadoc.iodocs/CONTRIBUTING.md本指南重点讲解主站文档的本地开发闭环其余三类 API 文档简要说明其构建与发布机制。主站对应的源码全部位于仓库的 docs 目录下结构如下src/所有 Markdown 源文件用户指南、格式规范、快速上手、社区页等theme/自定义 MkDocs 主题*.html模板 theme/assets/下的样式与脚本mkdocs.ymlMkDocs 站点配置pyproject.toml基于 uv 的 Python 工程配置Makefile常用的构建/校验命令入口。环境准备安装 uv 并同步依赖Lance 文档工程使用 uv 管理 Python 依赖uv 是高性能的 Python 包管理器可自动解析pyproject.toml并生成锁定文件。安装 uv 后即可直接同步依赖无需手工逐个安装cd docs uv sync --dev这条命令是文档贡献的第一步它会读取 docs/pyproject.toml 中声明的运行依赖与[tool.uv]下的 dev 依赖并一次性安装。从该配置文件可以确认主站构建所需的完整依赖清单mkdocs1.5.0文档站生成器pymdown-extensions10.0PyMdown 扩展集提供 admonition、superfences、tabbed 等 Markdown 增强能力pygments2.16代码高亮mkdocs-protobuf0.1.0用于将protos/目录下的.proto文件渲染为文档mkdocs-linkcheck1.0.0链接检查工具mkdocs-awesome-pages-plugin2.10.1为目录生成导航awesome-pages插件requests2.31.0linkcheck 的运行依赖。dev 依赖还包括mike多版本文档、mkdocs-minify-pluginHTML 压缩、mkdocs-git-revision-date-localized-plugin显示文档最后修改时间以及ruff用于对 Markdown 代码块做 Python lint。本地构建与实时预览主站依赖同步完成后使用 MkDocs 自带的开发服务器即可在本地实时预览文档改动cd docs uv run mkdocs serveuv run会在当前工程环境中执行mkdocs serve启动后访问本地端口即可浏览站点编辑src/下的 Markdown 文件会自动触发增量重建。若想得到静态产物可改用make build构建结果输出到docs/site/目录。仓库在 docs/Makefile 中把常用操作封装成了目标便于记忆与自动化Make 目标作用make serve本地实时预览自动组装多仓库文档并启动 mkdocs servemake build构建静态站点到site/make sync按pyproject.toml同步全部依赖含所有 extrasmake check-links检查文档中的损坏链接基于 mkdocs-linkcheckmake make-full-website从本地多仓库 checkout 组装完整站点make clean-full-website清理组装生成的占位内容make clean清理site/与.cache/构建产物注意make serve与make build都依赖make-full-website目标即先执行多仓库组装脚本再构建因此首次运行前请先阅读下文的多仓库组装说明。深入 MkDocs 配置mkdocs.yml 逐项解读主站的核心配置在 docs/mkdocs.yml理解它有助于判断文档改动的影响面site_name: Lance、site_description站点名称与 SEO 描述docs_dir: src指明 Markdown 源目录themename: nullcustom_dir: theme表示完全使用仓库内自定义主题而非内置 Material 主题模板位于theme/markdown_extensions启用了admonition提示块、pymdownx.details可折叠提示、pymdownx.superfences自定义代码栅栏支持渲染 Mermaid 图、pymdownx.highlight/inlinehilite代码高亮、pymdownx.snippets从仓库根目录拉取共享文档片段base_path配置为.与..、pymdownx.tabbed选项卡、pymdownx.magiclink裸 URL 自动链接、attr_list、tables与带 permalink 的tocpluginssearch站内搜索、awesome-pages依据各目录.pages文件生成导航、mkdocs_protobuf将proto_dir: ../protos指向仓库根目录的 protos 中的 proto 文件渲染为格式文档页hooks注册了 docs/hooks/pmc_roster.py在构建期自动生成 PMC 花名册表格详见后文。自定义主题Lance Docs 设计与多数仓库直接使用 MkDocs Material 主题不同Lance 主站使用了一套自定义主题实现“Lance Docs”设计语言。主题源码位于 docs/themebase.html全局骨架模板包含head、页头品牌 Logo、顶栏导航、GitHub/Discord 按钮、主题切换、页脚与搜索遮罩层。其中主题初始化脚本会在首屏绘制前读取localStorage中的ld-theme并按prefers-color-scheme回退避免浅色模式闪烁main.html内容区模板负责侧边栏分组导航sidenav_section宏、面包屑、正文区、上一篇/下一篇分页以及“On this page”目录theme/assets/site.js主题行为脚本包括主题切换、GitHub Star 数拉取缓存 1 小时离线时降级为普通链接、移动端侧边栏、代码块语言角标、TOC 滚动跟随、搜索遮罩层以及按需从 CDN 加载 Mermaid 渲染库theme/assets/site.css、tokens.css设计令牌与样式定义。因此若你贡献的内容涉及页面级 UI 调整改动点应在theme/下而纯内容贡献只修改src/下的 Markdown 即可。多仓库站点组装make-full-website.sh 的协作机制Lance 的完整文档站并不只来自本仓库还聚合了 lance-namespace、lance-namespace-impls、lance-spark、lance-ray、lance-trino、lance-duckdb、lance-huggingface、lance-context 等多个相关仓库的文档。docs/make-full-website.sh 负责把本地这些 checkout 中的文档复制进docs/src/对应目录支持通过环境变量覆盖各仓库路径例如LANCE_NAMESPACE_REPO、LANCE_SPARK_REPO、LANCE_RAY_REPO、LANCE_DUCKDB_REPO等默认值指向$HOME/oss/下的同名目录每个仓库都有独立的复制/跳过逻辑源目录存在则复制copy_docs_dir、copy_file_if_exists不存在则仅打印警告并保留占位文档warn_missing_repo复制完成后会动态改写各目录的.pages导航文件如integrations/、community/project-specific/把外部仓库的页面按顺序并入站点导航最后还会把仓库根目录的 CONTRIBUTING.md、release_process.md、rust/CONTRIBUTING.md、python/CONTRIBUTING.md 以及 docs/CONTRIBUTING.md 分别复制为社区页下的general.md、release.md、rust.md、python.md、docs.md。与之配套的 docs/clean-full-website.sh 会先清理上一次组装留下的外部内容再重建各处的占位页如 catalog、namespace 规范页保证在缺少外部 checkout 时make build/make serve依然可运行。这也是make serve必须先经过make-full-website的原因。构建期钩子PMC 花名册自动生成docs/hooks/pmc_roster.py 是一个 MkDocs 构建钩子它以 docs/src/community/pmc.yaml 为唯一事实来源在页面渲染阶段查找!-- PMC_ROSTER_TABLE --占位符并替换为自动生成的 Markdown 表格列为 Name、GitHub Handle、Affiliation、Ecosystem Roles。这样社区页的花名册永远不需要手工维护与 CI 中格式规范投票门禁共用同一份数据源。钩子通过 docs/mkdocs.yml 中的hooks:注册。文档质量保障链接检查与依赖维护链接检查运行make check-links底层是uv run mkdocs-linkcheck src即可扫描全部 Markdown 中的损坏链接适合在提交前自检新增依赖使用uv add package普通依赖或uv add --dev package开发依赖更新 docs/pyproject.toml必要时make sync重新同步依赖升级uv add packagelatest升级单个包uv sync --upgrade全量升级代码块质量[tool.ruff]配置会把*.md乃至*.ipynb纳入检查范围对文档中的 Python 代码块执行 E/F/UP/B/SIM/I 系列 lint忽略 E501 行长度确保文档示例代码可直接运行。Python、Rust、Java API 文档的构建与发布主站之外三类语言 SDK 的 API 文档各自独立构建与发布Python由独立的 lance-python-doc 工程使用 Sphinx 构建以 ReadTheDocs 风格发布到 GitHub Pages。因此 Python API 文档的改动属于独立仓库的职责不在本仓库docs/中维护RustRust crate 文档作为发布流程的一部分构建并发布到 docs.rs 的lancecrate 页面即在发布版本时自动生成JavaJava 文档在构建后发布到 Maven Central可通过 javadoc.io 按项目查看对应 Javadoc 页面。对于普通贡献者而言若要修改主站内容只需在src/下编辑 Markdown 并运行本地预览即可若要参与 API 文档需前往各自对应的独立工程。贡献文档的推荐工作流结合以上机制向 Lance 主站贡献文档的完整流程可总结为安装 uv进入docs/执行uv sync --dev同步依赖视需要设置各LANCE_*_REPO环境变量指向本地外部仓库 checkout否则使用占位文档运行make serve启动本地预览确认改动渲染正确在docs/src/下修改 Markdown涉及导航顺序时同步更新对应目录的.pages文件运行make check-links检查链接完整性提交前确认 docs/CONTRIBUTING.md 中列出的构建与发布约定未被破坏。遵循上述流程即可在不依赖外部站点的前提下完成 Lance 主站文档从编写、本地验证到提交的全过程。【免费下载链接】lanceOpen Lakehouse Format for Multimodal AI. Convert from Parquet in 2 lines of code for 100x faster random access, vector index, and data versioning. Compatible with Pandas, DuckDB, Polars, Pyarrow, and PyTorch with more integrations coming..项目地址: https://gitcode.com/GitHub_Trending/la/lance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考