python - 在 Travis CI 中自动构建 Mkdocs 文档

Question

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

Answer 1

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

第一步

只需将以下代码片段插入到您的 .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

第二步

如果您使用的 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

  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.

第三步

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

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

后记

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

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