The docs module is not in the module listing of the parent POM by default. Therefore to build you must either activate
the docs profile or be in the docs directory to build the documentation. This documentation assumes you’re in the
docs directory.
You can activate the docs profile from the root directory with either -Pdocs or -Ddocs=true.
In the POM there are currently 3 main properties:
-
appservername -
oracle-javadoc -
wildflyversion
Currently the only property that may need to be changed is the wildflyversion property. This defaults to the property
product.docs.server.version which can be found in the parent POM. It already should be set to the current major
version, but should likely be checked.
Building the documentation can be done with the following command:
mvn clean packagemvn clean package -Pcopy-siteThe asciidoctor-maven-plugin will execute and generate html5 files. The files are generated in the
target/generated-docs directory. You can optionally activate the copy-site profile to copy the generated site. See
copy site option 2 for more details
The first thing required here is a clone of the https://github.com/wildfly/wildfly.github.io repository. Once cloned it’s likely best to checkout a new branch for to update the documentation.
Copying the site can be done one of two ways:
-
You can manually copy the
target/generated-sitefrom thedocsdirectory of WildFly over to thewildfly.github.iorepository. This should be copied into a version directory. For example16for WildFly 16. -
You can run the build with
mvn clean package -Pcopy-sitewhich by default attempts to copy the site to../../wildfly.github.io/${product.docs.server.version}. This can be overridden with thewildfly.github.io.dirproperty.
Once copied you’ll need to add the directory to the git repository; git add ./16 for example.
Next in the wildfly.github.io repository you’ll need to add the newly created directory and link to it from the index page.
In the index.adoc, edit the :wildfly-latest-major: attribute to set it to the new release of WildFly (only the major version).
In the archives.adoc, add a table row for the previous version of WildFly.
Once you edit these 2 files, you’ll need to regenerate their HTML files. This can be done with the asciidoctor
command.
asciidoctor index.adoc archives.adocIn your wildfly.github.io checkout, edit the .github/workflows/jekyll-gh-pages.yml file and update the WILDFLY_DOC_DIR_VERSION_TO_SCAN environment variable with the value of the new documentation version directory (for example, 16 for WildFly 16). The value of this variable indicates the new documentation directory that needs to be scanned to prepare the pre-built search index.
In your wildfly.github.io checkout, edit the sitemap.xml file. In all lines with URLs that include the previous WildFly version, update to the new WildFly version.