生成网站

我们目前使用常规的 Maven 构建，不仅可以生成项目产物，还用于生成项目网站。

为了提供内容，每个模块都可以拥有一个 src/site 目录。该目录中的内容会生成到对应模块的站点部分。

用于生成站点的 skin 并非默认的 Maven 皮肤之一，而是一个外观更为现代的皮肤，采用了：

Bootstrap（用于 CSS）
JQuery（用于 JavaScript 的各种效果）
Fontawesome（用于图标和符号）

不过我们无需操心这些细节，一切都已配置好并会自动生效。

站点内容本身由 asciidoc 文件（扩展名为 .adoc）生成，这是一种简洁却强大的标记语言。（详情参见 AsciiDoc 语法快速参考或 AsciiDoc 速查表）

除这些基础能力之外，构建还配置为使用 asciidoctor-diagram 插件从 ASCII 数据生成图像。

借助它，我们可以生成类似 S7 协议说明页面上那样的图片。

提供新内容

在 src/site 目录中有一个文件 site.xml，它通常用于控制菜单和站点的外观。

大部分设置继承自 plc4x-parent 模块，这也是它比其他模块更复杂的原因。

site.xml 文件是可选的。即使没有它，站点依然会被生成，只是没有任何导航菜单会链接到额外的内容。

因此，如果我们想为某个（希望并不存在的）Wombat PLC Protocol 新增一个页面，就需要创建一个名为：

index.adoc 的文件，放在 src/site/asciidoc/protocols/wombat 目录中。

例如内容如下：

= Wombat PLC Protocol

If you want to waste your money, brains and time, feel free to use a `Wombat PLC`.

In order to help you waste even more of that, we'll skip documenting anything.

注意到双等号了吗？这是站点的标题。而只有一个等号的 One 级别似乎仅用于电子书输出。

所以请记住：两个等号表示顶级标题，所有更低级别的标题会使用更多等号。

要生成内容，你需要执行 Maven 的 site 工作流。

例如，可以通过执行以下命令来完成：

mvn site

这不会构建构件本身，而只是构建其网站。

构建完成后，你会在 target/site/protocols/wombat/index.html 中找到一个文件。

不过，你可以在任何其他页面链接到此页面，但它不会被添加到导航菜单中。

向菜单添加链接

要向菜单添加链接，必须为你想添加内容的模块创建或修改 site.xml。

最简单的形式可能类似于这样：

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--

 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

 https://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.

 -->
<project name="PLC4J">

  <body>
    <menu name="Wombat">
      <item name="lalala" href="https://plc4x.apache.org/somemodule/somedocument.html"/>
    </menu>
  </body>

</project>

这将会在末尾生成一个 Wombat 菜单，其中包含一个名为 lalala 的链接。

请注意，该链接的文件扩展名必须是 .html，而不能是 .adoc。

如果你想将菜单插入到其他位置，则必须重新定义整个菜单。

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--

 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

 https://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.

 -->
<project name="PLC4J">

  <body>

      <menu ref="reports" inherit="top"/>
      <menu ref="parent" inherit="top"/>

      <menu name="Wombat">
        <item name="lalala" href="https://plc4x.apache.org/somemodule/"/>
      </menu>

      <menu ref="modules" inherit="top"/>

  </body>

</project>

menu ref 条目引用了由 Maven 构建所提供的标准菜单。

网站部署

PLC4X 项目使用 Apache gitpubsub 系统来维护网站。

通常情况下，只要某个仓库已为此注册，其 asf-site 分支中的所有内容都会被复制到 Web 服务器上。

该分支中的内容在 Maven 构建期间生成并维护，属于 site 生成的一部分，前提是执行了 site-deploy 阶段。

构建系统需要将内容提交到 asf-site 分支，而 ASF 的 Jenkins 节点通常没有执行此操作的权限。

为了能够推送到 asf-site GIT 分支，专门配置了一个构建任务，使其运行在带有 Jenkins 标签 git-websites 的节点上。

只有在这些机器上，才允许任务向 Git 仓库推送更改，并且只能推送到名为 asf-site 的分支。

有关 PLC4X Jenkins 网站构建任务的详情，请参阅 https://ci-builds.apache.org/job/PLC4X/。

一旦 asf-site 中的内容发生更新，gitpubsub 机制就会在 https://plc4x.apache.org 提供这些更改。

提供新内容

向菜单添加链接

网站部署

评论