Split Readme up into multiple files

[samccann]

Please confirm the following

• I agree to follow this project's code of conduct.
• I have checked the current issues for duplicates.
• I understand that AWX Operator is open source software provided for free and that I might not receive a timely response.

Feature Summary

In preparation for creating a docsite, split up the existing readme into multiple smaller files in the /docs folder.

• draft out a proposal for how to split the file up. Use a comment in this github issue to describe the proposed set of new files.
• Once the writers agree, move that information into the agreed list of files.
• Leave everything from Contributing section to the end of the README file in the README file.
• Leave everything BEFORE the Table of contents in the README file.
• Add the new files to the mkdocs.yml and test the docs build

[samccann]

@DesmondSanctity will start this by creating a proposal on how to breakdown the readme file.

[DesmondSanctity]

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
Installation	- Creating a minikube cluster for testing - Basic Install - Helm Install on existing cluster
User Guide	- Admin user account configuration - Network and TLS Configuration * Service Type * Ingress Type - Database Configuration * External PostgreSQL Service * Migrating data from an old AWX instance * Managed PostgreSQL Service - Advanced Configuration * Deploying a specific version of AWX * Redis container capabilities * Privileged Tasks * Containers Resource Requirements * Priority Classes * Assigning AWX pods to specific nodes * Trusting a Custom Certificate Authority * Enabling LDAP Integration at AWX bootstrap * Persisting Projects Directory * Custom Volume and Volume Mount Options * Default execution environments from private registries * * Control plane ee from private registry * Exporting Environment Variables to Containers * CSRF Cookie Secure Setting * Session Cookie Secure Setting * Extra Settings * Configure no_log * Auto Upgrade ** Upgrade of instances without auto upgrade * Service Account * Labeling operator managed objects * Pods termination grace period * Disable IPV6 * Add Execution Nodes ** Custom Receptor CA * Debugging * Migration
Upgrade	- Upgrading * Backup * v0.14.0 ** Cluster-scope to Namespace-scope considerations ** Project is now based on v1.x of the operator-sdk project ** Steps to upgrade
Uninstall	- Uninstall
Contributors Guide	- Contributing - Release Process - Author - Code of Conduct - 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.

[DesmondSanctity]

@samccann I have prepared the breakdown. Please do review and drop feedbacks. Thanks

[samccann]

Looks like a good breakdown @DesmondSanctity . I couple of comments:

• change Configurations to User Guide
• Change Contributions Guide to Contributors Guide

Also can you look at the existing /docs folder? I noticed it has two files that need to be added to the table/proposed structure. Thanks!

[DesmondSanctity]

Alright I'll check and effect possible changes

[DesmondSanctity]

Looks like a good breakdown @DesmondSanctity . I couple of comments:

• change Configurations to User Guide
• Change Contributions Guide to Contributors Guide

Also can you look at the existing /docs folder? I noticed it has two files that need to be added to the table/proposed structure. Thanks!

@samccann These suggestions are now updated in the table. Thanks

[rooftopcellist]

The migration guide might warrant another section. It might make sense to have backup and restore as separate guides/sections as well, then link to those from the upgrade guide.

I could be swayed either way on that, that is refactoring we could easily change after the first iteration.

[samccann]

@DesmondSanctity - looking good. I'd suggest creating that PR to match this outline. We can make adjustments when we see it all in action so to speak. Thanks!

[DesmondSanctity]

@DesmondSanctity - looking good. I'd suggest creating that PR to match this outline. We can make adjustments when we see it all in action so to speak. Thanks!

@samccann I have attached the PR as suggested.

[samccann]

Thanks @DesmondSanctity - I'll be off work for the next few weeks so there will be a delay on getting back to this. Sorry about that but thanks for the PR!

[DesmondSanctity]

Thanks @DesmondSanctity - I'll be off work for the next few weeks so there will be a delay on getting back to this. Sorry about that but thanks for the PR!

It's totally fine. Have a nice week ahead!

[rooftopcellist]

I'll merge the docs proposal PR so we have that as a guide as we break out each part of the README.md to different linked files. I assume that will be in a follow-up PR (s).

[rooftopcellist]

This got auto-closed when the linked PR merged. We still want this issue open to track the other items in the checklist afaik. So I re-opened the issue.

[samccann]

Hi folks - coming back to this. Now that we have a defined outline, the next steps are to create all those individual md files to match the proposed outline. @DesmondSanctity are you up for that next step?

My recommendation on how to proceed:
1 - use one PR per 'segment' in the table above.
2 - name the .md after the segment name (introduction.md for example)
3. In the PR, remove the topics from the README file to the new .md file in the /docs folder
4. Update the mkdocs details (coming soon) to add the new file and test the mkdocs locally.

I'm working on getting #1363 tested locally and then merged. That is required before step 4 above.

[DesmondSanctity]

Hi folks - coming back to this. Now that we have a defined outline, the next steps are to create all those individual md files to match the proposed outline. @DesmondSanctity are you up for that next step?

My recommendation on how to proceed:
1 - use one PR per 'segment' in the table above.
2 - name the .md after the segment name (introduction.md for example)
3. In the PR, remove the topics from the README file to the new .md file in the /docs folder
4. Update the mkdocs details (coming soon) to add the new file and test the mkdocs locally.

I'm working on getting #1363 tested locally and then merged. That is required before step 4 above.

Yes I'm ready. So we should wait till the MKDocs is ready or we can start 1-3?

[samccann]

go ahead and start 1-3 please and thanks!

[samccann]

@DesmondSanctity - the mkdocs scaffolding PR just got merged. How's it going with splitting up the readme into separate files? We can do this one section per PR if that helps so multiple people can help out here.

[DesmondSanctity]

@DesmondSanctity - the mkdocs scaffolding PR just got merged. How's it going with splitting up the readme into separate files? We can do this one section per PR if that helps so multiple people can help out here.

@samccann Hello! I will send this information to the discord and see if others will be available to work on it together. I am trying to get some work off my table and begin working on the docs by Friday. Tell me if that works. Thanks

[samccann]

Sounds good to me. We can get volunteers from there for sure but we want to coordinate the work in the open here in the issue so others outside of discord have a chance to help too.

[DesmondSanctity]

@samccann I have started working on moving the docs. I also sent a message to the discord community, hopefully others will join to make it faster.

[LuluNwenyi]

Hi @DesmondSanctity I would like to contribute to this.

[DesmondSanctity]

Hi @DesmondSanctity I would like to contribute to this.

Hello @LuluNwenyi , glad you want to contribute. Of you followed the conversation here, we've gone from breaking down the ReadMe files to sections and currently moving them to the docs folder.

My recommendation on how to proceed:
1 - use one PR per 'segment' in the table above.
2 - name the .md after the segment name (introduction.md for example). Also create a folder with the segment name and all the md files for that segment will be in that folder. (Check my PRs for guidance).
3. In the PR, remove the topics from the README file to the new .md file in the /docs folder.

I also see you're in the discord community. If you need clarification, message me and we can do a small meeting to put you through.

[LuluNwenyi]

HI @DesmondSanctity, I've gotten started on this, and I have a question. Would each subtopic under a topic have its own .md file? For instance, advanced configuration...

[DesmondSanctity]

Hello @LuluNwenyi

So firstly, you should follow the breakdown above and not the one on the Table of Content in the ReadMe file.

Secondly, Topics with other subtopics within them can stay in one .md files. For Advanced Configuration, we can create a folder named advanced-configuration and add the subtopics as different .md files since it has many subtopics and will be long for a one paged documentation.

Network and TLS Configuration & Database Configuration can stay in one file.

[DesmondSanctity]

Hi folks - coming back to this. Now that we have a defined outline, the next steps are to create all those individual md files to match the proposed outline. @DesmondSanctity are you up for that next step?

My recommendation on how to proceed: 1 - use one PR per 'segment' in the table above. 2 - name the .md after the segment name (introduction.md for example) 3. In the PR, remove the topics from the README file to the new .md file in the /docs folder 4. Update the mkdocs details (coming soon) to add the new file and test the mkdocs locally.

I'm working on getting #1363 tested locally and then merged. That is required before step 4 above.

@samccann I and @LuluNwenyi have moved the docs to their respective files in the docs folder. You can also view the PRs as referenced and tell us what you think.