| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| |
| |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> |
| <title>PLC4X – </title> |
| <script src="../../js/jquery.slim.min.js" type="text/javascript"></script> |
| <!--script src="../../js/popper.min.js" type="javascript"></script--> |
| <script src="../../js/bootstrap.bundle.min.js" type="text/javascript"></script> |
| <!-- The tooling for adding images and links to Apache events --> |
| <script src="https://www.apachecon.com/event-images/snippet.js" type="text/javascript"></script> |
| <!-- FontAwesome --> |
| <link rel="stylesheet" href="../../css/all.min.css" type="text/css"/> |
| <!-- Bootstrap --> |
| <link rel="stylesheet" href="../../css/bootstrap.min.css" type="text/css"/> |
| <!-- Some Maven Site defaults --> |
| <link rel="stylesheet" href="../../css/maven-base.css" type="text/css"/> |
| <link rel="stylesheet" href="../../css/maven-theme.css" type="text/css"/> |
| <!-- The PLC4X version of a bootstrap theme --> |
| <link rel="stylesheet" href="../../css/themes/plc4x.css" type="text/css" id="pagestyle"/> |
| <!-- A custom style for printing content --> |
| <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print"/> |
| |
| <meta http-equiv="Content-Language" content="en"/> |
| |
| </head> |
| <body class="composite"> |
| <nav class="navbar navbar-light navbar-expand-md bg-faded justify-content-center border-bottom"> |
| <!--a href="/" class="navbar-brand d-flex w-50 mr-auto">Navbar 3</a--> |
| <a href="https://plc4x.apache.org/" id="bannerLeft"><img src="../../images/apache_plc4x_logo_small.png" alt="Apache PLC4X"/></a> |
| <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#collapsingNavbar3"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| <div class="navbar-collapse collapse w-100" id="collapsingNavbar3"> |
| <ul class="navbar-nav w-100 justify-content-center"> |
| <li class="nav-item"> |
| <a class="nav-link" href="../../index.html">Home</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="../../users/index.html">Users</a> |
| </li> |
| <li class="nav-item active"> |
| <a class="nav-link" href="../../developers/index.html">Developers</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="../../apache/index.html">Apache</a> |
| </li> |
| </ul> |
| <ul class="nav navbar-nav ml-auto justify-content-end"> |
| <li class="nav-item row valign-middle"> |
| <a class="acevent" data-format="wide" data-mode="light" data-event="random" style="width:240px;height:60px;"></a> |
| </li> |
| </ul> |
| </div> |
| </nav> |
| <div class="container-fluid"> |
| <div class="row h-100"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <nav class="col-sm-push col-md-2 pt-3 sidebar"> |
| <div class="sidebar-sticky"> |
| <ul class="nav flex-column"> |
| <li class="nav-item"> |
| <a href="../../developers/infrastructure/issues.html" class="nav-link">Bug & Issue Tracker</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/index.html" class="nav-link">Section Home</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/preparing/index.html" class="nav-link">Preparing your Computer</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../../developers/preparing/linux.html" class="nav-link">Linux</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/preparing/macos.html" class="nav-link">Mac OS</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/preparing/windows.html" class="nav-link">Windows</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/building.html" class="nav-link">Building</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/contributing.html" class="nav-link">Contributing</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/tutorials/index.html" class="nav-link">Tutorials</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../../developers/tutorials/writing-driver.html" class="nav-link">Writing Drivers</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/tutorials/testing-serializers-and-parsers.html" class="nav-link">Testing Drivers</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/code-gen/index.html" class="nav-link">Code Generation</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../../developers/code-gen/protocol/mspec.html" class="nav-link">Protocol: MSpec Format</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/code-gen/language/freemarker.html" class="nav-link">Language: Apache Freemarker</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/code-gen/protocol/df1.html" class="nav-link">Example: DF1 MSpec</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/infrastructure/index.html" class="nav-link">Infrastructure</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../../developers/infrastructure/ci.html" class="nav-link">Continuous Integration</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/infrastructure/issues.html" class="nav-link">Bug & Issue Tracker</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/infrastructure/sonar.html" class="nav-link">Code Analysis</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/infrastructure/wiki.html" class="nav-link">Wiki</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/infrastructure/vm.html" class="nav-link">Build VM</a> |
| </li> |
| <li class="nav-item"> |
| <strong class="nav-link">Website</strong> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/infrastructure/vpn.html" class="nav-link">IoT VPN</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/release/index.html" class="nav-link">Releasing</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../../developers/release/release.html" class="nav-link">Releasing</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/release/validation.html" class="nav-link">Validating</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../../developers/release/build-tools.html" class="nav-link">Releasing Build-Tools</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/tools.html" class="nav-link">Tools</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/team.html" class="nav-link">Team</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/decisions.html" class="nav-link">Decision Making</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../../developers/maturity.html" class="nav-link">Maturity</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| </div> |
| </nav> |
| <main role="main" class="ml-sm-auto px-4 col-sm-pull col-md-9 col-lg-10 h-100"> |
| <div class="sect1"> |
| <h2 id="generating_the_website">Generating the Website</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>We are currently using the normal <code>Maven</code> build to not only generate the project artifacts, but also the projects website.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to provide content, every module can have a <code>src/site</code> directory. This content will be generated to that modules site-part.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>skin</code> being used to generate the site is none of the default <code>Maven</code> skins, but a more up-to-date looking skin using:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Bootstrap (For the CSS)</p> |
| </li> |
| <li> |
| <p>JQuery (For the JavaScript magic)</p> |
| </li> |
| <li> |
| <p>Fontawesome (For icons and symbols)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>But we don’t have to worry about the details, all is configured to be used automatically.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The site content itself is generated from <code>asciidoc</code> files (ending <code>.adoc</code>) which is a simple yet powerful markup language. |
| (See <a href="http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/">AsciiDoc Syntax Quick Reference</a> or <a href="https://powerman.name/doc/asciidoc">AsciiDoc cheatsheet</a> for details)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Beyond the basic goodies, the build is also configured to generate images from ASCII data using the <code>asciidoctor-diagram</code> plugin.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This allows us to generate images like the ones on the <a href="http://plc4x.apache.org/protocols/s7/index.html">S7 Protocol Description page</a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="providing_new_content">Providing new content</h3> |
| <div class="paragraph"> |
| <p>Within the <code>src/site</code> directory there is a file <code>site.xml</code> which generally controls the menu and the look of the site.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Most setting are inherited from the <code>plc4x-parent</code> module. That’s also why this is more complicated than the others.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>site.xml</code> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>So if we wanted to add a new page on some (hopefully non existent) <code>Wombat PLC Protocol</code>, we would create a file called:</p> |
| </div> |
| <div class="paragraph"> |
| <p><code>index.adoc</code> in the <code>src/site/asciidoc/protocols/wombat</code> directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example with this content:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code>== 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.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Notice the double equals sign? This is the site Title. It seems the level <code>One</code> with only one equals sign is only used for ebook output.</p> |
| </div> |
| <div class="paragraph"> |
| <p>So just keep in mind: Two equals signs is the top level title, all lower levels have more equals signs.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to generate the content you need to execute the Maven <code>site</code> workflow.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This is for example done by executing:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>mvn site</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will not build the artifact itself, but only it’s website.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After the build, you would find a file <code>target/site/protocols/wombat/index.html</code></p> |
| </div> |
| <div class="paragraph"> |
| <p>However you can link to this page from any other page, but it is not added ot the navigation menu.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="adding_links_to_menus">Adding links to menus</h3> |
| <div class="paragraph"> |
| <p>In order to add links to the menus, you have to create or modify the <code>site.xml</code> for the module you want to add content to.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The simplest form would probably be something like this:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code><?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></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will generate a <code>Wombat</code> menu at the end, and this has one link named <code>lalala</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Notice that the link has to have a file ending of <code>.html</code> and not <code>.adoc</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you want to insert the menu somewhere else, you will have to re-define the entire menu.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="prettyprint highlight"><code><?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></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>menu ref</code> items hereby reference standard menus provided by the <code>Maven</code> build.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="deploying_the_website">Deploying the Website</h3> |
| <div class="paragraph"> |
| <p>The PLC4X project uses Apache <code>gitpubsub</code> system for maintaining the website.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In general all content in a repos <code>asf-site</code> branch is copied to the Webservers, if that repo is registered for it.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The content in this branch is generated and maintained during the <code>Maven</code> build as part of the <code>site</code> generation if the <code>site-deploy</code> phase is executed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The build system needs to check-in content to the <code>asf-site</code> branch and usually ASF Jenkins nodes don’t have the permissions to do that.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to be able to push to the <code>asf-site</code> GIT branch, a dedicated build job is configured to build on nodes with the Jenkins label <code>git-websites</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Only on these machines are jobs allowed to push changes to a Git repo and here only to a branch named <code>asf-site</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="https://ci-builds.apache.org/job/PLC4X/" class="bare">https://ci-builds.apache.org/job/PLC4X/</a> for details on the PLC4X Jenkins Website build job.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As soon as content is updated in the <code>asf-site</code> the <code>gitpubsub</code> mechanism will make those changes available at <a href="https://plc4x.apache.org" class="bare">https://plc4x.apache.org</a></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </main> |
| <footer class="pt-4 my-md-5 pt-md-5 w-100 border-top"> |
| <div class="row justify-content-md-center" style="font-size: 13px"> |
| <div class="col col-6 text-center"> |
| Copyright © 2017–2022 <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved.<br/> |
| Apache PLC4X, PLC4X, Apache, the Apache feather logo, and the Apache PLC4X project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries. All other marks mentioned may be trademarks or registered trademarks of their respective owners. |
| <br/><div style="text-align:center;">Home screen image taken from <a |
| href="https://flic.kr/p/chEftd">Flickr</a>, "Tesla Robot Dance" by Steve Jurvetson, licensed |
| under <a href="https://creativecommons.org/licenses/by/2.0/">CC BY 2.0 Generic</a>, image cropped |
| and blur effect added.</div> |
| </div> |
| </div> |
| </footer> |
| </div> |
| </div> |
| |
| <!-- Bootstrap core JavaScript |
| ================================================== --> |
| <!-- Placed at the end of the document so the pages load faster --> |
| <script src="../../js/jquery.slim.min.js"></script> |
| <script src="../../js/popper.min.js"></script> |
| <script src="../../js/bootstrap.min.js"></script> |
| <script type="text/javascript"> |
| $('.carousel .carousel-item').each(function(){ |
| var next = $(this).next(); |
| if (!next.length) { |
| next = $(this).siblings(':first'); |
| } |
| next.children(':first-child').clone().appendTo($(this)); |
| |
| for (let i = 0; i < 3; i++) { |
| next=next.next(); |
| if (!next.length) { |
| next = $(this).siblings(':first'); |
| } |
| next.children(':first-child').clone().appendTo($(this)); |
| } |
| }); |
| </script> |
| </body> |
| </html> |
