文档¶

懂得使用，功能才能发挥价值

发现文档中的某处说明不够清楚，想尝试解释得更好？ 下面介绍具体方法。

构建文档¶

概述¶

这份文档使用 MkDocs构建。

方法 1：Docker 与 make¶

请确保已安装以下依赖：

• Docker

使用 docs-serve 目标，即可构建文档并在本地测试（支持实时重新加载）：

$ make docs-serve
docker build -t traefik-docs -f docs.Dockerfile .
# […]
docker run  --rm -v /home/user/go/github/traefik/traefik:/mkdocs -p 8000:8000 traefik-docs mkdocs serve
# […]
[I 170828 20:47:48 server:283] Serving on http://0.0.0.0:8000
[I 170828 20:47:48 handlers:60] Start watching changes
[I 170828 20:47:48 handlers:62] Start detecting changes

如果只想构建文档，不需要在本地提供服务，可以使用以下命令：

$ make docs-build
...

方法 2：MkDocs¶

请确保已安装以下依赖：

• Python
• pip

$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2

然后通过 pip 安装 MkDocs。

pip install --user -r requirements.txt

从根目录运行 mkdocs serve，即可在本地构建文档并提供服务。 此命令会启动一个本地服务器。

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160505 22:31:24 server:281] Serving on http://127.0.0.1:8000
[I 160505 22:31:24 handlers:59] Start watching changes
[I 160505 22:31:24 handlers:61] Start detecting changes

检查文档¶

使用 docs-verify 目标检查文档是否符合标准要求（没有失效链接、HTML 标记有效等）。

$ make docs-verify
docker build -t traefik-docs-verify ./script/docs-verify-docker-image ## Build Validator image
...
docker run --rm -v /home/travis/build/traefik/traefik:/app traefik-docs-verify ## Check for dead links and w3c compliance
=== Checking HTML content...
Running ["HtmlCheck", "ImageCheck", "ScriptCheck", "LinkCheck"] on /app/site/basics/index.html on *.html...

$ make docs
...

DOCS_VERIFY_SKIP=true make docs-verify
...
DOCS_LINT_SKIP is true: no linting done.