1. ghp-import 是什么：一行描述“文档 → 网站“

1. ghp-import 是什么一行描述文档 → 网站【免费下载链接】ghp-importEasily import docs to your gh-pages branch.项目地址: https://gitcode.com/gh_mirrors/gh/ghp-importghp-import是一个小巧的 Python 文档导入工具当前版本 2.1.0Apache 2.0 许可核心就是一个单文件模块 ghp_import.py。它做一件事把已构建好的文档目录整体写入仓库的gh-pages分支并推送到远端由 GitHub Pages 托管发布。相比手动切分支、复制文件再推送它的好处是无感知分支操作不用关心gh-pages分支当前状态调用一次即完成提交 推送命令行 库双模式既可以在 Makefile、CI 中作为ghp-import命令使用也可以作为 Python 库from ghp_import import ghp_import直接调用底层基于git fast-import整个目录只产生一个提交速度快、仓库不膨胀依赖极少唯一的运行时依赖是python-dateutil⚠️重要警告来自 README.md 的 Big Fat Warningghp-import 会销毁目标分支的现有内容然后整体替换。gh-pages分支应当 100% 由构建产物派生不要手工编辑其中的文件。使用prefix参数时只销毁该前缀目录下的内容。2. 一键安装两种方式任选# 方式一从 PyPI 安装推荐 pip install ghp-import # 方式二从源码安装 git clone https://gitcode.com/gh_mirrors/gh/ghp-import cd ghp-import pip install -e .项目 setup.py 中注册了控制台命令ghp-import ghp_import:main因此安装后既能用命令行也能用 Python API二者参数完全对应。3. 快速上手3 行 Python 完成文档发布前置条件只有一个Python 进程的当前工作目录必须位于你的仓库内ghp-import 会在当前仓库中操作 Git。from ghp_import import ghp_import ghp_import(docs, pushTrue)这一行代码等价于把docs/目录的全部文件写入gh-pages分支提交信息默认Update documentation并推送到origin/gh-pages。4. ghp_import 库 API 参数全表函数签名为ghp_import(srcdir, **kwargs)srcdir必填其余 11 个参数均可选且与命令行选项一一对应源码定义见 ghp_import.py 与 options()参数对应 CLI 选项默认值作用srcdirDIRECTORY必填已构建文档的路径必须是目录否则抛出GhpErrorbranch-bgh-pages写入的目标分支名remote-rorigin推送到的远端名称mesg-mUpdate documentation目标分支上的提交信息push-pFalse提交后是否推送到{remote}/{branch}prefix-xNone给每个文件加目录前缀仅清空该前缀下内容force-fFalse强制推送到远端no_history-oFalse丢弃父提交历史保持分支只有一个提交use_shell-sFalse通过 shell 调用 GitWindows 个别环境需要followlinks-lFalse添加文件时是否跟随符号链接cname-cNone在分支中写入指定域名的CNAME文件nojekyll-nFalse在分支中写入.nojekyll文件高频必会srcdir、push、branch、mesgghp_import( build/html, # Sphinx 构建产物目录 branchgh-pages, pushTrue, mesgUpdate docs [skip ci], # [skip ci] 可避免推送触发 CI )srcdir指向的是构建输出目录如 Sphinx 的build/html不是文档源码用户页 / 组织页从master分支托管此时需显式传branchmastermesg建议带上[skip ci]防止推送文档分支 → 触发 CI → 再次构建推送的循环进阶参数no_history、prefix、cname、nojekyllno_historyTrue官方强烈推荐每次导入都丢弃父历史gh-pages分支始终只有 1 个提交避免仓库体积随每次文档更新持续膨胀。设置后推送时自动附加--force见 ghp_import.py 的推送逻辑。prefixdocs把文档发布到分支的docs/子目录下适合一个仓库有多个子项目文档共用的场景且只有该前缀目录会被清空降低误删风险。cnamedocs.example.com自动写入CNAME文件配合自定义域名使用。⛔nojekyllTrue写入空文件.nojekyll禁止 GitHub Pages 用 Jekyll 处理你的静态文件含下划线的文件名、_config.yml等场景必备。use_shellTrue部分 Windows 环境需要经 shell 调用 Git 命令时开启。5. 异常处理捕获 GhpError所有可预期的错误都会抛出 GhpError常见触发点错误信息触发原因Not a directory: xxxsrcdir不是目录ghp_import.pyfatal: not a git repository等当前目录不在 Git 仓库内check_repo()Failed to rebase gh-pages branch.无法基于远端gh-pages分支建立提交ghp_import.pyfrom ghp_import import ghp_import, GhpError try: ghp_import(docs, pushTrue, no_historyTrue) except GhpError as e: print(文档导入失败, e.message)6. 文档构建脚本集成指南Makefile CIghp-import 的官方文档站本身就是用它发布的Makefile 里就是标准集成范例docs: python ./docs/build.py ghp-import $(DOCS_OPTS) docs/ -b $(DOCS_BRANCH) -r $(DOCS_REMOTE) -m Update docs [skip ci] -o模式拆解构建脚本先产出静态页面 → 再调用 ghp-import 导入发布两个步骤串成一条命令。在 CI 中集成的通用写法python -m sphinx docs/ build/html ghp-import -p -o -m Update docs [skip ci] build/html在 Python 构建脚本末尾调用库 API 的等价写法ghp_import(build/html, pushTrue, no_historyTrue, mesgUpdate docs [skip ci])三种方式可按场景混用本地开发用 Makefile流水线用命令行构建工具链内部直接用 Python API。7. 最佳实践与常见陷阱清单✅先备份首次使用ghp-import前对已有gh-pages分支做备份它会被整体覆盖✅始终带no_historyTrue/-o官方highly recommended防止仓库膨胀✅提交信息加[skip ci]避免文档推送触发 CI 循环✅gh-pages分支只放构建产物绝不手工编辑该分支多子项目共用仓库用prefix隔离各自的文档目录Windows 偶发 Git 调用问题尝试use_shellTrue/-s文档目录含符号链接开启followlinksTrue/-l8. 项目文件导航文件说明ghp_import.py核心实现ghp_import()主函数、GhpError异常、Git 封装setup.py打包元数据注册ghp-import命令行入口Makefile文档构建 发布脚本范例make docs一键更新文档站README.md完整用法说明与 Python 库调用示例docs/index.html.tmpl本项目自己的文档站 HTML 模板掌握以上参数与集成模式后你就把构建文档和发布文档打通了无论本地一键发布还是 CI 自动上线一行调用即可完成。【免费下载链接】ghp-importEasily import docs to your gh-pages branch.项目地址: https://gitcode.com/gh_mirrors/gh/ghp-import创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考