在 Travis 中自动构建 Mkdocs 文档 CI

Question

我如何在 Travis CI 中自动部署我的 Mkdocs 文档？

Answer 1

以下是自动部署 mkdocs 文档的方法。只需按照以下 3 个步骤操作即可。

步骤 1

只需将以下代码片段插入到 .travis.yml 配置文件中的相应位置即可：

language: python # Set the build language to Python

python: 3.8 # Set the version of Python to use

branches: master # Set the branch to build from

install:
    - pip install mkdocs # Install the required dependencies

script: true # Skip script (Don't use this if one already exists)

before_deploy:
    - mkdocs build --verbose --clean --strict # Build a local version of the docs

deploy: # Deploy documentation to Github in the gh_pages branch
    provider: pages
    skip_cleanup: true
    github_token: $github_token
    local_dir: site
    on:
        branch: master

第 2 步

如果您使用的 mkdocs 主题不是 mkdocs 或 readthedocs，请按照以下步骤进行安装：

场景一：通过pip安装主题（如mkdocs-material）
1. 将 pip install mkdocs 附加到您需要安装的其他软件包，例如 mkdocs-material 它将是 pip install mkdocs mkdocs-material pymdown-extensions pygments

场景二：主题不可通过pip安装（如docskimmer）

从 mkdocs build --verbose --clean --strict 中删除 --strict 参数以抑制使用无法通过 pip 安装的主题可能导致的错误。
在 mkdocs build --verbose --clean
上方的 before_deploy 部分添加设置主题所需的代码

before_deploy 部分中的代码对于 docskimmer 如下所示：

  before_deploy:
      - git clone https://github.com/hfagerlund/mkdocs-docskimmer.git # Clone the repo hosting the code
      - cp -r $PWD/mkdocs-docskimmer/mkdocs_docskimmer . # Copy the required code to the repo root
      - cp -r $PWD/mkdocs-docskimmer/mkdocs_docskimmer/. ./docs # Copy the required code to the docs folder
      - mkdocs build --verbose --clean # Build a local version of the docs

Installation of themes not available via pip may vary.

步骤 3

最后步骤是告诉 Travis CI 登录您的 GitHub 帐户以推送更改所需的凭据：

如果您已经设置了 public_repo 范围的个人访问令牌，请跳至步骤 11
转到 this URL。如果加载，请跳至第 7 步。否则，照常继续执行这些说明。
转到您的 Github 帐户的 settings
点击Developer settings
点击Personal access tokens
点击Generate new token
您可能需要输入 GitHub 密码才能授权创建
在 Token description 下，为您的令牌选择一个名称 - 可以是任何名称；我将其命名为 Travis CI，因为您可以将令牌重复用于任意数量的存储库。
启用 public_repo 和 repo_deployment scope/permission
点击页面底部的Generate token
转到要为其构建 Mkdocs 文档的 Travis CI 存储库的设置
使用以下设置创建环境变量：
- 姓名：github_token
- 值：<THE TOKEN YOU JUST GENERATED>
- 构建日志中的显示值：No
点击add

后记

大功告成！有什么问题欢迎在评论区问我。

此外，如果该方法停止工作或不起作用，请在评论中告诉我，我会尽快修复它。

Answer 2

使用 Travis 部署 MkDocs 网站非常简单（考虑到您正在使用 material 主题）

第 1 步：为您的项目创建存储库，其中包含名为 master、dev、gh-pages 的 3 个空分支。

第 2 步：克隆存储库和本地并签出到开发分支。将您的 MkDocs 网站添加到本地的开发分支。将“/site”目录添加到 git-ignore。（即不要推送 .html）在 repo 中添加下面给出的 .travis.yml。将您的站点推送到开发分支。

第 3 步：从 dev 分支向 master 提出拉取请求

第 4 步：登录到 Travis 并在那里连接您的存储库，在 travis 中添加环境变量 'git_token'(used in .travis.yml) 它的值你可以得到从 github.com -> 设置 -> 开发设置 -> 个人访问令牌。

第 5 步：Complete/Merge 向 master.It 的拉取请求将触发 web-hook 并且 Travis 将开始 build.After 构建您生成的 html 文件将被推送到gh-pages支线。

第 6 步：转到存储库设置并设置 git-hub 页网站以从 gh-pages 分支加载。

完成

.travis.yml

language: python # Set the build language to Python

python: 3.6 # Set the version of Python to use

branches: master # Set the branch to build from

install:
    - pip install mkdocs mkdocs-material pymdown-extensions pygments # Install the required dependencies

script: true # Skip script (Don't use this if one already exists)

before_deploy:
    - mkdocs build --verbose --clean --strict # Build a local version of the docs

deploy: # Deploy documentation to Github in the gh_pages branch
    provider: pages
    skip_cleanup: true
    github_token: $github_token
    local_dir: site
    on:
        branch: master

在 Travis 中自动构建 Mkdocs 文档 CI

Auto-build an Mkdocs documentation in Travis CI

python

continuous-integration

travis-ci

mkdocs

步骤 1

第 2 步

步骤 3

后记