使用 MkDocs 自动化 GitHub 页面构建

所以我联系了Travis的支持团队，他们告诉我另一个很酷的技巧：$TRAVIS_TEST_RESULT变量指示script部分的当前退出状态；我们可以在script部分的最后一行进行测试，以有条件地安装资产！

因此，我们最终在script下有一行来安装资产，在after_success下有另一行来执行实际构建。它们可能会合并，但我选择不合并：我不希望构建文档的结果导致构建失败。我希望有一天缓存会在构建结束时发生，这样我们就可以将它们都放在after_success下。

环境变量

这会导致环境变量。为了确定是否需要构建文档，我们可以使用仅为我们要构建的环境设置的环境变量。因为我做的大多数项目都是PHP，所以我们必须选择要使用的矩阵中的哪个版本。我们的项目在PHP5.5、5.6、7.0和HHVM上进行测试。由于我们的大多数用户都使用PHP5版本，因此我们决定在最新的稳定版本5上编写文档：5.6。

我们也只想在主分支上构建，不作为拉取请求的一部分；如果针对该分支发出拉取请求，则该分支报告为master，这就是标准如此具体的原因。

最后，我知道我最终会安装MkDocs。由于我们使用的是基于Travis的Docker构建，我也知道这意味着我将使用pipinstall--user而不是通过apt-get安装MkDocs，因为我们没有root访问权限.这意味着MkDocs将在$HOME/.local/bin中，所以我需要为我构建的环境更新我的$PATH。

幸运的是，您可以在.travis.yml中声明作为计算结果的env变量声明。这意味着我最终得到了以下构建矩阵：

matrix:
  fast_finish: true
  include:
    - php: 5.5
      env:
        - EXECUTE_CS_CHECK=true
    - php: 5.6
      env:
        - EXECUTE_TEST_COVERALLS=true
        - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
        - PATH="$HOME/.local/bin:$PATH"
    - php: 7
    - php: hhvm
  allow_failures:
    - php: hhvm

这将创建一个新的$DEPLOY_DOCS环境变量，其值为“true”或“false”，稍后我可以对其进行测试。我的$PATH也更新了。

以上是构建特定的变量。但是，我还需要一些可以被scipts访问的变量：

• 我希望能够为我的mkdocs配置提供基本站点URL。默认情况下，我们不将其包含在mkdocs.yml中，因此您可以在本地构建。但是，对于我们的生产页面，我们需要它来确保搜索功能正常工作，因为我们将在子路径中。
• 为了通过git提交，git需要用户名和电子邮件。我的经验还表明，这些需要与生成个人访问令牌的用户相匹配。
• 因为我们希望功能可重复使用，所以我还需要提供git存储库的位置。

因此，我在env.global部分添加了以下内容：

env:
  global:
    - SITE_URL: https://organization.github.io/repository
    - GH_USER_NAME: "My Full Name"
    - GH_USER_EMAIL: me@domain.tld
    - GH_REF: github.com/organization/repository.git
    - secure: "..."

GH_REF是对正在使用的github存储库的引用。您会注意到URL缺少方案；这是因为用于将提交推送到gh-pages分支的脚本将使用GH_TOKEN创建完整的URL：

git remote add upstream https://${GH_TOKEN}@${GH_REF}

现在环境已经全部设置好，我们可以开始安装主题并构建文档了。

如何安装？

为了使用我们的自定义主题构建文档，我们需要在本地自定义主题。此外，我们可能希望仅在有更改时才下载主题；我们应该在请求之间缓存它。此外，如果资产未缓存，我们应该不下载它们，除非构建成功。

坦率地说，这是最难弄清楚的部分之一，我最终需要Travis支持团队的一些指导才能弄清楚。（感谢伟大的指点，你们这些Travis的好人！）

如前所述，缓存会在script部分执行后立即发生。这排除了此任务的after_success脚本，因为随后下载的任何资产都不会被缓存。但是我们如何知道构建何时成功？

如前所述，环境变量TRAVIS_TEST_RESULT保存构建的退出值。如果脚本的任何部分返回非零值，则该值将从该点向前变为非零。因此，如果我们在测试此值的script部分的末尾放置一个脚本，我们就可以有条件地触发一个动作！

我选择在我们的主题存储库中创建一个脚本，其中包含我们文档工具链安装的所有逻辑。这允许我们根据需要修改安装脚本，而无需更新将添加自动化的各种组件。该脚本目前看起来像这样：

#!/usr/bin/env bash
pip install --user mkdocs
pip install --user pymdown-extensions
if [[ ! -d zf-mkdoc-theme/theme ]];then
    mkdir -p zf-mkdoc-theme ;
    curl -s -L https://github.com/zendframework/zf-mkdoc-theme/releases/latest | egrep -o '/zendframework/zf-mkdoc-theme/archive/[0-9]*\.[0-9]*\.[0-9]*\.tar\.gz' | head -n1 | wget -O zf-mkdoc-theme.tgz --base=https://github.com/ -i - ;
    (
        cd zf-mkdoc-theme ;
        tar xzf ../zf-mkdoc-theme.tgz --strip-components=1 ;
    );
fi

exit 0

上面运行我们的pipinstall命令来安装MkDocs和我们使用的扩展，如果主题目录丢失，识别并下载主题的最新tarball并将其解压缩。

我遇到的一个陷阱：当您启用目录缓存时，Travis会创建该目录，即使没有找到它的缓存条目；因此，我们需要测试目录下的路径。

我遇到的一个陷阱：当您启用目录缓存时，Travis会创建该目录，即使没有找到它的缓存条目；因此，我们需要测试目录下的路径。

现在，我们如何获取安装脚本？在我们的script部分中使用以下行：

script:
  - <build tasks>
  - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi

上面获取脚本并执行它，但前提是我们处于指定用于文档部署的环境中，并且构建到此为止已经成功。这应该始终是脚本部分的最后一行。

如何构建？

既然我们知道我们拥有构建工具，那么如何构建文档本身呢？

为此，我编写了一个部署脚本，我们将其包含在我们的主题存储库中。我们将其包含在主题中以实现可重用性，这是我们的要求之一。这确保了随着构建和部署的变化，我们不需要更新所有正在构建文档的存储库；我们可以在主题存储库中进行更改，标记新版本，然后在下一个构建中，每个版本都会采用更改。

部署脚本执行几项任务：

• 它创建构建目录，并使用GH_TOKEN和GH_HREF将其初始化为git存储库，并将上游设置为存储库的gh-pages分支。
• 它将git配置设置为使用配置的GitHub用户名和电子邮件。
• 它运行构建（它本身是另一个脚本）。
• 它添加了更改文件，提交它们，并将它们推送到远程。

最后，部署脚本如下所示：

#!/usr/bin/env bash
set -o errexit -o nounset

SCRIPT_PATH="$(cd "$(dirname "$0")" && pwd -P)"

# Get curent commit revision
rev=$(git rev-parse --short HEAD)

# Initialize gh-pages checkout
mkdir -p doc/html
(
    cd doc/html
    git init
    git config user.name "${GH_USER_NAME}"
    git config user.email "${GH_USER_EMAIL}"
    git remote add upstream "https://${GH_TOKEN}@${GH_REF}"
    git fetch upstream
    git reset upstream/gh-pages
)

# Build the documentation
${SCRIPT_PATH}/build.sh

# Commit and push the documentation to gh-pages
(
    cd doc/html
    touch .
    git add -A .
    git commit -m "Rebuild pages at ${rev}"
    git push -q upstream HEAD:gh-pages
)

脚本注释

• 我们在doc/html/中构建我们的文档，通过.gitignore，允许我们安全地克隆到该位置。
• gitadd-A.将删除以前跟踪但现在已删除的任何文件，并添加找到的任何新路径。这使得自动化变得更加简单，因为我们不需要担心添加、删除或重命名。

此外，您会注意到gitpush命令包括-q开关。这非常重要：如果您不包含它，命令输出将包含推送URL，其中包含GitHub令牌！同样，您不希望该值泄露，因此请采取措施确保它不会泄露！

#!/usr/bin/env bash
SCRIPT_PATH="$(cd "$(dirname "$0")" && pwd -P)"

# Update the mkdocs.yml
cp mkdocs.yml mkdocs.yml.orig
echo "site_url: ${SITE_URL}"
echo "markdown_extensions:" >> mkdocs.yml
echo "    - markdown.extensions.codehilite:" >> mkdocs.yml
echo "        use_pygments: False" >> mkdocs.yml
echo "    - pymdownx.superfences" >> mkdocs.yml
echo "theme_dir: zf-mkdoc-theme/theme" >> mkdocs.yml

mkdocs build --clean
mv mkdocs.yml.orig mkdocs.yml

# Make images responsive
echo "Making images responsive"
php ${SCRIPT_PATH}/img_responsive.php

# Replace landing page content
echo "Replacing landing page content"
php ${SCRIPT_PATH}/swap_index.php

$ echo "zf-mkdoc-theme/" >> .git/info/exclude
$ git clone zendframework/zf-mkdoc-theme
$ ./zf-mkdoc-theme/build.sh
$ php -S 0:8000 -t doc/html/

after_success:
  - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi

cache:
  directories:
    - $HOME/.local
    - zf-mkdoc-theme

sudo: false

language: php

cache:
  directories:
    - $HOME/.local
    - zf-mkdoc-theme

env:
  global:
    - SITE_URL: https://organization.github.io/repository
    - GH_USER_NAME: "Name of Committer"
    - GH_USER_EMAIL: me@domain.tld
    - GH_REF: github.com/zendframework/zend-expressive.git
    - secure: "..."

matrix:
  fast_finish: true
  include:
    - php: 5.6
      env:
        - EXECUTE_TEST_COVERALLS=true
        - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
        - PATH="$HOME/.local/bin:$PATH"

script:
  - build something
  - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi

after_success:
  - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi