Move Reference Guide documentation to our library set-up

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Trigger documentation build
+
+on:
+  push:
+    branches:
+      - 'master'
+    paths:
+      - 'docs/**'
+  pull_request:
+    branches:
+      - 'master'
+    paths:
+      - 'docs/**'
+
+env:
+  VALE_VERSION: ${{ vars.LIBRARY_VALE_VERSION || '3.3.0' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install vale
+        run: |
+          wget "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz"
+          sudo tar -xvzf vale_${VALE_VERSION}_Linux_64-bit.tar.gz -C /usr/local/bin vale
+
+      - name: Generate Site
+        run: |
+          cd docs/_playbook/
+          npm install
+          export GIT_CREDENTIALS='https://axoniq-devops:${{ secrets.LIBRARY_DEVBOT_TOKEN }}@github.com'
+          echo 'Using' `vale -v`
+          npx antora playbook.yaml
+
+      - name: Notify AxonIQ Library (if a push to a tracked branch)
+        if: ${{ github.event_name == 'push'}}
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.LIBRARY_DEVBOT_TOKEN }}
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: 'AxonIQ',
+              repo: 'axoniq-library-site',
+              workflow_id: 'publish.yml',
+              ref: 'main'
+            })

README.md

@@ -23,19 +23,19 @@ For more information on anything Axon, please visit our website, [http://axoniq.
 
 ## Getting started
 
-The [reference guide](https://docs.axoniq.io) contains a separate chapter for all the extensions.
-The JGroups extension description can be found [here](https://docs.axoniq.io/reference-guide/extensions/jgroups).
+The [AxonIQ Library](https://library.axoniq.io) contains a section for the guides of all the Axon Framework extensions.
+The JGroups extension guide can be found [here](https://library.axoniq.io/home/guides/axon-framework.html).
 
 ## Receiving help
 
 Are you having trouble using the extension? 
 We'd like to help you out the best we can!
 There are a couple of things to consider when you're traversing anything Axon:
 
-* Checking the [reference guide](https://docs.axoniq.io/reference-guide/extensions/jgroups) should be your first stop,
- as the majority of possible scenarios you might encounter when using Axon should be covered there.
+* Checking the [reference guide](https://library.axoniq.io/axon_framework_old_ref/) should be your first stop,
+  as the majority of possible scenarios you might encounter when using Axon should be covered there.
 * If the Reference Guide does not cover a specific topic you would've expected,
- we'd appreciate if you could file an [issue](https://github.com/AxonIQ/reference-guide/issues) about it for us. 
+  we'd appreciate if you could post a [new thread/topic on our library fourms describing the problem](https://discuss.axoniq.io/c/26).
 * There is a [forum](https://discuss.axoniq.io/) to support you in the case the reference guide did not sufficiently answer your question.
 Axon Framework and Server developers will help out on a best effort basis.
 Know that any support from contributors on posted question is very much appreciated on the forum.

docs/_playbook/.gitignore

@@ -0,0 +1,5 @@
+build
+node_modules
+.vscode
+vale
+package-lock.json

docs/_playbook/.vale.ini

@@ -0,0 +1,24 @@
+StylesPath = vale
+
+MinAlertLevel = suggestion
+
+Packages = http://github.com/AxonIQ/axoniq-vale-package/releases/latest/download/axoniq-vale-package.zip
+
+Vocab = general, AxonIQ, Java, Names_Terms, misc
+
+[*.{adoc,html}]
+BasedOnStyles = AxonIQ, proselint, Google
+
+Google.Headings = NO # Diasable in favor od AxonIQ one
+Google.Parens = NO # Disable warning about using parens
+Google.Quotes = NO # Diasable "commas and periods go inside quotation marks"
+Google.WordList = NO # Disable Google's word list
+Google.Passive = NO # Allow the use of Passive voice
+Google.Colons = NO # Allow the use of Colons
+Google.Will = NO # Allow use will
+Google.Contractions = NO
+Google.We = NO
+
+
+AxonIQ.AcronymCase = NO
+AxonIQ.HeadingTitle = NO

docs/_playbook/package.json

@@ -0,0 +1,11 @@
+{
+  "devDependencies": {
+    "@antora/atlas-extension": "^1.0.0-alpha.2",
+    "@antora/cli": "^3.2.0-alpha.2",
+    "@antora/lunr-extension": "^1.0.0-alpha.8",
+    "@antora/site-generator": "^3.2.0-alpha.2",
+    "@asciidoctor/tabs": "^1.0.0-beta.6",
+    "@axoniq/antora-vale-extension": "^0.1.1",
+    "asciidoctor-kroki": "^0.17.0"
+  }
+}

docs/_playbook/playbook.yaml

@@ -0,0 +1,42 @@
+site:
+  title: Axon JGroups Extension docs PREVIEW
+  start_page: jgroups_extension_old_ref::index.adoc
+
+content:
+  sources:
+  - url: ../..
+    start_paths: ['docs/*', '!docs/_*']
+
+asciidoc:
+  attributes:
+    experimental: true
+    page-pagination: true
+    kroki-fetch-diagram: true
+  #   primary-site-manifest-url: https://library.axoniq.io/site-manifest.json
+  extensions:
+    - asciidoctor-kroki
+    - '@asciidoctor/tabs'
+
+antora:
+  extensions:
+    - id: prose-linting
+      require: '@axoniq/antora-vale-extension'
+      enabled: true
+      vale_config: .vale.ini
+      update_styles: true
+    - id: lunr
+      require: '@antora/lunr-extension'
+      enabled: true
+      index_latest_only: true
+    - id: atlas
+      require: '@antora/atlas-extension'
+
+runtime:
+  fetch: true # fetch remote repos
+  log:
+    level: info
+    failure_level: error
+
+ui:
+  bundle:
+    url: https://github.com/AxonIQ/axoniq-library-ui/releases/download/v.0.1.10/ui-bundle.zip

docs/old-reference-guide/antora.yml

@@ -0,0 +1,14 @@
+name: jgroups_extension_old_ref
+title: JGroups Extension Guide
+version: true
+prerelease: true
+start_page: ROOT:index.adoc
+
+asciidoc:
+  attributes:
+    component_description: The JGroups AMQP Extension Guide from the former reference guide
+    type: guide
+    group: axon-framework
+
+nav:
+  - modules/nav.adoc

docs/old-reference-guide/modules/ROOT/pages/index.adoc

@@ -0,0 +1,58 @@
+:navtitle: JGroups Extension
+= JGroups
+
+JGroups is an alternative approach to distributing command bus (commands) besides Axon Server.
+
+The `JGroupsConnector` uses (as the name already gives away) link:http://www.jgroups.org/[JGroups,window=_blank,role=external] as the underlying discovery and dispatching mechanism. Describing the features of JGroups is beyond the scope this reference guide Please refer to the link:http://www.jgroups.org/ug.html[JGroups User Guide,window=_blank,role=external] for more information.
+
+To use the JGroups components from Axon, make sure the `axon-jgroups` module is available on the classpath through the preferred dependency management system. When combined with Spring Boot, the `axon-jgroups-spring-boot-starter` dependency can be included to enable auto-configuration.
+
+Since JGroups handles both discovery of nodes and the communication between them, the `JGroupsConnector` acts as both a `CommandBusConnector` and a `CommandRouter`.
+
+NOTE: You can find the JGroups specific components for the `DistributedCommandBus` in the `axon-distributed-commandbus-jgroups` module.
+
+The `JGroupsConnector` has four mandatory configuration elements:
+
+- `channel` - which defines the JGroups protocol stack. Generally, a JChannel is constructed with a reference to a JGroups configuration file. JGroups comes with a number of default configurations which can be used as a basis for your own configuration. Do keep in mind that IP Multicast generally doesn't work in Cloud Services, like Amazon. TCP Gossip is generally a good start in such type of environment.
+
+- `clusterName` - defines the name of the cluster that each segment should register to. Segments with the same cluster name will eventually detect each other and dispatch commands among each other.
+
+- `localSegment` - the Command Bus implementation that dispatches Commands destined for the local JVM. These commands may have been dispatched by instances on other JVMs or from the local one.
+
+- `serializer` - used to serialize command messages before they are sent over the wire.
+
+NOTE: When using a cache, it should be cleared out when the `ConsistentHash` changes to avoid potential data corruption (for example, when commands do not specify a `@TargetAggregateVersion` and a new member quickly joins and leaves the JGroup, modifying the aggregate while it is still cached elsewhere.)
+
+Ultimately, the `JGroupsConnector` needs to actually connect in order to dispatch messages to other segments. To do so, call the `connect()` method.
+
+[source,java]
+----
+JChannel channel = new JChannel("path/to/channel/config.xml");
+CommandBus localSegment = SimpleCommandBus.builder().build();
+Serializer serializer = XStreamSerializer.builder().build();
+
+JGroupsConnector connector = JGroupsConnector.builder()
+                                             .channel(channel)
+                                             .clusterName("myCommandBus")
+                                             .localSegment(localSegment)
+                                             .serializer(serializer)
+                                             .build();
+DistributedCommandBus commandBus = DistributedCommandBus.builder()
+                                                        .connector(connector)
+                                                        .commandRouter(connector)
+                                                        .build();
+
+// on one node:
+commandBus.subscribe(CommandType.class.getName(), handler);
+connector.connect();
+
+// on another node, with more CPU:
+commandBus.subscribe(CommandType.class.getName(), handler);
+commandBus.subscribe(AnotherCommandType.class.getName(), handler2);
+commandBus.updateLoadFactor(150); // defaults to 100
+connector.connect();
+
+// from now on, just deal with commandBus as if it is local...
+----
+
+NOTE: Note that it is not required that all segments have command handlers for the same type of commands. You may use different segments for different command types altogether. The distributed command bus will always choose a node to dispatch a command to that has support for that specific type of command.

docs/old-reference-guide/modules/ROOT/pages/springboot-config.adoc

@@ -0,0 +1,32 @@
+:navtitle: Configuration in SpringBoot
+= Configuration in SpringBoot
+
+If you use Spring, you may want to consider using the `JGroupsConnectorFactoryBean`. It automatically connects the connector when the `ApplicationContext` is started, and does a proper disconnect when the `ApplicationContext` is shut down. Furthermore, it uses sensible defaults for a testing environment (but should not be considered production ready) and autowiring for the configuration.
+
+If Spring Boot is used, the configuration can be further simplified by including the `axon-jgroups-spring-boot-starter` dependency.
+
+The settings for the JGroups connector are all prefixed with `axon.distributed.jgroups`.
+
+[source, properties]
+----
+# enables Axon to construct the DistributedCommandBus
+axon.distributed.enabled=true
+# defines the load factor used for this segment. Defaults to 100
+axon.distributed.load-factor=100
+
+# the address to bind this instance to. By default, it attempts to find the Global IP address
+axon.distributed.jgroups.bind-addr=GLOBAL
+# the port to bind the local instance to
+axon.distributed.jgroups.bind-port=7800
+
+# the name of the JGroups Cluster to connect to
+axon.distributed.jgroups.cluster-name=Axon
+
+# the JGroups Configuration file to configure JGroups with
+axon.distributed.jgroups.configuration-file=default_tcp_gossip.xml
+
+# The IP and port of the Gossip Servers (comma separated) to connect to
+axon.distributed.jgroups.gossip.hosts=localhost[12001]
+# when true, will start an embedded Gossip Server on bound to the port of the first mentioned gossip host.
+axon.distributed.jgroups.gossip.auto-start=false
+----

docs/old-reference-guide/modules/nav.adoc

@@ -0,0 +1,2 @@
+* xref:ROOT:index.adoc[]
+** xref:ROOT:springboot-config.adoc[]