Documentation

当您知道如何使用功能时,这些功能会更好

您在文档中发现了一些不清楚的地方,想尝试更好地解释它吗? 让我们看看如何.

Building Documentation

General

文档是使用mkdocs构建的 .

Method 1: Docker and make

您可以使用docs目标构建文档并在本地进行测试(通过实时重新加载):

$ make docs
docker build -t traefik-docs -f docs.Dockerfile .
# […]
docker run  --rm -v /home/user/go/github/containous/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

预设网址

默认情况下,本地文档服务器将在http://127.0.0.1:8000上运行.

如果只想构建文档而不在本地提供文档,则可以使用以下命令:

$ make docs-build
...

Method 2: mkdocs

首先,请确保您已安装pythonpip .

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

然后,使用pip安装mkdocs.

pip install --user -r requirements.txt

要在本地构建文档并在本地mkdocs serve从根目录运行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

Check the Documentation

要检查文档是否符合标准期望(没有无效链接,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/containous/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-clean docs-verify
...

禁用文档验证

可以通过将环境变量DOCS_VERIFY_SKIP设置为true来禁用验证:

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