docs: overall minor renovations (#1874)

* docs: simplify README.md and make index.md to refer to it
* docs: change order for pages in navigation and add missing pages
* docs: fix headings to improve navigation, transform notes to admonition, fix indentation, linting issues and minor issues
* docs: merge docs for using images from private registries
* docs: add example to integrate LDAP configuration via extra_settings_files
* Apply suggestions from code review
docs: apply suggested changes

Co-authored-by: Don Naro <[email protected]>

* docs: update the doc site url as same as the url in https://www.ansible.com/ecosystem/
* docs: minor fixes for hpa page
* docs: expand note block
* docs: apply #1904 to README.md

---------

Co-authored-by: Don Naro <[email protected]>

README.md

@@ -8,30 +8,17 @@
 
 An [Ansible AWX](https://github.com/ansible/awx) operator for Kubernetes built with [Operator SDK](https://github.com/operator-framework/operator-sdk) and Ansible.
 
-<!-- Regenerate this table of contents using https://github.com/ekalinin/github-markdown-toc -->
-<!-- gh-md-toc --insert README.md -->
-<!--ts-->
+The AWX Operator is meant to be deployed in your Kubernetes cluster(s) and can be used to install and manage the lifecycle of an AWX instance in the same namespace.
 
-# AWX Operator Documentation
+## Documentation
 
-The AWX Operator documentation is now available at https://awx-operator.readthedocs.io/
-
-For docs changes, create PRs on the appropriate files in the /docs folder.
+The AWX Operator documentation is available at <https://ansible.readthedocs.io/projects/awx-operator/>
 
 ## Contributing
 
 Please visit [our contributing guidelines](https://github.com/ansible/awx-operator/blob/devel/CONTRIBUTING.md).
 
-## Release Process
-
-The first step is to create a draft release. Typically this will happen in the [Stage Release](https://github.com/ansible/awx/blob/devel/.github/workflows/stage.yml) workflow for AWX and you don't need to do it as a separate step.
-
-If you need to do an independent release of the operator, you can run the [Stage Release](https://github.com/ansible/awx-operator/blob/devel/.github/workflows/stage.yml) in the awx-operator repo. Both of these workflows will run smoke tests, so there is no need to do this manually.
-
-After the draft release is created, publish it and the [Promote AWX Operator image](https://github.com/ansible/awx-operator/blob/devel/.github/workflows/promote.yaml) will run, which will:
-
-- Publish image to Quay
-- Release Helm chart
+For docs changes, create PRs on the appropriate files in the `/docs` folder.
 
 ## Author
 
@@ -43,7 +30,7 @@ We ask all of our community members and contributors to adhere to the [Ansible c
 
 ## Get Involved
 
-We welcome your feedback and ideas. The AWX operator uses the same mailing list and IRC channel as AWX itself. Here's how to reach us with feedback and questions:
+We welcome your feedback and ideas. The AWX operator uses the same Matrix channel and Ansible Community Forum as AWX itself. Here's how to reach us with feedback and questions:
 
 - Join the [Ansible AWX channel on Matrix](https://matrix.to/#/#awx:ansible.com)
 - Join the [Ansible Community Forum](https://forum.ansible.com)

docs/contributors-guide/author.md

@@ -1,3 +1,3 @@
-## Author
+# Author
 
 This operator was originally built in 2019 by [Jeff Geerling](https://www.jeffgeerling.com) and is now maintained by the Ansible Team

docs/contributors-guide/code-of-conduct.md

@@ -1,3 +1,3 @@
-## Code of Conduct
+# Code of Conduct
 
 We ask all of our community members and contributors to adhere to the [Ansible code of conduct](http://docs.ansible.com/ansible/latest/community/code_of_conduct.html). If you have questions or need assistance, please reach out to our community team at [[email protected]](mailto:[email protected])

docs/contributors-guide/contributing.md

@@ -1,3 +1,5 @@
-## Contributing
+# Contributing
 
 Please visit [our contributing guidelines](https://github.com/ansible/awx-operator/blob/devel/CONTRIBUTING.md).
+
+For docs changes, create PRs on the appropriate files in the `/docs` folder.

docs/contributors-guide/get-involved.md

@@ -1,6 +1,6 @@
-## Get Involved
+# Get Involved
 
-We welcome your feedback and ideas. The AWX operator uses the same mailing list and IRC channel as AWX itself. Here's how to reach us with feedback and questions:
+We welcome your feedback and ideas. The AWX operator uses the same Matrix channel and Ansible Community Forum as AWX itself. Here's how to reach us with feedback and questions:
 
-- Join the `#ansible-awx` channel on irc.libera.chat
-- Join the [mailing list](https://groups.google.com/forum/#!forum/awx-project)
+- Join the [Ansible AWX channel on Matrix](https://matrix.to/#/#awx:ansible.com)
+- Join the [Ansible Community Forum](https://forum.ansible.com)

docs/contributors-guide/release-process.md

@@ -1,4 +1,4 @@
-## Release Process
+# Release Process
 
 The first step is to create a draft release. Typically this will happen in the [Stage Release](https://github.com/ansible/awx/blob/devel/.github/workflows/stage.yml) workflow for AWX and you don't need to do it as a separate step.
 
@@ -10,16 +10,18 @@ After the draft release is created, publish it and the [Promote AWX Operator ima
 - Release Helm chart
 
 After the GHA is complete, the final step is to run the [publish-to-operator-hub.sh](https://github.com/ansible/awx-operator/blob/devel/hack/publish-to-operator-hub.sh) script, which will create a PR in the following repos to add the new awx-operator bundle version to OperatorHub:
-* https://github.com/k8s-operatorhub/community-operators (community operator index)
-* https://github.com/redhat-openshift-ecosystem/community-operators-prod (operator index shipped with Openshift)
 
-The usage is documented in the script itself, but here is an example of how you would use the script to publish the 2.5.3 awx-opeator bundle to OperatorHub.
-Note that you need to specify the version being released, as well as the previous version. This is because the bundle has a pointer to the previous version that is it being upgrade from. This is used by OLM to create a dependency graph.
+- <https://github.com/k8s-operatorhub/community-operators> (community operator index)
+- <https://github.com/redhat-openshift-ecosystem/community-operators-prod> (operator index shipped with Openshift)
 
-```bash
-$ VERSION=2.5.3 PREV_VERSION=2.5.2 ./publish-operator.sh
-```
+!!! note
+    The usage is documented in the script itself, but here is an example of how you would use the script to publish the 2.5.3 awx-opeator bundle to OperatorHub.
+    Note that you need to specify the version being released, as well as the previous version. This is because the bundle has a pointer to the previous version that is it being upgrade from. This is used by OLM to create a dependency graph.
 
-> Note: There are some quirks with running this on OS X that still need to be fixed, but the script runs smoothly on linux.
+    ```bash
+    VERSION=2.5.3 PREV_VERSION=2.5.2 ./hack/publish-to-operator-hub.sh
+    ```
+
+    There are some quirks with running this on OS X that still need to be fixed, but the script runs smoothly on linux.
 
 As soon as CI completes successfully, the PR's will be auto-merged. Please remember to monitor those PR's to make sure that CI passes, sometimes it needs a retry.

docs/index.md

@@ -0,0 +1 @@
+../README.md

docs/installation/basic-install.md

@@ -1,6 +1,7 @@
-### Basic Install
+# Basic Install
 
 After cloning this repository, you must choose the tag to run:
+
 ```sh
 git clone [email protected]:ansible/awx-operator.git
 cd awx-operator
@@ -20,17 +21,23 @@ export VERSION=<tag>
 export VERSION=2.7.2
 ```
 
-Once you have a running Kubernetes cluster, you can deploy AWX Operator into your cluster using [Kustomize](https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/). Since kubectl version 1.14 kustomize functionality is built-in (otherwise, follow the instructions here to install the latest version of Kustomize: https://kubectl.docs.kubernetes.io/installation/kustomize/ )
+Once you have a running Kubernetes cluster, you can deploy AWX Operator into your cluster using [Kustomize](https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/). Since kubectl version 1.14 kustomize functionality is built-in (otherwise, follow the instructions here to install the latest version of Kustomize: <https://kubectl.docs.kubernetes.io/installation/kustomize/>)
+
+!!! tip
+    If you don't have a Kubernetes cluster, you can use [Minikube](https://minikube.sigs.k8s.io/docs/) for testing purposes. See the [Minikube install docs](./creating-a-minikube-cluster-for-testing.md) for more details.
 
-> Some things may need to be configured slightly differently for different Kubernetes flavors for the networking aspects. When installing on Kind, see the [kind install docs](./kind-install.md) for more details.
+!!! note
+    Some things may need to be configured slightly differently for different Kubernetes flavors for the networking aspects. When installing on Kind, see the [kind install docs](./kind-install.md) for more details.
 
 There is a make target you can run:
-```
+
+```sh
 make deploy
 ```
 
 If you have a custom operator image you have built, you can specify it with:
-```
+
+```sh
 IMG=quay.io/$YOURNAMESPACE/awx-operator:$YOURTAG make deploy
 ```
 
@@ -52,11 +59,12 @@ images:
 namespace: awx
 ```
 
-> **TIP:** If you need to change any of the default settings for the operator (such as resources.limits), you can add [patches](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/patches/) at the bottom of your kustomization.yaml file.
+!!! tip
+    If you need to change any of the default settings for the operator (such as resources.limits), you can add [patches](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/patches/) at the bottom of your kustomization.yaml file.
 
 Install the manifests by running this:
 
-```
+```sh
 $ kubectl apply -k .
 namespace/awx created
 customresourcedefinition.apiextensions.k8s.io/awxbackups.awx.ansible.com created
@@ -77,21 +85,22 @@ deployment.apps/awx-operator-controller-manager created
 
 Wait a bit and you should have the `awx-operator` running:
 
-```
+```sh
 $ kubectl get pods -n awx
 NAME                                               READY   STATUS    RESTARTS   AGE
 awx-operator-controller-manager-66ccd8f997-rhd4z   2/2     Running   0          11s
 ```
 
 So we don't have to keep repeating `-n awx`, let's set the current namespace for `kubectl`:
 
-```
-$ kubectl config set-context --current --namespace=awx
+```sh
+kubectl config set-context --current --namespace=awx
 ```
 
 Next, create a file named `awx-demo.yml` in the same folder with the suggested content below. The `metadata.name` you provide will be the name of the resulting AWX deployment.
 
-**Note:** If you deploy more than one AWX instance to the same namespace, be sure to use unique names.
+!!! note
+    If you deploy more than one AWX instance to the same namespace, be sure to use unique names.
 
 ```yaml
 ---
@@ -103,7 +112,8 @@ spec:
   service_type: nodeport
 ```
 
-> It may make sense to create and specify your own secret key for your deployment so that if the k8s secret gets deleted, it can be re-created if needed.  If it is not provided, one will be auto-generated, but cannot be recovered if lost. Read more [here](../user-guide/admin-user-account-configuration.md#secret-key-configuration).
+!!! tip
+    It may make sense to create and specify your own secret key for your deployment so that if the k8s secret gets deleted, it can be re-created if needed.  If it is not provided, one will be auto-generated, but cannot be recovered if lost. Read more [here](../user-guide/admin-user-account-configuration.md#secret-key-configuration).
 
 If you are on Openshift, you can take advantage of Routes by specifying the following your spec. This will automatically create a Route for you with a custom hostname. This can be found on the Route section of the Openshift Console.
 
@@ -118,8 +128,7 @@ spec:
   ingress_type: Route
 ```
 
-
-Make sure to add this new file to the list of "resources" in your `kustomization.yaml` file:
+Make sure to add this new file to the list of `resources` in your `kustomization.yaml` file:
 
 ```yaml
 ...
@@ -132,19 +141,13 @@ resources:
 
 Finally, apply the changes to create the AWX instance in your cluster:
 
-```
+```sh
 kubectl apply -k .
 ```
 
-After a few minutes, the new AWX instance will be deployed. You can look at the operator pod logs in order to know where the installation process is at:
-
-```
-$ kubectl logs -f deployments/awx-operator-controller-manager -c awx-manager
-```
-
 After a few seconds, you should see the operator begin to create new resources:
 
-```
+```sh
 $ kubectl get pods -l "app.kubernetes.io/managed-by=awx-operator"
 NAME                        READY   STATUS    RESTARTS   AGE
 awx-demo-77d96f88d5-pnhr8   4/4     Running   0          3m24s
@@ -156,19 +159,19 @@ awx-demo-postgres   ClusterIP   None           <none>        5432/TCP       4m4s
 awx-demo-service    NodePort    10.109.40.38   <none>        80:31006/TCP   3m56s
 ```
 
-Once deployed, the AWX instance will be accessible by running:
+After a few minutes, the new AWX instance will be deployed. You can look at the operator pod logs in order to know where the installation process is at:
 
+```sh
+kubectl logs -f deployments/awx-operator-controller-manager -c awx-manager
 ```
-$ minikube service -n awx awx-demo-service --url
-```
+
+Once deployed, your AWX instance should now be reachable at `http://localhost:<assigned-nodeport>/` (in this case, `http://localhost:31006/`).
 
 By default, the admin user is `admin` and the password is available in the `<resourcename>-admin-password` secret. To retrieve the admin password, run:
 
-```
+```sh
 $ kubectl get secret awx-demo-admin-password -o jsonpath="{.data.password}" | base64 --decode ; echo
 yDL2Cx5Za94g9MvBP6B73nzVLlmfgPjR
 ```
 
 You just completed the most basic install of an AWX instance via this operator. Congratulations!!!
-
-For an example using the Nginx Ingress Controller in Minikube, don't miss our [demo video](https://asciinema.org/a/416946).

docs/installation/creating-a-minikube-cluster-for-testing.md

@@ -1,8 +1,8 @@
-### Creating a minikube cluster for testing
+# Creating a minikube cluster for testing
 
 If you do not have an existing cluster, the `awx-operator` can be deployed on a [Minikube](https://minikube.sigs.k8s.io/docs/) cluster for testing purposes. Due to different OS and hardware environments, please refer to the official Minikube documentation for further information.
 
-```
+```sh
 $ minikube start --cpus=4 --memory=6g --addons=ingress
 😄  minikube v1.23.2 on Fedora 34
 ✨  Using the docker driver based on existing profile
@@ -22,7 +22,7 @@ $ minikube start --cpus=4 --memory=6g --addons=ingress
 
 Once Minikube is deployed, check if the node(s) and `kube-apiserver` communication is working as expected.
 
-```
+```sh
 $ minikube kubectl -- get nodes
 NAME       STATUS   ROLES                  AGE    VERSION
 minikube   Ready    control-plane,master   113s   v1.22.2
@@ -45,6 +45,17 @@ It is not required for `kubectl` to be separately installed since it comes alrea
 
 Let's create an alias for easier usage:
 
+```sh
+alias kubectl="minikube kubectl --"
 ```
-$ alias kubectl="minikube kubectl --"
-```
+
+Now, you can proceed with the installation of the AWX Operator and AWX. Please refer to the [Basic Install](basic-install.md) for further instructions.
+
+!!! tip
+    Once your AWX has been deployed, the AWX instance will be accessible by running:
+
+    ```sh
+    minikube service -n awx awx-demo-service --url
+    ```
+
+For an example using the Nginx Ingress Controller in Minikube, don't miss our [demo video](https://asciinema.org/a/416946).

docs/installation/helm-install-on-existing-cluster.md

@@ -1,4 +1,4 @@
-### Helm Install on existing cluster
+# Helm Install on existing cluster
 
 For those that wish to use [Helm](https://helm.sh/) to install the awx-operator to an existing K8s cluster: