LlamaIndex 文档本地构建实战Poetry MkDocs API 参考自动生成流水线【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文以 LlamaIndex 仓库的 文档目录说明 为主体完整还原在其docs目录下本地构建、预览 LlamaIndex 官方文档docs.llamaindex.ai的全套操作流程并深入 构建准备脚本 与 MkDocs 主配置讲清楚--skip-notebooks、--skip-reference等构建选项的作用以及 API 参考页面是如何从数百个集成包的pyproject.toml自动生成的。读完本文你可以在本地完整跑起 LlamaIndex 文档的构建服务并理解文档导航与 API 参考保持同步的机制。一、文档工程的结构与独立构建环境docs目录包含 LlamaIndex 文档的完整源码最终产物即线上文档站点。目录职责大致如下docs/api_reference/API 参考的 MkDocs 工程mkdocs.yml、依赖声明与生成的 API 参考页面都在这里docs/examples/大量 Notebook 示例构建时会被转换为文档页面Agent、Embeddings、LLM、Vector Stores、Workflow 等分类目录docs/scripts/构建工具脚本docs/src/content/文档正文内容框架指南、模块指南等。需要特别注意的是文档拥有自己独立的 Python 虚拟环境。LlamaIndex 各包如llama-index-core使用的依赖与文档构建依赖完全隔离避免互相污染。文档工程的依赖声明在 docs/api_reference/pyproject.toml 中关键信息如下要求python ^3.11构建文档的 Python 环境需为 3.11 及以上核心构建工具是mkdocs ^1.6.1配套插件包括mkdocs-material主题、mkdocs-jupyterNotebook 转文档页面、mkdocstringsPython API 文档抽取启用pythonextra、mkdocs-autorefs、mkdocs-include-dir-to-nav、mkdocs-render-swagger-plugin、mkdocs-redirects等额外依赖griffe-fieldz用于从源码抽取 Pydantic 字段信息以及本地路径依赖llama-index-instrumentation {path ../../llama-index-instrumentation}说明 API 参考生成时还需要能 import 到本地源码包声明了三个 Poetry 入口命令[tool.poetry.scripts] merge-external-docs scripts.merge_external_docs:main prepare-for-build scripts.prepare_for_build:main serve scripts.serve:main这三个命令正是文档构建流程的全部操作面拉取外部文档、准备构建配置、启动构建服务。二、本地构建文档的完整流程以下流程均假设当前工作目录位于仓库的docs目录内原文档强调从现在起所有命令都从docs目录执行。2.1 获取仓库并进入 docs 目录git clone https://gitcode.com/GitHub_Trending/ll/llama_index.git cd llama_index cd llama_index/docs2.2 安装文档构建依赖先安装 Poetry用于管理包依赖然后在docs目录下执行poetry install该命令会按pyproject.toml声明安装构建文档所需的全部依赖主要是mkdocs及其扩展插件并创建文档专属的虚拟环境。2.3 拉取外部文档文档站点中有一部分页面来自仓库外部如实验性包等构建前需要先同步进来poetry run python scripts/merge_external_docs.py对应的入口定义在 pyproject.toml 的merge-external-docs脚本命令中。2.4 启动构建服务poetry run servepoetry run serve构建过程中所有 Notebook 示例会被mkdocs-jupyter等插件转换为文档页面docs/examples/ 下有数百个 Notebook仅llm分类就近百个因此完整构建需要数分钟。两个可显著缩短构建时间的选项选项作用适用场景--skip-notebooks跳过 Notebook 到文档页面的转换不修改Examples示例部分时的日常开发--skip-reference跳过 API 参考页的生成只关注正文内容、不需要刷 API 文档时组合使用可做最小化构建poetry run serve --skip-notebooks # 只跳过 Notebook 转换 poetry run serve --skip-reference # 只跳过 API 参考生成 poetry run serve --skip-notebooks --skip-reference # 最小化构建2.5 确认构建完成后再打开浏览器构建耗时较长必须等到终端出现如下输出再打开浏览器... INFO - Documentation built in 53.32 seconds INFO - [16:18:17] Watching paths for changes: docs INFO - [16:18:17] Serving on http://127.0.0.1:8000/en/stable/出现Watching paths for changes说明已进入热重载监听状态此后每次修改文档文件本地服务都会自动重新构建并刷新浏览器页面开发体验类似前端 dev server。浏览器访问http://localhost:8000/即可查看生成的文档站点。三、prepare-for-buildmkdocs.yml 与 API 参考的自动同步机制原文档在Configuration一节指出mkdocs.yml的一部分配置由脚本自动生成用于保持示例与全仓库所有包的 API 参考同步。执行方式poetry run prepare-for-build提示原文档原话作为普通贡献者你通常不需要亲自运行该脚本如需改动可在 PR 中寻求维护者协助。下面结合 prepare_for_build.py 的源码解析它到底做了什么。3.1 扫描集成包的pyproject.toml脚本维护了一个待扫描的集成目录列表INTEGRATION_FOLDERSINTEGRATION_FOLDERS [ ../llama-index-packs, ../llama-index-integrations, ] EXCLUDED_INTEGRATION_FOLDERS [ llama-index-integrations/agent, ]它遍历这些目录下的每一个pyproject.toml自动跳过.venv与被排除的 agent 目录从其中的[tool.llamahub]表读取两个关键键import_path该集成包对外暴露的 Python 导入路径如llama_index.vector_stores.chromaclass_authors需要生成 API 参考页的公开类列表。3.2 生成 API 参考 Markdown 页面对每个包脚本按模板拼装出一个 MkDocs 的 mkdocstrings 入口文件API_REF_TEMPLATE ::: {import_path} options: members: {members} API_REF_MEMBER_TEMPLATE - {member}生成路径由import_path推导取包名中间段作为目录名模块名加.md作为文件名。存在三类特殊目录映射import_path 中间段生成目录vector_storesapi_reference/api_reference/storage/vector_storeindices/managedapi_reference/api_reference/indicesgraph_storesapi_reference/api_reference/storage/graph_stores实际产物可以验证例如 chroma.md 的全部内容就是::: llama_index.vector_stores.chroma options: members: - ChromaVectorStore即一行 mkdocstrings 指令从llama_index.vector_stores.chroma模块抽取ChromaVectorStore类的文档。docs/api_reference/api_reference/ 目录下按分类存有约七百七十九个这样的生成页面含 core、integrations 各包的 llms、embeddings、readers、vector_stores 等全部由该脚本产出。3.3 回写 mkdocs.yml 的 mkdocstrings 搜索路径生成页面后脚本还会遍历mkdocs.yml中的plugins找到mkdocstrings插件把本次扫描到的每个包路径追加进handlers.python.paths若尚不存在for search_path in search_paths: if search_path not in mkdocs[plugins][i][mkdocstrings][handlers][python][paths]: mkdocs[plugins][i][mkdocstrings][handlers][python][paths].append(search_path)最终用yaml.dump回写 docs/api_reference/mkdocs.yml。查看该文件可以看到效果paths列表从../../llama-index-core、../../llama-index-instrumentation开始随后列出数百个../../llama-index-integrations/...的具体包路径——这正是 mkdocstrings 能import 到各集成包的依据。该文件中与 API 抽取质量直接相关的核心配置值得留意- mkdocstrings: handlers: python: options: docstring_style: google # 按 Google 风格解析 docstring docstring_options: ignore_init_summary: true extensions: - griffe_fieldz # 抽取 Pydantic 模型字段 filters: - !^_ # 过滤下划线开头的私有成员 - !^__init__ members_order: source # 按源码定义顺序展示成员 separate_signature: true show_signature_annotations: true3.4 同步 CHANGELOG脚本末尾还有一个收尾动作把仓库根目录的CHANGELOG.md拷贝为docs/src/content/docs/framework/CHANGELOG.md并将# ChangeLog标题替换为 Astro 风格的 frontmatter 头---\ntitle: ChangeLog\n---保证文档站上的变更日志页面格式正确。3.5 导航标签的组织同一脚本还维护了两张目录 → 导航标签映射表FOLDER_NAME_TO_LABEL37 个docs/examples子目录如./examples/agent→Agents、./examples/llm→LLMs、./examples/workflow→Workflow与INTEGRATION_FOLDER_TO_LABEL60 余个集成分类如vector_stores之外的retrievers→Retrievers、storage→Storage、voice_agents→Voice Agents。结合include_dir_to_nav插件文档站的导航结构即由这些目录结构自动推导而来——这也是新增示例目录时需要关注标签映射的原因。四、适用前提与注意事项Python 版本文档构建环境要求 3.11见 pyproject.toml 的python ^3.11。构建耗时完整构建因 Notebook 转换需要一段时间非 Examples 方向的开发者应优先使用--skip-notebooks必要时叠加--skip-reference做最小化构建。热重载服务进入Watching paths for changes: docs状态后自动重建无需手动刷新构建判断构建就绪的唯一可靠信号是Documentation built in ...日志。prepare-for-build的定位它面向维护者用于新增集成包后刷新mkdocs.yml与 API 参考页普通文档贡献者一般直接改docs/src/content下正文由 PR 流程中的维护者代为刷新参考。依赖本机源码包mkdocstrings 需要真实 import 各包源码paths均指向仓库内相对路径因此文档构建必须发生在完整克隆的仓库内而不是单独拉取docs目录。五、关键文件索引文件作用docs/DOCS_README.md文档本地构建指南本文主体docs/api_reference/pyproject.toml文档独立环境的依赖与 Poetry 命令声明docs/scripts/prepare_for_build.py生成 API 参考页、回写 mkdocstrings 路径、同步 CHANGELOGdocs/api_reference/mkdocs.ymlMkDocs 主配置插件、主题、搜索路径docs/api_reference/api_reference/脚本生成的 API 参考页面集合docs/examples/构建时转换为文档页的 Notebook 示例【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LlamaIndex 文档本地构建实战：Poetry + MkDocs + API 参考自动生成流水线
LlamaIndex 文档本地构建实战Poetry MkDocs API 参考自动生成流水线【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文以 LlamaIndex 仓库的 文档目录说明 为主体完整还原在其docs目录下本地构建、预览 LlamaIndex 官方文档docs.llamaindex.ai的全套操作流程并深入 构建准备脚本 与 MkDocs 主配置讲清楚--skip-notebooks、--skip-reference等构建选项的作用以及 API 参考页面是如何从数百个集成包的pyproject.toml自动生成的。读完本文你可以在本地完整跑起 LlamaIndex 文档的构建服务并理解文档导航与 API 参考保持同步的机制。一、文档工程的结构与独立构建环境docs目录包含 LlamaIndex 文档的完整源码最终产物即线上文档站点。目录职责大致如下docs/api_reference/API 参考的 MkDocs 工程mkdocs.yml、依赖声明与生成的 API 参考页面都在这里docs/examples/大量 Notebook 示例构建时会被转换为文档页面Agent、Embeddings、LLM、Vector Stores、Workflow 等分类目录docs/scripts/构建工具脚本docs/src/content/文档正文内容框架指南、模块指南等。需要特别注意的是文档拥有自己独立的 Python 虚拟环境。LlamaIndex 各包如llama-index-core使用的依赖与文档构建依赖完全隔离避免互相污染。文档工程的依赖声明在 docs/api_reference/pyproject.toml 中关键信息如下要求python ^3.11构建文档的 Python 环境需为 3.11 及以上核心构建工具是mkdocs ^1.6.1配套插件包括mkdocs-material主题、mkdocs-jupyterNotebook 转文档页面、mkdocstringsPython API 文档抽取启用pythonextra、mkdocs-autorefs、mkdocs-include-dir-to-nav、mkdocs-render-swagger-plugin、mkdocs-redirects等额外依赖griffe-fieldz用于从源码抽取 Pydantic 字段信息以及本地路径依赖llama-index-instrumentation {path ../../llama-index-instrumentation}说明 API 参考生成时还需要能 import 到本地源码包声明了三个 Poetry 入口命令[tool.poetry.scripts] merge-external-docs scripts.merge_external_docs:main prepare-for-build scripts.prepare_for_build:main serve scripts.serve:main这三个命令正是文档构建流程的全部操作面拉取外部文档、准备构建配置、启动构建服务。二、本地构建文档的完整流程以下流程均假设当前工作目录位于仓库的docs目录内原文档强调从现在起所有命令都从docs目录执行。2.1 获取仓库并进入 docs 目录git clone https://gitcode.com/GitHub_Trending/ll/llama_index.git cd llama_index cd llama_index/docs2.2 安装文档构建依赖先安装 Poetry用于管理包依赖然后在docs目录下执行poetry install该命令会按pyproject.toml声明安装构建文档所需的全部依赖主要是mkdocs及其扩展插件并创建文档专属的虚拟环境。2.3 拉取外部文档文档站点中有一部分页面来自仓库外部如实验性包等构建前需要先同步进来poetry run python scripts/merge_external_docs.py对应的入口定义在 pyproject.toml 的merge-external-docs脚本命令中。2.4 启动构建服务poetry run servepoetry run serve构建过程中所有 Notebook 示例会被mkdocs-jupyter等插件转换为文档页面docs/examples/ 下有数百个 Notebook仅llm分类就近百个因此完整构建需要数分钟。两个可显著缩短构建时间的选项选项作用适用场景--skip-notebooks跳过 Notebook 到文档页面的转换不修改Examples示例部分时的日常开发--skip-reference跳过 API 参考页的生成只关注正文内容、不需要刷 API 文档时组合使用可做最小化构建poetry run serve --skip-notebooks # 只跳过 Notebook 转换 poetry run serve --skip-reference # 只跳过 API 参考生成 poetry run serve --skip-notebooks --skip-reference # 最小化构建2.5 确认构建完成后再打开浏览器构建耗时较长必须等到终端出现如下输出再打开浏览器... INFO - Documentation built in 53.32 seconds INFO - [16:18:17] Watching paths for changes: docs INFO - [16:18:17] Serving on http://127.0.0.1:8000/en/stable/出现Watching paths for changes说明已进入热重载监听状态此后每次修改文档文件本地服务都会自动重新构建并刷新浏览器页面开发体验类似前端 dev server。浏览器访问http://localhost:8000/即可查看生成的文档站点。三、prepare-for-buildmkdocs.yml 与 API 参考的自动同步机制原文档在Configuration一节指出mkdocs.yml的一部分配置由脚本自动生成用于保持示例与全仓库所有包的 API 参考同步。执行方式poetry run prepare-for-build提示原文档原话作为普通贡献者你通常不需要亲自运行该脚本如需改动可在 PR 中寻求维护者协助。下面结合 prepare_for_build.py 的源码解析它到底做了什么。3.1 扫描集成包的pyproject.toml脚本维护了一个待扫描的集成目录列表INTEGRATION_FOLDERSINTEGRATION_FOLDERS [ ../llama-index-packs, ../llama-index-integrations, ] EXCLUDED_INTEGRATION_FOLDERS [ llama-index-integrations/agent, ]它遍历这些目录下的每一个pyproject.toml自动跳过.venv与被排除的 agent 目录从其中的[tool.llamahub]表读取两个关键键import_path该集成包对外暴露的 Python 导入路径如llama_index.vector_stores.chromaclass_authors需要生成 API 参考页的公开类列表。3.2 生成 API 参考 Markdown 页面对每个包脚本按模板拼装出一个 MkDocs 的 mkdocstrings 入口文件API_REF_TEMPLATE ::: {import_path} options: members: {members} API_REF_MEMBER_TEMPLATE - {member}生成路径由import_path推导取包名中间段作为目录名模块名加.md作为文件名。存在三类特殊目录映射import_path 中间段生成目录vector_storesapi_reference/api_reference/storage/vector_storeindices/managedapi_reference/api_reference/indicesgraph_storesapi_reference/api_reference/storage/graph_stores实际产物可以验证例如 chroma.md 的全部内容就是::: llama_index.vector_stores.chroma options: members: - ChromaVectorStore即一行 mkdocstrings 指令从llama_index.vector_stores.chroma模块抽取ChromaVectorStore类的文档。docs/api_reference/api_reference/ 目录下按分类存有约七百七十九个这样的生成页面含 core、integrations 各包的 llms、embeddings、readers、vector_stores 等全部由该脚本产出。3.3 回写 mkdocs.yml 的 mkdocstrings 搜索路径生成页面后脚本还会遍历mkdocs.yml中的plugins找到mkdocstrings插件把本次扫描到的每个包路径追加进handlers.python.paths若尚不存在for search_path in search_paths: if search_path not in mkdocs[plugins][i][mkdocstrings][handlers][python][paths]: mkdocs[plugins][i][mkdocstrings][handlers][python][paths].append(search_path)最终用yaml.dump回写 docs/api_reference/mkdocs.yml。查看该文件可以看到效果paths列表从../../llama-index-core、../../llama-index-instrumentation开始随后列出数百个../../llama-index-integrations/...的具体包路径——这正是 mkdocstrings 能import 到各集成包的依据。该文件中与 API 抽取质量直接相关的核心配置值得留意- mkdocstrings: handlers: python: options: docstring_style: google # 按 Google 风格解析 docstring docstring_options: ignore_init_summary: true extensions: - griffe_fieldz # 抽取 Pydantic 模型字段 filters: - !^_ # 过滤下划线开头的私有成员 - !^__init__ members_order: source # 按源码定义顺序展示成员 separate_signature: true show_signature_annotations: true3.4 同步 CHANGELOG脚本末尾还有一个收尾动作把仓库根目录的CHANGELOG.md拷贝为docs/src/content/docs/framework/CHANGELOG.md并将# ChangeLog标题替换为 Astro 风格的 frontmatter 头---\ntitle: ChangeLog\n---保证文档站上的变更日志页面格式正确。3.5 导航标签的组织同一脚本还维护了两张目录 → 导航标签映射表FOLDER_NAME_TO_LABEL37 个docs/examples子目录如./examples/agent→Agents、./examples/llm→LLMs、./examples/workflow→Workflow与INTEGRATION_FOLDER_TO_LABEL60 余个集成分类如vector_stores之外的retrievers→Retrievers、storage→Storage、voice_agents→Voice Agents。结合include_dir_to_nav插件文档站的导航结构即由这些目录结构自动推导而来——这也是新增示例目录时需要关注标签映射的原因。四、适用前提与注意事项Python 版本文档构建环境要求 3.11见 pyproject.toml 的python ^3.11。构建耗时完整构建因 Notebook 转换需要一段时间非 Examples 方向的开发者应优先使用--skip-notebooks必要时叠加--skip-reference做最小化构建。热重载服务进入Watching paths for changes: docs状态后自动重建无需手动刷新构建判断构建就绪的唯一可靠信号是Documentation built in ...日志。prepare-for-build的定位它面向维护者用于新增集成包后刷新mkdocs.yml与 API 参考页普通文档贡献者一般直接改docs/src/content下正文由 PR 流程中的维护者代为刷新参考。依赖本机源码包mkdocstrings 需要真实 import 各包源码paths均指向仓库内相对路径因此文档构建必须发生在完整克隆的仓库内而不是单独拉取docs目录。五、关键文件索引文件作用docs/DOCS_README.md文档本地构建指南本文主体docs/api_reference/pyproject.toml文档独立环境的依赖与 Poetry 命令声明docs/scripts/prepare_for_build.py生成 API 参考页、回写 mkdocstrings 路径、同步 CHANGELOGdocs/api_reference/mkdocs.ymlMkDocs 主配置插件、主题、搜索路径docs/api_reference/api_reference/脚本生成的 API 参考页面集合docs/examples/构建时转换为文档页的 Notebook 示例【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
