在 Travis CI 中自动构建 Mkdocs 文档

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或readthedocs的 mkdocs 主题，请按照以下步骤进行安装：

• 场景 1：主题可以通过 pip 安装(例如 mkdocs-material(

  1. 将pip install mkdocs与您需要安装的其他软件包一起附加，例如mkdocs-material它将pip install mkdocs mkdocs-material pymdown-extensions pygments

• 场景 2：主题无法通过 pip 安装(例如文档撇渣器(

  1. 从mkdocs build --verbose --clean --strict中删除--strict参数，以禁止使用无法通过 pip 安装的主题时可能出现的错误。

  2. 在上面的before_deploy部分添加设置主题所需的代码mkdocs build --verbose --clean

  对于文档撇渣器，before_deploy部分中的代码如下所示：

  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
  

  无法通过 pip 安装的主题可能会有所不同。

步骤 3

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

1. 如果已设置具有public_repo范围的个人访问令牌，请跳到步骤 11
2. 转到此网址。如果已加载，请跳至步骤 7。否则，请像往常一样继续执行这些说明。
3. 转到您的 Github 帐户的设置
4. 点击开发者设置
5. 单击"个人访问令牌">
6. 点击生成新令牌
7. 您可能需要输入您的 GitHub 密码来授权创建
8. 在Token description下，为您的令牌选择一个名称 - 它可以是任何内容;我会将其命名为类似Travis CI，因为您可以根据需要为任意数量的存储库重复使用令牌。
9. 启用public_repo和repo_deployment范围/权限
10. 单击页面底部的Generate token
11. 转到要为其构建 Mkdocs 文档的 Travis CI 存储库的设置
12. 使用以下设置创建环境变量：
    • 姓名：github_token
    • 值：<THE TOKEN YOU JUST GENERATED>
    • 在构建日志中显示值：No
13. 单击"add

后记

大功告成！请随时在评论中问我任何问题。

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

Answer 2

使用 Travis 部署您的 MkDocs 网站非常简单 (认为您正在使用材料主题(

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

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

步骤 3：从开发分支向主节点提出拉取请求

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

第 5 步：完成/合并拉取请求到主服务器。它将触发网络钩子，特拉维斯将开始构建。构建后，生成的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