You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by cd...@apache.org on 2017/12/23 17:02:41 UTC
[incubator-plc4x] branch master updated: NO JIRA:
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-plc4x.git
The following commit(s) were added to refs/heads/master by this push:
new 447bed6 NO JIRA:
447bed6 is described below
commit 447bed6a8cb69a993f35d5b32b3a20e27caa51ba
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Sat Dec 23 17:57:55 2017 +0100
NO JIRA:
- Added some documentation on how to write content for the website.
---
src/site/asciidoc/development/website.adoc | 177 +++++++++++++++++++++++++++++
src/site/asciidoc/infra/website.adoc | 39 -------
src/site/site.xml | 4 +-
3 files changed, 179 insertions(+), 41 deletions(-)
diff --git a/src/site/asciidoc/development/website.adoc b/src/site/asciidoc/development/website.adoc
new file mode 100644
index 0000000..ff95f8d
--- /dev/null
+++ b/src/site/asciidoc/development/website.adoc
@@ -0,0 +1,177 @@
+//
+// 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
+//
+// http://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
+
+ http://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
+
+ http://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 http://[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://builds.apache.org/view/M-R/job/PLC4X/job/PLC4X%20Site/ for details on the PLC4X Jenkins 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
diff --git a/src/site/asciidoc/infra/website.adoc b/src/site/asciidoc/infra/website.adoc
deleted file mode 100644
index 3635075..0000000
--- a/src/site/asciidoc/infra/website.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-//
-// 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
-//
-// http://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.
-
-
-
-=== 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.
-
-This content in this branch is generated and maintained during the `Maven` build as part of the `site` generation.
-
-The build system needs to check-in content to the `asf-site` branch and usually Jenkins machines don't have the permissions to push to git.
-
-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://builds.apache.org/view/M-R/job/PLC4X/job/PLC4X%20Site/ for details on the PLC4X Jenkins 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
diff --git a/src/site/site.xml b/src/site/site.xml
index 295952d..54b3572 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -81,8 +81,8 @@
<menu ref="reports" inherit="top"/>
<menu ref="parent" inherit="top"/>
- <menu name="Project">
- <!--item name="Incubation-Proposal" href="incubation-proposal.html"/-->
+ <menu name="Development">
+ <item name="Website" href="development/website.html"/>
</menu>
<menu name="Infrastructure">
<item name="Wiki" href="https://cwiki.apache.org/confluence/display/PLC4X"/>
--
To stop receiving notification emails like this one, please contact
['"commits@plc4x.apache.org" <co...@plc4x.apache.org>'].