Skip to content
Permalink
Browse files
chore: Add Maven build option
  • Loading branch information
christophd authored and zregvart committed Mar 12, 2019
1 parent 3b8f70a commit e310973acc16ce1814ce2174f3bf99ed0325070d
Showing 3 changed files with 236 additions and 4 deletions.
@@ -1,3 +1,5 @@
node
target
node_modules
public
static
@@ -19,10 +19,14 @@ Tools used to generate the website:
Asciidoc documents from different sources in the [Camel](https://github.com/apache/camel)
and [Camel K](https://github.com/apache/camel-k) repositories where user manual and component
reference documentation resides and renders them for inclusion in this website.
- [Maven](https://maven.apache.org/) (optional) a build tool used to run the complete website generating process

## Building the website
## Build with Node and yarn

You can build the website locally using the tools `Node.js` and `yarn`.
You can build the website locally using the tools `Node.js` and `yarn`.

If you can not use these tools on your local machine for some reason you can also build the website using Maven as
described in section ["Build with Maven"](#build-with-maven).

### Preparing the tools

@@ -51,7 +55,7 @@ You will need Yarn installed, which is the preferred package manager for the Nod

You should install Yarn globally using the following command:

$ npm install -g yarn
$ npm install -g yarn

`npm` is the Node package manager that comes with the default Node installation. So when you have Node installed you
should also be able to use the `npm` command.
@@ -95,6 +99,66 @@ To build the website go to the project root folder and run:
This should fetch doc sources for [Camel](https://github.com/apache/camel) and [Camel K](https://github.com/apache/camel-k)
and generate the website with Hugo. You should see the generated website in the `public` folder.

## Build with Maven

The project provides a simple way to build the website sources locally using the build tool [Maven](https://maven.apache.org/).

The Maven build automatically downloads the tool binaries such as `node` and `yarn` for you. You do not need to install
those tools on your host then. The binaries are added to the local project sources only and generate the website content.

As the Maven build uses pinned versions of `node` and `yarn` that are tested to build the website you most likely avoid
build errors due to incompatible versions of `Node.js` tooling installed on your machine.

### Preparing Maven

Make sure that you have Maven installed.

$ mvn --version

If this command fails with an error, you do not have Maven installed.

Please install Maven using your favorite package manager (like [Homebrew](https://brew.sh/)) or from
official [Maven binaries](https://maven.apache.org/install.html)

### Building from scratch

When building everything from scratch the build executes following steps:

- Download `yarn` and `Node.js` binaries to the local project
- Load required libraries to the local project using `yarn`
- Build the Antora Camel UI theme ([antora-ui-camel](antora-ui-camel))
- Fetch the doc sources from [Camel](https://github.com/apache/camel)
and [Camel K](https://github.com/apache/camel-k) github reporsitories
- Build the website content using Hugo

You can do all of this with one single command:

$ mvn package

The whole process takes up to five minutes (time to grab some coffee!)

When the build is finished you should see the generated website in the `public` folder.

### Rebuild website

When rebuilding the website you can optimize the build process as some of the steps are only required for a fresh
build from scratch. You can skip the ui theme rendering (unless you have changes in the theme itself).

$ mvn package -Dskip.theme

This should save you some minutes in the build process. You can find the updated website content in the `public` folder.

### Clean build

When rebuilding the website the process uses some cached content (e.g. the fetched doc sources for
[Camel](https://github.com/apache/camel) and [Camel K](https://github.com/apache/camel-k) or the Antora ui theme).
If you want to start from scratch for some reason you can simply add the `clean` operation to the build which removes
all generated sources in the project first.

$ mvn clean package

Of course this then takes some more time than an optimized rebuild (time to grab another coffee!).

## Contribute changes

The Apache Camel website is composed of different sources. So where to add and contribute changes in particular?
@@ -106,7 +170,7 @@ The Apache Camel website is composed of different sources. So where to add and c
The site main menu is defined in the top level configuration [config.toml](config.toml). You can add/change
menu items there.

#### Website content
#### Content

The basic website content is located in [content](content). You can find several different folders representing different
areas of the website:
166 pom.xml
@@ -0,0 +1,166 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (C) 2016 Red Hat, Inc.
Licensed 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 xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>
<groupId>org.apache</groupId>
<artifactId>apache</artifactId>
<version>21</version>
</parent>

<modelVersion>4.0.0</modelVersion>

<groupId>org.apache.camel</groupId>
<artifactId>camel-website</artifactId>
<version>0.0.1</version>
<packaging>pom</packaging>

<name>Apache Camel Website</name>

<properties>
<!-- unify the encoding for all the modules -->
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

<node.version>v10.15.3</node.version>
<yarn.version>v1.14.0</yarn.version>

<theme.basedir>antora-ui-camel</theme.basedir>
<skip.theme>false</skip.theme>
</properties>

<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-clean-plugin</artifactId>
<version>3.1.0</version>
</plugin>
<plugin>
<groupId>com.github.eirslett</groupId>
<artifactId>frontend-maven-plugin</artifactId>
<version>1.7.5</version>
</plugin>
</plugins>
</pluginManagement>

<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-clean-plugin</artifactId>
<configuration>
<excludeDefaultDirectories>true</excludeDefaultDirectories>
<filesets>
<fileset>
<directory>${project.build.directory}</directory>
</fileset>
<fileset>
<directory>node</directory>
</fileset>
<fileset>
<directory>.pnp</directory>
</fileset>
<fileset>
<directory>public</directory>
</fileset>
<fileset>
<directory>static</directory>
</fileset>
<fileset>
<directory>${theme.basedir}/.pnp</directory>
</fileset>
<fileset>
<directory>${theme.basedir}/public</directory>
</fileset>
<fileset>
<directory>${theme.basedir}/build</directory>
</fileset>
</filesets>
</configuration>
</plugin>

<plugin>
<groupId>com.github.eirslett</groupId>
<artifactId>frontend-maven-plugin</artifactId>
<executions>
<execution>
<id>install node and npm</id>
<goals>
<goal>install-node-and-npm</goal>
</goals>
<configuration>
<nodeVersion>${node.version}</nodeVersion>
</configuration>
</execution>
<execution>
<id>install yarn</id>
<goals>
<goal>install-node-and-yarn</goal>
</goals>
<configuration>
<nodeVersion>${node.version}</nodeVersion>
<yarnVersion>${yarn.version}</yarnVersion>
</configuration>
</execution>
<execution>
<id>theme install</id>
<goals>
<goal>yarn</goal>
</goals>
<configuration>
<skip>${skip.theme}</skip>
<arguments>install --no-progress --force</arguments>
<workingDirectory>${theme.basedir}</workingDirectory>
<installDirectory>${project.basedir}</installDirectory>
</configuration>
</execution>
<execution>
<id>theme build</id>
<goals>
<goal>yarn</goal>
</goals>
<configuration>
<skip>${skip.theme}</skip>
<arguments>build</arguments>
<workingDirectory>${theme.basedir}</workingDirectory>
<installDirectory>${project.basedir}</installDirectory>
</configuration>
</execution>
<execution>
<id>yarn install</id>
<goals>
<goal>yarn</goal>
</goals>
<configuration>
<arguments>install --no-progress --force</arguments>
</configuration>
</execution>
<execution>
<id>yarn build</id>
<goals>
<goal>yarn</goal>
</goals>
<configuration>
<arguments>build</arguments>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

0 comments on commit e310973

Please sign in to comment.