7

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

4

2 回答 2

14

以下是如何自动部署您的 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

  • 场景 2：主题无法通过 pip 安装（例如docskimmer）

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

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

    对于doskimmer，该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

后记

你完成了！请随时在评论中问我任何问题。

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

于 2018-06-16T21:45:09.673 回答
0

使用 Travis 部署 MkDocs 网站非常简单（考虑到您使用的是材料主题）

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

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

第 3 步：从 dev 分支向 master 提出 pull request

第 4 步：登录 Travis 并在那里连接您的存储库，在 travis 中添加环境变量 'git_token'（在 .travis.yml 中使用）它的值可以从 github.com -> settings-> dev settings -> 个人访问令牌中获取。

第 5 步：完成/合并对 master 的拉取请求。它将触发 web-hook 并且 Travis 将开始构建。构建后，您生成的 html 文件将被推送到 gh-pages 分支。

第 6 步：转到存储库设置并设置 git-hub pages 网站以从 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
于 2019-06-05T06:55:28.130 回答