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

= 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 http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference] or https://powerman.name/doc/asciidoc[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 http://plc4x.apache.org/protocols/s7/index.html[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
