Import drools docs (7/10)

drools-docs/.gitignore

@@ -1,10 +1,22 @@
+# Local files
 /target
 /local
+/build
+/node
+/node_modules
 
 # Eclipse, Netbeans and IntelliJ files
 /.*
 !.gitignore
+!.gitattributes
+!.htaccess
 /nbproject
 /*.ipr
 /*.iws
 /*.iml
+
+# Repository wide ignore mac DS_Store files
+.DS_Store
+
+# Doc generation
+!.index.adoc

drools-docs/README.adoc

@@ -0,0 +1,61 @@
+= Drools documentation website
+
+https://www.drools.org/docs[www.drools.org/docs]
+
+NOTE: The instructions below are to generate Antora site manually. This drools-docs is already configured to generate Antora site with maven plugins.
+
+== Prerequisite
+
+Running Antora with Lunr extension (required to generate self-hosted search) requires Node.js v16.0.0 or above.
+
+== Installing Antora and Lunr
+
+Install Antora CLI 3.0.0 within the playbook project so you can run the antora command using npx:
+
+`npm i -D -E @antora/[email protected]`
+
+Next, install the site generator package within the playbook project:
+
+`npm i -D -E @antora/[email protected]`
+
+Now when you run `npx antora -v`, you should see the version of both the Antora CLI and the site generator printed in the terminal.
+
+```
+@antora/cli: 3.0.0
+@antora/site-generator: 3.0.0
+```
+
+Finally install the Lunr extension with:
+
+`npm i @antora/lunr-extension`
+
+== Building the website locally
+
+This folder contains 2 antora playbooks, `antora-playbook.yml` to generate the documentation from the Drools git repository and `antora-playbook-author.yml` to generate it from the source of your locally installed drools project. To run the latter and generate the documentation locally under the `build` folder use:
+
+`npx antora antora-playbook-author.yml`
+
+== How it works
+
+This module builds a documentation website using https://antora.org/[Antora] that pulls the content from
+the latest release branch of the https://github.com/kiegroup/drools[drools repository].
+
+To simplify the maintenance, the documentation website is based on a pre-built default Antora UI bundle
+located in `ui-bundle/ui-bundle.zip`. Customizations are located in `supplemental-ui` that Antora uses to replace
+parts of the default `ui-bundle.zip`.
+
+== How to upgrade
+
+=== Upgrade UI bundle
+
+Download the latest `ui-bundle.zip` from https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable[Antora GitLab job]
+and replace the existing one in the `ui-bundle` directory.
+
+Be aware that the bundle is not versioned and in the future might not be compatible with the customizations this website uses.
+
+=== Upgrade Lunr search engine
+
+Download the new version of the https://lunrjs.com/[Lunr engine] from the https://www.npmjs.com/package/lunr[NPM registry]
+and replace the existing `supplemental-ui/js/vendor/lunr-*.min.js` file.
+
+Make sure the search box in the top-right corner of the documentation website can still provide hints.

drools-docs/antora-playbook-author.yml

@@ -0,0 +1,20 @@
+# This file serves for local development. Keep it in sync with antora-playbook.yml.
+site:
+  title: Drools Documentation
+  url: https://www.drools.org/docs
+  start_page: drools::getting-started/index.adoc
+  robots: allow
+content:
+  edit_url: '{web_url}/edit/main/{path}'
+  sources:
+    - url: ..
+      branches: [HEAD]
+      start_path: drools-docs/src
+ui:
+  bundle:
+    url: ./ui-bundle/ui-bundle.zip
+  supplemental_files: ./supplemental-ui
+antora:
+  extensions:
+    - '@antora/lunr-extension'
+

drools-docs/antora-playbook.yml

@@ -0,0 +1,23 @@
+# This file serves for generating the Drools documentation website.
+# For local development, see antora-playbook-author.yml.
+site:
+  title: Drools Documentation
+  url: https://www.drools.org/docs
+  start_page: drools::getting-started/index.adoc
+  robots: allow
+content:
+  edit_url: '{web_url}/edit/main/{path}'
+  sources:
+    - url: [email protected]:kiegroup/drools.git
+      # Update with every release.
+      branches: [main]
+      start_path: drools-docs/src
+ui:
+  bundle:
+    url: ./ui-bundle/ui-bundle.zip
+    snapshot: true
+  supplemental_files: ./supplemental-ui
+antora:
+  extensions:
+    - '@antora/lunr-extension'
+

drools-docs/drools-expert-docs/src/main/docbook/en-US/Chapter-ApiReference/Chapter-ApiReference.xml → drools-docs/drools-docs-expert/src/main/docbook/en-US/Obsolete-Chapter-Deployment/Chapter-DepymentAndTest.xml

@@ -4,10 +4,9 @@
          xml:base="./" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns="http://docbook.org/ns/docbook">
-  <title>Api Reference</title>
+  <title>Deployment and Testing</title>
 
-  <xi:include href="Section-Building.xml" />
-  <xi:include href="Section-Deploying.xml" />
-  <xi:include href="Section-Running.xml" />
+  <xi:include href="Section-Deployment.xml" />
+  <xi:include href="Section-Testing.xml" />
 
 </chapter>

drools-docs/drools-docs-expert/src/main/docbook/en-US/Obsolete-Chapter-Deployment/Section-Testing.xml

@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section version="5.0"
+         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
+         xml:base="../" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns="http://docbook.org/ns/docbook">
+  <title>Testing</title>
+
+  <para>In recent years, practices such as Test Driven Development have become
+  increasingly mainstream, as the value and quality that these techniques
+  bring to software development has been realized. In a sense, rules are code
+  (although at a high level), and a lot of the same principles apply.</para>
+
+  <para>You can provide tests as a means to specify rule behavior before
+  rules are even written. Further to this, tests are even more important in
+  environments where rules change frequently. Tests can provide a baseline of
+  confidence that the rule changes are consistent with what is specified in
+  the tests. Of course, the rules may change in such a way as the tests are
+  now wrong (or perhaps new tests need to be written to cover the new rule
+  behavior). As in TDD practices, tests should be run often, and in a rule
+  driven environment, this means that they should be run every time the rules
+  change (even though the software may be static).</para>
+
+  <section>
+    <title>Testing frameworks</title>
+
+    <para>For developers, clearly JUnit (or TestNG) are popular tools for
+    testing code, and these can also apply to rules. Keep in mind that rule
+    changes may happen out of sync with code changes, so you should be
+    prepared to keep these unit tests up to date with rules (may not be
+    possible in all environments). Also, the best idea is to target testing
+    some core features of the rule sets that are not as likely to change over
+    time.</para>
+
+    <para>Obviously, for rule tests, other non source code driven frameworks
+    would be preferable to test rules in some environments. The following
+    section outlines a rule testing component add on.</para>
+  </section>
+
+  <section>
+    <title>FIT for Rules - a rule testing framework</title>
+
+    <para>As a separate add-on, there is a testing framework available that is
+    built on FIT (Framework for Integrated Testing). This allows rule test
+    suites (functional) to be capture in Word documents, or Excel spreadsheets
+    (in fact any tool that can save as HTML). It utilizes a tabular layout to
+    capture input data, and make assertions over the rules of a rulesets
+    execution for the given facts. As the tests are stored in documents, the
+    scenarios and requirements can be (optionally) kept in the same
+    documents, providing a single point of truth for rule behavior.</para>
+
+    <para>Also, as the test documents are not code, they can be updated
+    frequently, and kept with the rules, used to validate rule changes etc. As
+    the input format is fairly simple to people familiar with the domain of
+    the rules, it also facilitates "scenario testing" where different
+    scenarios can be tried out with the rules - all external to the
+    application that the rules are used in. These scenarios can then be kept
+    as tests to increase confidence that a rule change is consistent with the
+    users understanding.</para>
+
+    <para>This testing framework is built on FIT and JSR-94, and is kept as a
+    separate project to JBoss Rules. Due to it being built on FIT, it requires
+    a different license (but is still open source). You can download and read
+    more about this tool from this web page:
+    <link xlink:href="http://fit-for-rules.sourceforge.net/">Fit for rules</link></para>
+
+    <para>The following screen captures show the fit for rules framework in
+    action.</para>
+
+    <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/Chapter-Deployment/Testing1.png" />
+        </imageobject>
+      </mediaobject>
+    </screenshot>
+
+    <para>Using Fit for rules, you capture test data, pass it to the rule
+    engine and then verify the results (with documentation woven in with the
+    test). It is expected that in future, the Drools Server tools will provide
+    a similar integrated framework for testing (green means good ! red means a
+    failure - with the expected values placed in the cell). Refer to
+    http://fit.c2.com for more information on the FIT framework itself.</para>
+
+    <screenshot>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/Chapter-Deployment/Testing2.png" />
+        </imageobject>
+      </mediaobject>
+    </screenshot>
+
+    <para>More information and downloads from <link xlink:href="http://fit-for-rules.sourceforge.net/">here</link></para>
+  </section>
+</section>