ARTEMIS-4383 migrate user docs to AsciiDoc

Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.

Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.

The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.

AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.

This commit contains the following changes:
 - Convert all the Markdown for the User Manual, Migration Guide, and
   Hacking guide to AsciiDoc via kramdown [1].
 - Update the `artemis-website` build to use AsciiDoctor Maven tooling.
 - Update `RELEASING.md` with simplified instructions.
 - Update Hacking Guide with simplified instructions.
 - Use AsciiDoc link syntax in Artemis Maven doc plugin.
 - Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
   Guide. All docs will be HTML only except for the User Manual which
   will have PDF.
 - Move all docs up out of their respective "en" directory. This was a
   hold-over from when we had docs in different languages.
 - Migration & Hacking Guides are now single-page HTML since they are
   relatively short.
 - Refactor README.md to simplify and remove redundant content.

Benefits of the change:
 - Much simplified tooling. No more NPM packages or native tools.
 - Auto-generated table of contents for every chapter.
 - Auto-generated anchor links for every sub-section.
 - Overall more appealing presentation.
 - All docs will use the ActiveMQ favicon.
 - No more manual line-wrapping! AsciiDoc recommends one sentence per
   line and paragraphs are separated by a blank line.
 - AsciiDoctor plugins for IDEA are quite good.
 - Resulting HTML is less than *half* of the previous size.

All previous links/bookmarks should continue to work.

[1] https://github.com/asciidoctor/kramdown-asciidoc

Author: jbertram

.gitignore

@@ -31,12 +31,5 @@ artemis-native/src/main/c/org_apache_activemq_artemis_jlibaio_LibaioContext.h
 # generated by shade
 **/dependency-reduced-pom.xml
 
-# gitbook output
-docs/user-manual/en/_book
-docs/hacking-guide/en/_book
-
 # overlay outpit
 **/overlays/**/*
-
-# result of gitbook pdf under docs
-docs/user-manual/en/book.pdf

README.md

@@ -1,61 +1,21 @@
-# ActiveMQ Artemis
+# Welcome to Apache ActiveMQ Artemis
 
-This file describes some minimum 'stuff one needs to know' to get started coding in this project.
+ActiveMQ Artemis is the next generation message broker from Apache ActiveMQ.
 
-## Source
+## Getting Started
 
-For details about the modifying the code, building the project, running tests, IDE integration, etc. see
-our [Hacking Guide](./docs/hacking-guide/en/SUMMARY.md).
+See the [User Manual](https://activemq.apache.org/components/artemis/documentation/latest/) for an in-depth explanation of all aspects of broker configuration and behavior.
 
-## Build Status
+The broker ships with many [examples](https://activemq.apache.org/components/artemis/documentation/latest/examples.html) which you can run, inspect, & modify.
 
-Build Status: [![Build Status](https://travis-ci.org/apache/activemq-artemis.svg?branch=main)](https://travis-ci.org/apache/activemq-artemis)
+## How to Build, etc.
 
-## Building the ASYNC IO library
+See the [Hacking Guide](https://activemq.apache.org/components/artemis/documentation/hacking-guide/) for details about modifying the code, building the project, running tests, IDE integration, etc.
 
-ActiveMQ Artemis provides two journal persistence types, NIO (which uses the Java NIO libraries), and ASYNCIO which interacts with the linux kernel libaio library.   The ASYNCIO journal type should be used where possible as it is far superior in terms of performance.
+## Migrate from ActiveMQ "Classic"
 
-ActiveMQ Artemis does not ship with the Artemis Native ASYNCIO library in the source distribution.  These need to be built prior to running "mvn install", to ensure that the ASYNCIO journal type is available in the resulting build.  Don't worry if you don't want to use ASYNCIO or your system does not support libaio, ActiveMQ Artemis will check at runtime to see if the required libraries and system dependencies are available, if not it will default to using NIO.
+See the [Migration Guide](https://activemq.apache.org/components/artemis/migration-documentation/) for information about the architectural and configuration differences between ActiveMQ "Classic" (i.e. 5.x) and ActiveMQ Artemis.
 
-To build the ActiveMQ Artemis ASYNCIO native libraries, please follow the instructions in the artemis-native/README.
+## Report an Issue
 
-## Documentation
-
-Our documentation is always in sync with our releases at the [Apache ActiveMQ Artemis](https://activemq.apache.org/artemis/docs.html) website.
-
-Or you can also look at the current main version on [github](https://github.com/apache/activemq-artemis/blob/main/docs/user-manual/en/SUMMARY.md).
-
-## Examples
-
-To run an example firstly make sure you have run
-
-    $ mvn -Prelease install
-
-If the project version has already been released then this is unnecessary.
-
-Each individual example can be run using this command from its corresponding directory:
-
-    $ mvn verify
-
-If you wish to run groups of examples then use this command from a parent directory (e.g. examples/features/standard):
-
-    $ mvn -Pexamples verify
-
-### Recreating the examples
-
-If you are trying to copy the examples somewhere else and modifying them. Consider asking Maven to explicitly list all the dependencies:
-
-    # if trying to modify the 'topic' example:
-    cd examples/jms/topic && mvn dependency:list
-
-### Open Web Application Security Project (OWASP) Report
-
-If you wish to generate the report for CCV dependencies, you may run it with the -Powasp profile
-
-    $ mvn -Powasp verify
-
-The output will be under ./target/dependency-check-report.html **for each** sub-module.
-
-## Bugs
-
-Issues are tracked at https://issues.apache.org/jira/projects/ARTEMIS/
+See [our website](https://activemq.apache.org/issues) for details on how to report an bug, request a feature, etc.

RELEASING.md

@@ -315,26 +315,15 @@ Once the mirrors are up-to-date then update the following:
    with the HTML from the bottom of the release notes url you sent out with your VOTE email (appending `&styleName=Text`).
 2. Copy `src/_artemis_releases/artemis-<old-version>-release.md` to `src/_artemis_releases/artemis-<new-version>-release.md`. Update the versions and dates.
 3. Update the _artemis_ list within the `src/_data/current_releases.yml` file if needed.
-4. Copy `src/components/artemis/documentation/latest` to `src/components/artemis/documentation/<old-version>`.
+4. Rename `src/components/artemis/documentation/latest` to `src/components/artemis/documentation/<old-version>`.
 5. Build the `artemis-website` module from the new-version release sources with `mvn clean package -Prelease`.
-6. Create `src/components/artemis/documentation/latest` and copy these files into it:
-    1. the contents of user-manual from `apache-artemis-<new-version>/web/user-manual`
-    2. book.pdf version of user-manual (generated from the new-version sources at `artemis-website/target/scratch/user-manual/` with the command `gitbook pdf`)
-    3. book.epub version of user-manual (generated from the new-version sources at `artemis-website/target/scratch/user-manual/` with the command `gitbook epub`)
-    4. book.mobi version of user-manual (generated from the new-version sources at `artemis-website/target/scratch/user-manual/` with the command `gitbook mobi`)
-7. Create `src/components/artemis/documentation/hacking-guide` and copy these files into it:
-    1. the contents of hacking-guide from `apache-artemis-<new-version>/web/hacking-guide`
-    2. book.pdf version of hacking-guide (generated with `gitbook pdf`)
-8. Copy `src/components/artemis/documentation/javadocs/javadoc-latest` to `src/components/artemis/documentation/javadocs/javadoc-<old-version>`.
-9. Create `src/components/artemis/documentation/javadocs/javadoc-latest` and copy the contents of `apache-artemis-<new-version>/web/api` into it.
+6. Create `src/components/artemis/documentation/latest` and copy into it the contents of `target/classes/user-manual` from the `artemis-website` module which you just built.
+7. Delete `src/components/artemis/documentation/javadocs/javadoc-latest` to clear the old/existing content (in case any files are being moved/removed by the new version).
+8. Create `src/components/artemis/documentation/javadocs/javadoc-latest` again and copy into it the contents of `target/apidocs` from the `artemis-website` module which you just built.
 
 Run `git add` for all the added directories & files and then `git commit -m "updates for <version> release"`.
 Once pushed, the changes should be published automatically by the `jekyll_websites` builder of the [apache buildbot](https://ci2.apache.org/#/builders).
 
-Note: Generating PDFs, etc. with gitbook requires the installation of [Calibre](https://calibre-ebook.com).
-You can install this manually, but it is recommended you use your platform's package management to install
-(e.g. `sudo apt-get install calibre`).
-
 
 ## Send announcement to user list
 

artemis-distribution/src/main/assembly/source-assembly.xml

@@ -52,10 +52,6 @@
             <!-- Exclude all docs except user manual -->
             <exclude>docs/diagrams/</exclude>
 
-            <!-- Exclude stuff generated by the npm build -->
-            <exclude>artemis-website/node/</exclude>
-            <exclude>artemis-website/node_modules/</exclude>
-
             <!-- Exclude Release and Dev files -->
             <exclude>RELEASING.md</exclude>
             <exclude>ratReport.txt</exclude>
@@ -145,8 +141,6 @@
          </includes>
          <excludes>
             <exclude>**/target/**</exclude>
-            <exclude>artemis-website/node/</exclude>
-            <exclude>artemis-website/node_modules/</exclude>
          </excludes>
       </fileSet>
    </fileSets>

artemis-maven-plugin/src/main/java/org/apache/activemq/artemis/maven/ArtemisDependencyDocPlugin.java

@@ -210,7 +210,7 @@ public int compare(Artifact o1, Artifact o2) {
                if (uri.equals("")) {
                   filter.put("X{fileMD}", result.getArtifact().getFile().getName());
                } else {
-                  filter.put("X{fileMD}", "[" + result.getArtifact().getFile().getName() + "](" + uri + ")");
+                  filter.put("X{fileMD}", "link:" + uri + "[" + result.getArtifact().getFile().getName() + "]");
                }
 
                String output = applyFilters(line, filter);