Add profile for generating javadocs and xref files (#11259)

Motivation:

When changing the netty-all artifact to not include any sources we also removed the ability to generate the javadocs / xref files for our website

Modifications:

- Add new profile which will generate the files
- Add script which generates all the files and copy these over to the netty-website

Result:

Easier to generate files for website
This commit is contained in:
Norman Maurer 2021-05-17 20:12:06 +02:00
parent 7c3810fbdf
commit 5bdcc89ea3
3 changed files with 130 additions and 39 deletions

99
pom.xml
View File

@ -68,6 +68,102 @@
</developers>
<profiles>
<profile>
<id>aggregate</id>
<properties>
<checkstyle.skip>true</checkstyle.skip>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.2.0</version>
<executions>
<execution>
<id>aggregate</id>
<goals>
<goal>aggregate</goal>
</goals>
</execution>
</executions>
<configuration>
<sourceFileExcludes>
<exclude>**/com/sun/**/*.java</exclude>
<exclude>**/example/**/*.java</exclude>
<exclude>**/testsuite/**/*.java</exclude>
<exclude>**/microbench/**/*.java</exclude>
<exclude>**/microbenchmark/**/*.java</exclude>
<exclude>**/generated/**/*.java</exclude>
</sourceFileExcludes>
<docfilessubdirs>true</docfilessubdirs>
<outputDirectory>${project.build.directory}/api</outputDirectory>
<overview>${project.basedir}/src/javadoc/overview.html</overview>
<doctitle>Netty API Reference (${project.version})</doctitle>
<windowtitle>Netty API Reference (${project.version})</windowtitle>
<detectJavaApiLink>false</detectJavaApiLink>
<links>
<link>https://docs.oracle.com/javase/8/docs/api/</link>
<link>https://developers.google.com/protocol-buffers/docs/reference/java/</link>
<link>https://www.slf4j.org/apidocs/</link>
</links>
<groups>
<group>
<title>Low-level data representation</title>
<packages>io.netty.buffer*</packages>
</group>
<group>
<title>Central interface for all I/O operations</title>
<packages>io.netty.channel*</packages>
</group>
<group>
<title>Client &amp; Server bootstrapping utilities</title>
<packages>io.netty.bootstrap*</packages>
</group>
<group>
<title>Reusable I/O event interceptors</title>
<packages>io.netty.handler*</packages>
</group>
<group>
<title>DNS / Host resolvers</title>
<packages>io.netty.resolver*</packages>
</group>
<group>
<title>Utils</title>
<packages>io.netty.util*</packages>
</group>
</groups>
<locale>en_US</locale>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jxr-plugin</artifactId>
<executions>
<execution>
<id>aggregate</id>
<goals>
<goal>aggregate</goal>
</goals>
</execution>
</executions>
<configuration>
<linkJavadoc>true</linkJavadoc>
<destDir>${project.build.directory}/site/xref</destDir>
<javadocDir>${project.build.directory}/site/apidocs</javadocDir>
<docTitle>Netty Source Xref (${project.version})</docTitle>
<windowTitle>Netty Source Xref (${project.version})</windowTitle>
<excludes>
<exclude>**/com/sun/**/*.java</exclude>
<exclude>**/example/**/*.java</exclude>
<exclude>**/microbench/**/*.java</exclude>
<exclude>**/microbenchmark/**/*.java</exclude>
</excludes>
</configuration>
</plugin>
</plugins>
</build>
</profile>
<!-- Detect if we use GraalVM and if so enable the native image testsuite -->
<profile>
<id>graal</id>
@ -1317,9 +1413,8 @@
<version>2.6</version>
</plugin>
<plugin>
<!-- Do NOT upgrade -->
<artifactId>maven-jxr-plugin</artifactId>
<version>2.2</version>
<version>3.1.1</version>
</plugin>
<plugin>
<artifactId>maven-antrun-plugin</artifactId>

View File

@ -1,37 +0,0 @@
#!/bin/bash
set -e
if [ "$#" -ne 1 ]; then
echo "Expected netty-website directory"
exit 1
fi
if [ ! -d "$1" ]; then
echo "$1 is not a directory"
exit 1
fi
BRANCH=$(git branch --show-current)
WEBSITE_API_DIR="$1"/"$BRANCH"/api/
WEBSITE_XREF_DIR="$1"/"$BRANCH"/xref/
API_DIR=all/target/api/
XREF_DIR=all/target/xref/
if [ ! -d "$API_DIR" ]; then
echo "$API_DIR not exists, didn't run the release process yet?"
exit 1
fi
if [ ! -d "$XREF_DIR" ]; then
echo "$XREF_DIR not exists, didn't run the release process yet?"
exit 1
fi
echo "Delete old javadocs and xref files"
rm -rf "$WEBSITE_API_DIR"/*
rm -rf "$WEBSITE_XREF_DIR"/*
echo "Copy javadocs and xref files"
cp -r "$API_DIR"/* "$WEBSITE_API_DIR"
cp -r "$XREF_DIR"/* "$WEBSITE_XREF_DIR"

33
scripts/generate_docs.sh Executable file
View File

@ -0,0 +1,33 @@
#!/bin/bash
set -e
# Adjust for different branch if needed
VERSION=5.0
if [ "$#" -ne 2 ]; then
echo "Expected netty-website directory and tag"
exit 1
fi
if [ ! -d "$1" ]; then
echo "$1 is not a directory"
exit 1
fi
BRANCH=$(git branch --show-current)
TAG="$2"
WEBSITE_API_DIR="$1"/"$VERSION"/api/
WEBSITE_XREF_DIR="$1"/"$VERSION"/xref/
API_DIR=target/site/apidocs/
XREF_DIR=target/site/xref/
git checkout "$TAG"
JAVA_HOME=$JAVA8_HOME ./mvnw -Paggregate clean package javadoc:aggregate jxr:aggregate -DskipTests=true
echo "Delete old javadocs and xref files"
rm -rf "$WEBSITE_API_DIR"/*
rm -rf "$WEBSITE_XREF_DIR"/*
echo "Copy javadocs and xref files"
cp -r "$API_DIR"/* "$WEBSITE_API_DIR"
cp -r "$XREF_DIR"/* "$WEBSITE_XREF_DIR"