From 71362dd3d4173ec5997ea648cbb16d5021573f1b Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 3 Aug 2023 15:13:11 -0400 Subject: [PATCH] Add new docs files to mkdocs (#1507) --- docs/README.md | 8 +++ docs/doc-proposal.md | 29 ---------- docs/index.md | 3 +- .../helm-install-on-existing-cluster.md | 2 +- .../{installation.md => index.md} | 1 - docs/introduction/introduction.md | 3 - docs/requirements.txt | 6 +- .../advanced-configuration/doc-proposal.md | 29 ---------- docs/user-guide/database-configuration.md | 4 +- mkdocs.yml | 57 +++++++++++++++++-- 10 files changed, 68 insertions(+), 74 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/doc-proposal.md rename docs/installation/{installation.md => index.md} (93%) delete mode 100644 docs/introduction/introduction.md delete mode 100644 docs/user-guide/advanced-configuration/doc-proposal.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..25fb2738 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +# Building the Ansible AWX Operator Docs + +To build the AWX Operator docs locally: + +1. Clone the AWX operator repository. +2. From the root directory: + a. pip install --user -r docs/requirements.txt + b. mkdocs build \ No newline at end of file diff --git a/docs/doc-proposal.md b/docs/doc-proposal.md deleted file mode 100644 index c19ea5c6..00000000 --- a/docs/doc-proposal.md +++ /dev/null @@ -1,29 +0,0 @@ -# Docs Breakdown for AWX Operator - -## Introduction - -This table below is aimed at breaking down the ReadME documentation for Ansible AWX Operator and structure it in the way it can be moved to the Read The Docs module. - -From the ReadMe file, the documentation can be classified into six distinct segments which are: - - -- Introduction/Getting Started -- Installation -- User Guide -- Upgrade -- Uninstall -- Contributors Guide - -Using these listed segments, we can do a proper breakdown of all the topics in the ReadMe and place each one in the segment they fall into. This table is open to any form of refactoring or modifications. - -| Segments | Topics | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Introduction | - [Purpose](https://github.com/ansible/awx-operator#purpose) | -| Installation | - [Creating a minikube cluster for testing](https://github.com/ansible/awx-operator#creating-a-minikube-cluster-for-testing)
- [Basic Install](https://github.com/ansible/awx-operator#basic-install)
- [Helm Install on existing cluster](https://github.com/ansible/awx-operator#helm-install-on-existing-cluster) | -| User Guide | - [Admin user account configuration](https://github.com/ansible/awx-operator#admin-user-account-configuration)
- [Network and TLS Configuration](https://github.com/ansible/awx-operator#network-and-tls-configuration)
* [Service Type](https://github.com/ansible/awx-operator#service-type)
* [Ingress Type](https://github.com/ansible/awx-operator#ingress-type)
- [Database Configuration](https://github.com/ansible/awx-operator#database-configuration)
* [External PostgreSQL Service](https://github.com/ansible/awx-operator#external-postgresql-service)
* [Migrating data from an old AWX instance](https://github.com/ansible/awx-operator#migrating-data-from-an-old-awx-instance)
* [Managed PostgreSQL Service](https://github.com/ansible/awx-operator#managed-postgresql-service)
- [Advanced Configuration](https://github.com/ansible/awx-operator#advanced-configuration)
* [Deploying a specific version of AWX](https://github.com/ansible/awx-operator#deploying-a-specific-version-of-awx)
* [Redis container capabilities](https://github.com/ansible/awx-operator#redis-container-capabilities)
* [Privileged Tasks](https://github.com/ansible/awx-operator#privileged-tasks)
* [Containers Resource Requirements](https://github.com/ansible/awx-operator#containers-resource-requirements)
* [Priority Classes](https://github.com/ansible/awx-operator#priority-classes)
* [Assigning AWX pods to specific nodes](https://github.com/ansible/awx-operator#assigning-awx-pods-to-specific-nodes)
* [Trusting a Custom Certificate Authority](https://github.com/ansible/awx-operator#trusting-a-custom-certificate-authority)
* [Enabling LDAP Integration at AWX bootstrap](https://github.com/ansible/awx-operator#enabling-ldap-integration-at-awx-bootstrap)
* [Persisting Projects Directory](https://github.com/ansible/awx-operator#persisting-projects-directory)
* [Custom Volume and Volume Mount Options](https://github.com/ansible/awx-operator#custom-volume-and-volume-mount-options)
* [Default execution environments from private registries](https://github.com/ansible/awx-operator#default-execution-environments-from-private-registries)
* * [Control plane ee from private registry](https://github.com/ansible/awx-operator#control-plane-ee-from-private-registry)
* [Exporting Environment Variables to Containers](https://github.com/ansible/awx-operator#exporting-environment-variables-to-containers)
* [CSRF Cookie Secure Setting](https://github.com/ansible/awx-operator#csrf-cookie-secure-setting)
* [Session Cookie Secure Setting](https://github.com/ansible/awx-operator#session-cookie-secure-setting)
* [Extra Settings](https://github.com/ansible/awx-operator#extra-settings)
* [Configure no_log](https://github.com/ansible/awx-operator#no-log)
* [Auto Upgrade](https://github.com/ansible/awx-operator#auto-upgrade)
** [Upgrade of instances without auto upgrade](https://github.com/ansible/awx-operator#upgrade-of-instances-without-auto-upgrade)
* [Service Account](https://github.com/ansible/awx-operator#service-account)
* [Labeling operator managed objects](https://github.com/ansible/awx-operator#labeling-operator-managed-objects)
* [Pods termination grace period](https://github.com/ansible/awx-operator#pods-termination-grace-period)
* [Disable IPV6](https://github.com/ansible/awx-operator#disable-ipv6)
* [Add Execution Nodes](https://github.com/ansible/awx-operator#adding-execution-nodes)
** [Custom Receptor CA](https://github.com/ansible/awx-operator#custom-receptor-ca)
* [Debugging](https://github.com/ansible/awx-operator/blob/devel/docs/debugging.md)
* [Migration](https://github.com/ansible/awx-operator/blob/devel/docs/migration.md) | -| Upgrade | - [Upgrading](https://github.com/ansible/awx-operator#upgrading)
* [Backup](https://github.com/ansible/awx-operator#backup)
* [v0.14.0](https://github.com/ansible/awx-operator#v0140)
** [Cluster-scope to Namespace-scope considerations](https://github.com/ansible/awx-operator#cluster-scope-to-namespace-scope-considerations)
** [Project is now based on v1.x of the operator-sdk project](https://github.com/ansible/awx-operator#project-is-now-based-on-v1x-of-the-operator-sdk-project)
** [Steps to upgrade](https://github.com/ansible/awx-operator#steps-to-upgrade) | -| Uninstall | - [Uninstall](https://github.com/ansible/awx-operator#uninstall) | -| Contributors Guide | - [Contributing](https://github.com/ansible/awx-operator#contributing)
- [Release Process](https://github.com/ansible/awx-operator#release-process)
- [Author](https://github.com/ansible/awx-operator#author)
- [Code of Conduct](https://github.com/ansible/awx-operator#code-of-conduct)
- [Get Involved](https://github.com/ansible/awx-operator#get-involved) | - - -Note: I could not get the multi-level bullet point list to work in the table so I used single asterisk `*` for one level down and double asterisk `**` for two level down. diff --git a/docs/index.md b/docs/index.md index 8357ff8a..4ca40f46 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1,2 @@ -# Welcome to the documentation of ansible awx-operator + +The AWX operator is meant to provide a more Kubernetes-native installation method for AWX via an AWX Custom Resource Definition (CRD). diff --git a/docs/installation/helm-install-on-existing-cluster.md b/docs/installation/helm-install-on-existing-cluster.md index 6963fff5..89e50edf 100644 --- a/docs/installation/helm-install-on-existing-cluster.md +++ b/docs/installation/helm-install-on-existing-cluster.md @@ -2,7 +2,7 @@ For those that wish to use [Helm](https://helm.sh/) to install the awx-operator to an existing K8s cluster: -The helm chart is generated from the `helm-chart` Makefile section using the starter files in `.helm/starter`. Consult [the documentation](.helm/starter/README.md) on how to customize the AWX resource with your own values. +The helm chart is generated from the `helm-chart` Makefile section using the starter files in `.helm/starter`. Consult [the documentation](https://github.com/ansible/awx-operator/blob/devel/.helm/starter/README.md) on how to customize the AWX resource with your own values. ```bash $ helm repo add awx-operator https://ansible.github.io/awx-operator/ diff --git a/docs/installation/installation.md b/docs/installation/index.md similarity index 93% rename from docs/installation/installation.md rename to docs/installation/index.md index cf058aaa..e6978804 100644 --- a/docs/installation/installation.md +++ b/docs/installation/index.md @@ -1,3 +1,2 @@ -## Usage This Kubernetes Operator is meant to be deployed in your Kubernetes cluster(s) and can manage one or more AWX instances in any namespace. diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md deleted file mode 100644 index 29b620cf..00000000 --- a/docs/introduction/introduction.md +++ /dev/null @@ -1,3 +0,0 @@ -## Purpose - -This operator is meant to provide a more Kubernetes-native installation method for AWX via an AWX Custom Resource Definition (CRD). diff --git a/docs/requirements.txt b/docs/requirements.txt index 3e3a2e5e..03d019fb 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,10 +1,10 @@ cairosvg==2.7.0 markdown-exec>=1.6.0 -mkdocs-ansible[lock]>=0.1.6 +mkdocs-ansible>=0.1.6 mkdocs-gen-files>=0.4.0 mkdocs-material-extensions>=1.1.1 -mkdocs-material>=9.1.15 -mkdocs==1.4.3 +mkdocs-material>=9.1.18 +mkdocs mkdocstrings-python>=1.1.0 mkdocstrings>=0.22.0 pillow==9.5.0 diff --git a/docs/user-guide/advanced-configuration/doc-proposal.md b/docs/user-guide/advanced-configuration/doc-proposal.md deleted file mode 100644 index c19ea5c6..00000000 --- a/docs/user-guide/advanced-configuration/doc-proposal.md +++ /dev/null @@ -1,29 +0,0 @@ -# Docs Breakdown for AWX Operator - -## Introduction - -This table below is aimed at breaking down the ReadME documentation for Ansible AWX Operator and structure it in the way it can be moved to the Read The Docs module. - -From the ReadMe file, the documentation can be classified into six distinct segments which are: - - -- Introduction/Getting Started -- Installation -- User Guide -- Upgrade -- Uninstall -- Contributors Guide - -Using these listed segments, we can do a proper breakdown of all the topics in the ReadMe and place each one in the segment they fall into. This table is open to any form of refactoring or modifications. - -| Segments | Topics | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Introduction | - [Purpose](https://github.com/ansible/awx-operator#purpose) | -| Installation | - [Creating a minikube cluster for testing](https://github.com/ansible/awx-operator#creating-a-minikube-cluster-for-testing)
- [Basic Install](https://github.com/ansible/awx-operator#basic-install)
- [Helm Install on existing cluster](https://github.com/ansible/awx-operator#helm-install-on-existing-cluster) | -| User Guide | - [Admin user account configuration](https://github.com/ansible/awx-operator#admin-user-account-configuration)
- [Network and TLS Configuration](https://github.com/ansible/awx-operator#network-and-tls-configuration)
* [Service Type](https://github.com/ansible/awx-operator#service-type)
* [Ingress Type](https://github.com/ansible/awx-operator#ingress-type)
- [Database Configuration](https://github.com/ansible/awx-operator#database-configuration)
* [External PostgreSQL Service](https://github.com/ansible/awx-operator#external-postgresql-service)
* [Migrating data from an old AWX instance](https://github.com/ansible/awx-operator#migrating-data-from-an-old-awx-instance)
* [Managed PostgreSQL Service](https://github.com/ansible/awx-operator#managed-postgresql-service)
- [Advanced Configuration](https://github.com/ansible/awx-operator#advanced-configuration)
* [Deploying a specific version of AWX](https://github.com/ansible/awx-operator#deploying-a-specific-version-of-awx)
* [Redis container capabilities](https://github.com/ansible/awx-operator#redis-container-capabilities)
* [Privileged Tasks](https://github.com/ansible/awx-operator#privileged-tasks)
* [Containers Resource Requirements](https://github.com/ansible/awx-operator#containers-resource-requirements)
* [Priority Classes](https://github.com/ansible/awx-operator#priority-classes)
* [Assigning AWX pods to specific nodes](https://github.com/ansible/awx-operator#assigning-awx-pods-to-specific-nodes)
* [Trusting a Custom Certificate Authority](https://github.com/ansible/awx-operator#trusting-a-custom-certificate-authority)
* [Enabling LDAP Integration at AWX bootstrap](https://github.com/ansible/awx-operator#enabling-ldap-integration-at-awx-bootstrap)
* [Persisting Projects Directory](https://github.com/ansible/awx-operator#persisting-projects-directory)
* [Custom Volume and Volume Mount Options](https://github.com/ansible/awx-operator#custom-volume-and-volume-mount-options)
* [Default execution environments from private registries](https://github.com/ansible/awx-operator#default-execution-environments-from-private-registries)
* * [Control plane ee from private registry](https://github.com/ansible/awx-operator#control-plane-ee-from-private-registry)
* [Exporting Environment Variables to Containers](https://github.com/ansible/awx-operator#exporting-environment-variables-to-containers)
* [CSRF Cookie Secure Setting](https://github.com/ansible/awx-operator#csrf-cookie-secure-setting)
* [Session Cookie Secure Setting](https://github.com/ansible/awx-operator#session-cookie-secure-setting)
* [Extra Settings](https://github.com/ansible/awx-operator#extra-settings)
* [Configure no_log](https://github.com/ansible/awx-operator#no-log)
* [Auto Upgrade](https://github.com/ansible/awx-operator#auto-upgrade)
** [Upgrade of instances without auto upgrade](https://github.com/ansible/awx-operator#upgrade-of-instances-without-auto-upgrade)
* [Service Account](https://github.com/ansible/awx-operator#service-account)
* [Labeling operator managed objects](https://github.com/ansible/awx-operator#labeling-operator-managed-objects)
* [Pods termination grace period](https://github.com/ansible/awx-operator#pods-termination-grace-period)
* [Disable IPV6](https://github.com/ansible/awx-operator#disable-ipv6)
* [Add Execution Nodes](https://github.com/ansible/awx-operator#adding-execution-nodes)
** [Custom Receptor CA](https://github.com/ansible/awx-operator#custom-receptor-ca)
* [Debugging](https://github.com/ansible/awx-operator/blob/devel/docs/debugging.md)
* [Migration](https://github.com/ansible/awx-operator/blob/devel/docs/migration.md) | -| Upgrade | - [Upgrading](https://github.com/ansible/awx-operator#upgrading)
* [Backup](https://github.com/ansible/awx-operator#backup)
* [v0.14.0](https://github.com/ansible/awx-operator#v0140)
** [Cluster-scope to Namespace-scope considerations](https://github.com/ansible/awx-operator#cluster-scope-to-namespace-scope-considerations)
** [Project is now based on v1.x of the operator-sdk project](https://github.com/ansible/awx-operator#project-is-now-based-on-v1x-of-the-operator-sdk-project)
** [Steps to upgrade](https://github.com/ansible/awx-operator#steps-to-upgrade) | -| Uninstall | - [Uninstall](https://github.com/ansible/awx-operator#uninstall) | -| Contributors Guide | - [Contributing](https://github.com/ansible/awx-operator#contributing)
- [Release Process](https://github.com/ansible/awx-operator#release-process)
- [Author](https://github.com/ansible/awx-operator#author)
- [Code of Conduct](https://github.com/ansible/awx-operator#code-of-conduct)
- [Get Involved](https://github.com/ansible/awx-operator#get-involved) | - - -Note: I could not get the multi-level bullet point list to work in the table so I used single asterisk `*` for one level down and double asterisk `**` for two level down. diff --git a/docs/user-guide/database-configuration.md b/docs/user-guide/database-configuration.md index fdf98145..556e8fe4 100644 --- a/docs/user-guide/database-configuration.md +++ b/docs/user-guide/database-configuration.md @@ -2,7 +2,7 @@ #### Postgres Version -The default Postgres version for the version of AWX bundled with the latest version of the awx-operator is Postgres 13. You can find this default for a given version by at the default value for [_postgres_image_version](./roles/installer/defaults/main.yml#L138). +The default Postgres version for the version of AWX bundled with the latest version of the awx-operator is Postgres 13. You can find this default for a given version by at the default value for [_postgres_image_version](https://github.com/ansible/awx-operator/blob/devel/roles/installer/defaults/main.yml#L243). We only have coverage for the default version of Postgres. Newer versions of Postgres (14+) will likely work, but should only be configured as an external database. If your database is managed by the awx-operator (default if you don't specify a `postgres_configuration_secret`), then you should not override the default version as this may cause issues when awx-operator tries to upgrade your postgresql pod. @@ -48,7 +48,7 @@ spec: #### Migrating data from an old AWX instance -For instructions on how to migrate from an older version of AWX, see [migration.md](/docs/migration/migration.md). +For instructions on how to migrate from an older version of AWX, see [migration.md](../migration/migration.md). #### Managed PostgreSQL Service diff --git a/mkdocs.yml b/mkdocs.yml index 8f8a1f52..1a089711 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ --- -site_name: awx-operator +site_name: Ansible AWX Operator Documentation site_url: https://awx-operator.readthedocs.io/ repo_url: https://github.com/ansible/awx-operator edit_uri: blob/devel/docs/ @@ -8,7 +8,7 @@ strict: true use_directory_urls: false theme: - name: "material" + name: "ansible" features: - content.code.copy - content.action.edit @@ -35,9 +35,56 @@ theme: name: Switch to light mode nav: - - home: index.md - - debugging.md - - migration.md + - index.md + - Contributors Guide: + - contributors-guide/contributing.md + - contributors-guide/release-process.md + - contributors-guide/author.md + - contributors-guide/code-of-conduct.md + - contributors-guide/get-involved.md + - Installation: + - Installation: installation/index.md + - installation/basic-install.md + - installation/creating-a-minikube-cluster-for-testing.md + - installation/helm-install-on-existing-cluster.md + - Migrate: + - migration/migration.md + - Uninstall: + - uninstall/uninstall.md + - User Guide: + - user-guide/admin-user-account-configuration.md + - user-guide/network-and-tls-configuration.md + - user-guide/database-configuration.md + - Upgrade: + - upgrade/upgrading.md + - Advanced Configuration: + - user-guide/advanced-configuration/deploying-a-specific-version-of-awx.md + - user-guide/advanced-configuration/redis-container-capabilities.md + - user-guide/advanced-configuration/privileged-tasks.md + - user-guide/advanced-configuration/containers-resource-requirements.md + - user-guide/advanced-configuration/priority-classes.md + - user-guide/advanced-configuration/scaling-the-web-and-task-pods-independently.md + - user-guide/advanced-configuration/assigning-awx-pods-to-specific-nodes.md + - user-guide/advanced-configuration/trusting-a-custom-certificate-authority.md + - user-guide/advanced-configuration/enabling-ldap-integration-at-awx-bootstrap.md + - user-guide/advanced-configuration/persisting-projects-directory.md + - user-guide/advanced-configuration/custom-volume-and-volume-mount-options.md + - user-guide/advanced-configuration/default-execution-environments-from-private-registries.md + - user-guide/advanced-configuration/exporting-environment-variables-to-containers.md + - user-guide/advanced-configuration/csrf-cookie-secure-setting.md + - user-guide/advanced-configuration/session-cookie-secure-setting.md + - user-guide/advanced-configuration/extra-settings.md + - user-guide/advanced-configuration/no-log.md + - user-guide/advanced-configuration/auto-upgrade.md + - user-guide/advanced-configuration/service-account.md + - user-guide/advanced-configuration/labeling-operator-managed-objects.md + - user-guide/advanced-configuration/pods-termination-grace-period.md + - user-guide/advanced-configuration/disable-ipv6.md + - Troubleshooting: + - troubleshooting/debugging.md + +exclude_docs: + README.md plugins: - autorefs