Update docs for main

Signed-off-by: ansible-middleware-core <[email protected]>
ansible-middleware · Oct 14, 2024 · 20c47f8 · 20c47f8
1 parent 79b0fe1
commit 20c47f8
Show file tree

Hide file tree

Showing 64 changed files with 5,300 additions and 1,100 deletions.
diff --git a/main/.buildinfo b/main/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
-# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 5422d2407b39bec8045469759c8d4bcd
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 41717c66ccfdc835c0d79583ac723bee
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/main/CHANGELOG.html b/main/CHANGELOG.html
diff --git a/main/README.html b/main/README.html
@@ -1,3 +1,5 @@
+
+
 <!DOCTYPE html>
 <html class="writer-html5" lang="en" data-content_root="./">
 <head>
@@ -6,20 +8,16 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Ansible Collection - middleware_automation.keycloak &mdash; Keycloak Ansible Collection  documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=5707b69d" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=19f00094" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
       <link rel="stylesheet" type="text/css" href="_static/antsibull-minimal.css" />
       <link rel="stylesheet" type="text/css" href="_static/ansible-basic-sphinx-ext.css" />
 
 
-  <!--[if lt IE 9]>
-    <script src="_static/js/html5shiv.min.js"></script>
-  <![endif]-->
-
-        <script src="_static/jquery.js?v=5d32c60e"></script>
-        <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="_static/documentation_options.js?v=5929fcd5"></script>
-        <script src="_static/doctools.js?v=9a2dae69"></script>
-        <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/jquery.js?v=5d32c60e"></script>
+      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+      <script src="_static/documentation_options.js?v=5929fcd5"></script>
+      <script src="_static/doctools.js?v=9bcbadda"></script>
+      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/js/theme.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
@@ -74,27 +72,24 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="plugins/index.html">Plugin Index</a></li>
 <li class="toctree-l1"><a class="reference internal" href="roles/index.html">Role Index</a></li>
+<li class="toctree-l1"><a class="reference internal" href="CHANGELOG.html">Changelog</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="developing.html">Developing</a></li>
+<li class="toctree-l1"><a class="reference internal" href="developing.html#contributor-s-guidelines">Contributor’s Guidelines</a></li>
 <li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
-<li class="toctree-l1"><a class="reference internal" href="developing.html">Contributor’s Guidelines</a></li>
-<li class="toctree-l1"><a class="reference internal" href="releasing.html">Collection Versioning Strategy</a></li>
-</ul>
-<p class="caption" role="heading"><span class="caption-text">General</span></p>
-<ul>
-<li class="toctree-l1"><a class="reference internal" href="CHANGELOG.html">Changelog</a></li>
+<li class="toctree-l1"><a class="reference internal" href="releasing.html">Releasing</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Middleware collections</span></p>
 <ul>
-<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/infinispan/main/">Infinispan / Red Hat Data Grid</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/keycloak/main/">Keycloak / Red Hat Single Sign-On</a></li>
+<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/infinispan/main/">Infinispan / Red Hat Data Grid</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/wildfly/main/">Wildfly / Red Hat JBoss EAP</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/jws/main/">Tomcat / Red Hat JWS</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/amq/main/">ActiveMQ / Red Hat AMQ Broker</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/amq_streams/main/">Kafka / Red Hat AMQ Streams</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/common/main/">Ansible Middleware utilities</a></li>
-<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/redhat-csp-download/main/">Red Hat CSP Download</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/ansible_collections_jcliff/main/">JCliff</a></li>
 </ul>
 
@@ -127,7 +122,7 @@ <h1>Ansible Collection - middleware_automation.keycloak<a class="headerlink" hre
 <!--start build_status -->
 <p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/actions/workflows/ci.yml"><img alt="Build Status" src="https://github.com/ansible-middleware/keycloak/workflows/CI/badge.svg?branch=main" /></a></p>
 <blockquote>
-<div><p><strong><em>NOTE:</em> If you are Red Hat customer, install <code class="docutils literal notranslate"><span class="pre">redhat.sso</span></code> (for Red Hat Single Sign-On) or <code class="docutils literal notranslate"><span class="pre">redhat.rhbk</span></code> (for Red Hat Build of Keycloak) from <a class="reference external" href="https://console.redhat.com/ansible/ansible-dashboard">Automation Hub</a> as the certified version of this collection.</strong></p>
+<div><p><strong><em>NOTE:</em> If you are Red Hat customer, install <code class="docutils literal notranslate"><span class="pre">redhat.rhbk</span></code> (for Red Hat Build of Keycloak) or <code class="docutils literal notranslate"><span class="pre">redhat.sso</span></code> (for Red Hat Single Sign-On) from <a class="reference external" href="https://console.redhat.com/ansible/ansible-dashboard">Automation Hub</a> as the certified version of this collection.</strong></p>
 </div></blockquote>
 <!--end build_status -->
 <!--start description -->
@@ -170,9 +165,9 @@ <h3>Installing the Collection from Ansible Galaxy<a class="headerlink" href="#in
 <section id="included-roles">
 <h3>Included roles<a class="headerlink" href="#included-roles" title="Link to this heading"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md"><code class="docutils literal notranslate"><span class="pre">keycloak</span></code></a>: role for installing the service (keycloak &lt;= 19.0).</p></li>
-<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_realm/README.md"><code class="docutils literal notranslate"><span class="pre">keycloak_realm</span></code></a>: role for configuring a realm, user federation(s), clients and users, in an installed service.</p></li>
-<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_quarkus/README.md"><code class="docutils literal notranslate"><span class="pre">keycloak_quarkus</span></code></a>: role for installing the quarkus variant of keycloak (&gt;= 17.0.0).</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_quarkus</span></code>: role for installing keycloak (&gt;= 19.0.0, quarkus based).</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm</span></code>: role for configuring a realm, user federation(s), clients and users, in an installed service.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">keycloak</span></code>: role for installing legacy keycloak (&lt;= 19.0, wildfly based).</p></li>
 </ul>
 <!--end roles_paths -->
 </section>
@@ -183,8 +178,8 @@ <h2>Usage<a class="headerlink" href="#usage" title="Link to this heading"></a
 <h3>Install Playbook<a class="headerlink" href="#install-playbook" title="Link to this heading"></a></h3>
 <!--start rhbk_playbook -->
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak.yml</span></code></a> installs keycloak legacy based on the defined variables (using most defaults).</p></li>
 <li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_quarkus.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak_quarkus.yml</span></code></a> installs keycloak &gt;= 17 based on the defined variables (using most defaults).</p></li>
+<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak.yml</span></code></a> installs keycloak legacy based on the defined variables (using most defaults).</p></li>
 </ul>
 <p>Both playbooks include the <code class="docutils literal notranslate"><span class="pre">keycloak</span></code> role, with different settings, as described in the following sections.</p>
 <p>For full service configuration details, refer to the <a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md">keycloak role README</a>.</p>

diff --git a/main/_sources/CHANGELOG.rst.txt b/main/_sources/CHANGELOG.rst.txt
@@ -9,11 +9,6 @@ This changelog describes changes after version 0.2.6.
 v2.4.3-devel
 ============
 
-Release Summary
----------------
-
-Internal release, documentation or test changes only.
-
 v2.4.2
 ======
 

diff --git a/main/_sources/README.md.txt b/main/_sources/README.md.txt
@@ -3,7 +3,7 @@
 <!--start build_status -->
 [![Build Status](https://github.com/ansible-middleware/keycloak/workflows/CI/badge.svg?branch=main)](https://github.com/ansible-middleware/keycloak/actions/workflows/ci.yml)
 
-> **_NOTE:_ If you are Red Hat customer, install `redhat.sso` (for Red Hat Single Sign-On) or `redhat.rhbk` (for Red Hat Build of Keycloak) from [Automation Hub](https://console.redhat.com/ansible/ansible-dashboard) as the certified version of this collection.**
+> **_NOTE:_ If you are Red Hat customer, install `redhat.rhbk` (for Red Hat Build of Keycloak) or `redhat.sso` (for Red Hat Single Sign-On) from [Automation Hub](https://console.redhat.com/ansible/ansible-dashboard) as the certified version of this collection.**
 
 <!--end build_status -->
 <!--start description -->
@@ -49,19 +49,20 @@ A requirement file is provided to install:
 <!--start roles_paths -->
 ### Included roles
 
-* [`keycloak`](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md): role for installing the service (keycloak <= 19.0).
-* [`keycloak_realm`](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_realm/README.md): role for configuring a realm, user federation(s), clients and users, in an installed service.
-* [`keycloak_quarkus`](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_quarkus/README.md): role for installing the quarkus variant of keycloak (>= 17.0.0).
+* `keycloak_quarkus`: role for installing keycloak (>= 19.0.0, quarkus based).
+* `keycloak_realm`: role for configuring a realm, user federation(s), clients and users, in an installed service.
+* `keycloak`: role for installing legacy keycloak (<= 19.0, wildfly based).
+
 <!--end roles_paths -->
 
 ## Usage
 
 
 ### Install Playbook
 <!--start rhbk_playbook -->
-* [`playbooks/keycloak.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak.yml) installs keycloak legacy based on the defined variables (using most defaults).
 * [`playbooks/keycloak_quarkus.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_quarkus.yml) installs keycloak >= 17 based on the defined variables (using most defaults).
-
+* [`playbooks/keycloak.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak.yml) installs keycloak legacy based on the defined variables (using most defaults).
+
 Both playbooks include the `keycloak` role, with different settings, as described in the following sections.
 
 For full service configuration details, refer to the [keycloak role README](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md).
@@ -92,7 +93,7 @@ Execute the following command from the source root directory
 
 ```
 ansible-playbook -i <ansible_hosts> -e @rhn-creds.yml playbooks/keycloak.yml -e keycloak_admin_password=<changeme>
-``` 
+```
 
 - `keycloak_admin_password` Password for the administration console user account.
 - `ansible_hosts` is the inventory, below is an example inventory for deploying to localhost
@@ -143,4 +144,3 @@ Apache License v2.0 or later
 <!--start license -->
 See [LICENSE](LICENSE) to view the full text.
 <!--end license -->
-
diff --git a/main/_sources/developing.md.txt b/main/_sources/developing.md.txt
@@ -1,3 +1,37 @@
+## Developing
+
+### Build and install locally
+
+Clone the repository, checkout the tag you want to build, or pick the main branch for the development version; then:
+
+    ansible-galaxy collection build .
+    ansible-galaxy collection install middleware_automation-keycloak-*.tar.gz
+
+
+### Development environment
+
+Make sure your development machine has avilable:
+
+* python 3.11+
+* virtualenv
+* docker (or podman)
+
+In order to run setup the development environment and run the molecule tests locally, after cloning the repository:
+
+```
+# create new virtualenv using python 3
+virtualenv $PATH_TO_DEV_VIRTUALENV
+# activate the virtual env
+source $PATH_TO_DEV_VIRTUALENV/bin/activate
+# install ansible and tools onto the virtualenv
+pip install yamllint 'molecule>=6.0' 'molecule-plugins[docker]' 'ansible-core>=2.15' ansible-lint
+# install collection dependencies
+ansible-galaxy collection install -r requirements.yml
+# install python dependencies
+pip install -r requirements.txt molecule/requirements.txt
+# execute the tests (replace --all with -s subdirectory to run a single test)
+molecule test --all
+```
 
 ## Contributor's Guidelines
 

diff --git a/main/_sources/index.rst.txt b/main/_sources/index.rst.txt
@@ -10,31 +10,25 @@ Welcome to Keycloak Collection documentation
    README
    plugins/index
    roles/index
+   Changelog <CHANGELOG>
 
 .. toctree::
    :maxdepth: 2
    :caption: Developer documentation
 
-   testing
-   developing
-   releasing
-
-.. toctree::
-   :maxdepth: 2
-   :caption: General
-
-   Changelog <CHANGELOG>
+   Developing <developing>
+   Testing <testing>
+   Releasing <releasing>
 
 .. toctree::
    :maxdepth: 2
    :caption: Middleware collections
 
-   Infinispan / Red Hat Data Grid <https://ansible-middleware.github.io/infinispan/main/>
    Keycloak / Red Hat Single Sign-On <https://ansible-middleware.github.io/keycloak/main/>
+   Infinispan / Red Hat Data Grid <https://ansible-middleware.github.io/infinispan/main/>
    Wildfly / Red Hat JBoss EAP <https://ansible-middleware.github.io/wildfly/main/>
    Tomcat / Red Hat JWS <https://ansible-middleware.github.io/jws/main/>
    ActiveMQ / Red Hat AMQ Broker <https://ansible-middleware.github.io/amq/main/>
    Kafka / Red Hat AMQ Streams <https://ansible-middleware.github.io/amq_streams/main/>
    Ansible Middleware utilities <https://ansible-middleware.github.io/common/main/>
-   Red Hat CSP Download <https://ansible-middleware.github.io/redhat-csp-download/main/>
    JCliff <https://ansible-middleware.github.io/ansible_collections_jcliff/main/>
diff --git a/main/_sources/plugins/index.rst.txt b/main/_sources/plugins/index.rst.txt
@@ -6,6 +6,7 @@ Plugin Index
    :maxdepth: 0
 
    keycloak_client
+   keycloak_realm
    keycloak_role
    keycloak_user_federation