Generating the Website

We are currently using the normal Maven build to not only generate the project artifacts, but also the projects website.

In order to provide content, every module can have a src/site directory. This content will be generated to that modules site-part.

The skin being used to generate the site is none of the default Maven skins, but a more up-to-date looking skin using:

  • Bootstrap (For the CSS)

  • JQuery (For the JavaScript magic)

  • Fontawesome (For icons and symbols)

But we don’t have to worry about the details, all is configured to be used automatically.

The site content itself is generated from asciidoc files (ending .adoc) which is a simple yet powerful markup language. (See AsciiDoc Syntax Quick Reference or AsciiDoc cheatsheet for details)

Beyond the basic goodies, the build is also configured to generate images from ASCII data using the asciidoctor-diagram plugin.

This allows us to generate images like the ones on the S7 Protocol Description page

Providing new content

Within the src/site directory there is a file site.xml which generally controls the menu and the look of the site.

Most setting are inherited from the plc4x-parent module. That’s also why this is more complicated than the others.

The site.xml file is optional. Even if this is not available a site will be generated however no additional content will be linked from any of the navigation menus.

So if we wanted to add a new page on some (hopefully non existent) Wombat PLC Protocol, we would create a file called:

index.adoc in the src/site/asciidoc/protocols/wombat directory.

For example with this content:

= 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.

Notice the double equals sign? This is the site Title. It seems the level One with only one equals sign is only used for ebook output.

So just keep in mind: Two equals signs is the top level title, all lower levels have more equals signs.

In order to generate the content you need to execute the Maven site workflow.

This is for example done by executing:

mvn site

This will not build the artifact itself, but only it’s website.

After the build, you would find a file target/site/protocols/wombat/index.html

However you can link to this page from any other page, but it is not added ot the navigation menu.

Adding links to menus

In order to add links to the menus, you have to create or modify the site.xml for the module you want to add content to.

The simplest form would probably be something like this:

<?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>

This will generate a Wombat menu at the end, and this has one link named lalala.

Notice that the link has to have a file ending of .html and not .adoc.

If you want to insert the menu somewhere else, you will have to re-define the entire menu.

<?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>

The menu ref items hereby reference standard menus provided by the Maven build.

Deploying the Website

The PLC4X project uses Apache gitpubsub system for maintaining the website.

In general all content in a repos asf-site branch is copied to the Webservers, if that repo is registered for it.

The content in this branch is generated and maintained during the Maven build as part of the site generation if the site-deploy phase is executed.

The build system needs to check-in content to the asf-site branch and usually ASF Jenkins nodes don’t have the permissions to do that.

In order to be able to push to the asf-site GIT branch, a dedicated build job is configured to build on nodes with the Jenkins label git-websites.

Only on these machines are jobs allowed to push changes to a Git repo and here only to a branch named asf-site.

See https://ci-builds.apache.org/job/PLC4X/ for details on the PLC4X Jenkins Website build job.

As soon as content is updated in the asf-site the gitpubsub mechanism will make those changes available at https://plc4x.apache.org