Add user facing documentation and mkdoc

The mkdoc is used to generate a dynamic pages with a user documentation.
The documentation is common for ISV and community operators. The docs
will server as a official doc for operator users.

The mkdoc will run whenever a doc is updated and will be released to
Github hosted environment.

JIRA: ISV-4507

Signed-off-by: Ales Raszka <[email protected]>

Author: Allda

.github/workflows/documentation.yaml

@@ -0,0 +1,29 @@
+---
+name: "Documentation"
+
+on:
+  push:
+    paths:
+      - docs/**
+      - mkdocs.yml
+  workflow_dispatch:
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Generate docs
+        run: |
+          pip install mkdocs \
+            mkdocs-material \
+            pymdown-extensions \
+            mkdocs-mermaid2-plugin
+
+          mkdocs build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

docs/README.md

@@ -0,0 +1,68 @@
+# Openshift Operators
+
+## About this repository
+
+This repo is the canonical source for Kubernetes Operators that appear on [OpenShift Container Platform](https://openshift.com) and [OKD](https://www.okd.io/).
+
+**NOTE** The index catalogs:
+
+- `registry.redhat.io/redhat/certified-operator-index:v<OCP Version>`
+- `registry.redhat.io/redhat/redhat-marketplace-index:v<OCP Version>`
+- `registry.redhat.io/redhat/community-operator-index:v<OCP Version>`
+
+are built from this repository and it is
+consumed by Openshift and OKD to create their sources and built their catalog. To know more about how
+Openshift catalog are built see the [documentation](https://docs.openshift.com/container-platform/4.14/operators/understanding/olm-rh-catalogs.html#olm-rh-catalogs_olm-rh-catalogs).
+
+See our [documentation](https://redhat-openshift-ecosystem.github.io/operator-pipelines/) to find out
+more about Community, Certified and Marketplace operators and contribution.
+
+## Add your Operator
+
+We would love to see your Operator added to this collection. We currently use automated vetting via continuous integration plus manual review to curate a list of high-quality, well-documented Operators. If you are new to Kubernetes Operators start [here](https://sdk.operatorframework.io/build/).
+
+If you have an existing Operator read our contribution guidelines on how to [open a PR](contributing-via-pr.md). Then the community operator pipeline will be triggered to test your Operator and merge a Pull Request.
+
+## Contributing Guide
+
+- [Prerequisites](contributing-prerequisites.md)
+- [Where to place operator](contributing-where-to.md)
+- [Creating pull request (PR)](contributing-via-pr.md)
+- [Operator Publishing / Review settings](operator-ci-yaml.md)
+- [OKD/OpenShift Catalogs criteria and options](packaging-required-criteria-ocp.md)
+
+## Test and release process for the Operator
+
+Refer to the [operator pipeline documentation](docs/pipelines_overview.md) .
+
+## IMPORTANT NOTICE
+
+Some APIs versions are deprecated and are OR will no longer be served on the Kubernetes version
+`1.22/1.25/1.26` and consequently on vendors like Openshift `4.9/4.12/4.13`.
+
+**What does it mean for you?**
+
+Operator bundle versions using the removed APIs can not work successfully from the respective releases.
+Therefore, it is recommended to check if your solutions are failing in these scenarios to stop using these versions
+OR by setting the `"olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "<OCP version>"}]'`
+to block cluster admins upgrades when they have Operator versions installed that can **not**
+work well in OCP versions higher than the value informed. Also, by defining a valid OCP range via the annotation `com.redhat.openshift.versions`
+into the `metadata/annotations.yaml` for our solution does **not** end up shipped on OCP/OKD versions where it cannot be installed.
+
+> WARNING: `olm.maxOpenShiftVersion` should ONLY be used if you are 100% sure that your Operator bundle version
+> cannot work in upper releases. Otherwise, you might provide a bad user experience. Be aware that cluster admins
+> will be unable to upgrade their clusters with your solution installed. Then, suppose you do not provide any upper
+> version and a valid upgrade path for those who have your Operator installed be able to upgrade it and consequently
+> be allowed to upgrade their cluster version (i.e from OCP 4.10 to 4.11). In that case, cluster admins might
+> choose to uninstall your Operator and no longer use it so that they can move forward and upgrade their cluster
+> version without it.
+
+Please, make sure you check the following announcements:
+- [How to deal with removal of v1beta1 CRD removals in Kubernetes 1.22 / OpenShift 4.9](https://github.com/redhat-openshift-ecosystem/community-operators-prod/discussions/138)
+- [Kubernetes API removals on 1.25/1.26 and Openshift 4.12/4.13 might impact your Operator. How to deal with it?](https://github.com/redhat-openshift-ecosystem/community-operators-prod/discussions/1182)
+
+## Reporting Bugs
+
+Use the issue tracker in this repository to report bugs.
+
+[k8s-deprecated-guide]: https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22

docs/img/op_pr_tests_failed.png

@@ -4,20 +4,20 @@ This document aims to provide information needed for maintenance and troubleshoo
 
 ## Operator repositories
 - Certified operators
-  - prod: https://github.com/redhat-openshift-ecosystem/certified-operators
-  - nonprod: https://github.com/redhat-openshift-ecosystem/certified-operators-preprod
+    - prod: https://github.com/redhat-openshift-ecosystem/certified-operators
+    - nonprod: https://github.com/redhat-openshift-ecosystem/certified-operators-preprod
 - Marketplace operators
-  - prod: https://github.com/redhat-openshift-ecosystem/redhat-marketplace-operators
-  - nonprod: https://github.com/redhat-openshift-ecosystem/redhat-marketplace-operators-preprod
+    - prod: https://github.com/redhat-openshift-ecosystem/redhat-marketplace-operators
+    - nonprod: https://github.com/redhat-openshift-ecosystem/redhat-marketplace-operators-preprod
 - Community OCP operators
-  - prod: https://github.com/redhat-openshift-ecosystem/community-operators-prod
-  - nonprod: https://github.com/redhat-openshift-ecosystem/community-operators-pipeline-preprod/
+    - prod: https://github.com/redhat-openshift-ecosystem/community-operators-prod
+    - nonprod: https://github.com/redhat-openshift-ecosystem/community-operators-pipeline-preprod/
 
 Pre-production repositories are used for all pre-prod environments (stage, dev, qa). Each environment has a dedicated git branch. By selecting a target branch you can select an environment where the operator will be tested.
 
 ## OCP environments
-https://console-openshift-console.apps.pipelines-prod.ijdb.p1.openshiftapps.com/pipelines/ns/operator-pipeline-prod
-https://console-openshift-console.apps.pipelines-stage.0ce8.p1.openshiftapps.com/pipelines/ns/operator-pipeline-stage
+- https://console-openshift-console.apps.pipelines-prod.ijdb.p1.openshiftapps.com/pipelines/ns/operator-pipeline-prod
+- https://console-openshift-console.apps.pipelines-stage.0ce8.p1.openshiftapps.com/pipelines/ns/operator-pipeline-stage
 
 ## Pipelines
 
@@ -29,8 +29,8 @@ Testing and certification of OpenShift operators from ISV and Community sources
 - **ISV Release pipeline** - The release pipeline distributes ISV operator to all index images supported by the operator bundle and make sure the new operator is visible on Red Hat Ecosystem catalog.
 
 ### Community pipelines
-- **Community Hosted pipeline** - Similarly as the ISV hosted pipeline, the community hosted pipeline verifies if a new operator bundle follows all pre-defined rules and passes all the community tests. The pipeline verifies that operator can be installed on a OCP cluster. A Preflight tools is used to execute a dynamic test suite
-- **Community Release pipeline** - The release pipeline distributes a community operators into OCP catalog.
+- **Hosted pipeline** - Similarly as the ISV hosted pipeline, the community hosted pipeline verifies if a new operator bundle follows all pre-defined rules and passes all the community tests. The pipeline verifies that operator can be installed on a OCP cluster. A Preflight tools is used to execute a dynamic test suite
+- **Release pipeline** - The release pipeline distributes a community operators into OCP catalog.
 
 ## Troubleshooting
 
@@ -62,8 +62,6 @@ Based on which pipeline fails one of these command can be used to re-trigger it
 
 - `/pipeline restart operator-hosted-pipeline`
 - `/pipeline restart operator-release-pipeline`
-- `/pipeline restart community-hosted-pipeline`
-- `/pipeline restart community-release-pipeline`
 
 ![re-trigger](img/re-trigger.png "Example of the re-trigger command.")
 

docs/img/op_test_pr.png

@@ -0,0 +1,6 @@
+# Operator Best Practices
+
+Check the sections Best Practices for OLM and SDK projects to know more about its best practices and common recommendations, suggestions and conventions, see:
+
+- [SDK best practices](https://sdk.operatorframework.io/docs/best-practices/)
+- [OLM best practices](https://olm.operatorframework.io/docs/best-practices/)

docs/img/preflight_run_logs_example.png

@@ -0,0 +1,74 @@
+# Before submitting your Operator
+
+> **Important:** "First off, thanks for taking the time to contribute your Operator!"
+
+## A primer to Openshift Community Operators
+
+This project collects Community Operators that work with OpenShift to be displayed in the embedded OperatorHub. If you are new to Operators, start [here](https://operatorframework.io/).
+
+## Sign Your Work
+
+The contribution process works off standard git _Pull Requests_. Every PR needs to be signed. The sign-off is a simple line at the end of the explanation for a commit. Your signature certifies that you wrote the patch or otherwise have the right to contribute the material. The rules are pretty simple if you can certify the below (from [developercertificate.org](https://developercertificate.org/)):
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```
+
+Then you just add a line to every git commit message:
+
+    Signed-off-by: John Doe <[email protected]>
+
+Use your real name (sorry, no pseudonyms or anonymous contributions.)
+
+If you set your `user.name` and `user.email` git configs, you can sign your commit automatically with `git commit -s`.
+
+Note: If your git config information is set properly then viewing the `git log` information for your commit will look something like this:
+
+```
+Author: John Doe <[email protected]>
+Date:   Mon Oct 21 12:23:17 2019 -0800
+
+    Update README
+
+    Signed-off-by: John Doe <[email protected]>
+```
+
+Notice the `Author` and `Signed-off-by` lines **must match**.
+
+

docs/img/static_tests_example.png

@@ -0,0 +1,40 @@
+# Submitting your Operator via Pull Requests (PR) in community operators project
+
+## Overview
+To submit an operator one has to do these steps
+
+1. Fork project `https://github.com/redhat-openshift-ecosystem/community-operators-prod`
+1. Make a pull request
+1. Place the operator in the target directory. [More info](./contributing-where-to.md)
+    - operators
+1. Configure `ci.yaml` file. [More info](./operator-ci-yaml.md)
+    - Setup reviewers
+    - Operator versioning strategy
+1. Verify tests and fix problems, if possible
+1. Ask for help in the PR in case of problems
+
+
+## Pull request
+
+When a pull request is created, a number of tests are executed via community hosted pipeline. One can see the results in the comment section of conversation tab.
+
+![PR](../img/op_test_pr.png)
+
+## You are done
+User is done when all tests are green. When the PR is merged, the community release pipeline will be triggered.
+
+## Test results failed?
+When operator tests are failing, one can see a following picture
+
+![Summary of test results when failing](../img/op_pr_tests_failed.png)
+
+In case of failures, please have a look at the logs of specific tests. If an error is not clear to you, please ask in the PR. Maintainers will be happy to help you with it.
+
+## Useful commands interacting with the pipeline
+You can post the following comment/command:
+
+Command | Functionality |
+--- | --- |
+`/pipeline restart operator-hosted-pipeline` | The hosted pipeline will be re-triggered and PR will be merged if possible. |
+`/pipeline restart operator-release-pipeline` | The release pipeline will be re-triggered.
+`/test skip {test_case_name}` | *test_case_name* test will be skipped. Please consider that only a subset of tests (*currently only pruned graph test*) can be skipped.