Traefik 贡献文档

文档

了解如何使用功能时，功能会更好

你发现文档中有不清楚的地方并想尝试更好地解释它？ 让我们看看如何做。

构建文档

通用

此文档 使用 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

默认 URL

你的本地文档服务器默认在 http://127.0.0.1:8000 上运行。

如果只想构建文档而不在本地服务它，可以使用以下命令：

$ 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

检查文档

要检查文档是否符合标准期望（无死链接、html 标记有效性等），请使用 docs-verify 目标。

$ 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 来禁用验证：

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