Replaced all references of downstream docs to upstream docs #15388

tvo318 · 2024-07-19T01:25:28Z

SUMMARY

Replaced all links to 'tower' and 'automation-controller' documentation with links to https://ansible.readthedocs.io/projects/awx/en/latest/ or to to developers.redhat.com for the API reference guide. The purpose of this PR is to correct links that are still pointing to old product docs.

ISSUE TYPE

Bug, Docs Fix or other nominal change

COMPONENT NAME

Docs
API

AWX VERSION

devel and latest

…erefs

oraNod · 2024-07-19T10:32:30Z

awx_collection/README.md

@@ -32,7 +32,7 @@ Installing the `tar.gz` involves no special instructions.
 ## Running

 Non-deprecated modules in this collection have no Python requirements, but
-may require the official [AWX CLI](https://docs.ansible.com/ansible-tower/latest/html/towercli/index.html)
+may require the official [AWX CLI](https://docs.ansible.com/automation-controller/latest/html/controllercli/index.html)


@tvo318 Hey, about the AWX CLI docs. I know there's currently no equivalent of the guide in the AWX docsite yet and we still need to migrate the content to docs.redhat. @samccann renewed this topic and the community team are going to keep working on it.

For AWX I've been thinking that maybe we should just rely on manpages rather than a published guide. I know that's not quite as ideal but I think it's a good approach.

The main reason here is that it's going to take some engineering effort to create an AWX CLI guide that is separate to the Controller CLI guide. I obvs don't own the decision but I'd question if it's worth going there. IMO it's worth investing more in developing higher quality manpages than it is generating a separate AWX CLI guide. Docs should always be available from where the user is working.

Anyway, in this particular case, I suggest we just remove the link to docs.ansible.com because that has always been intended for downstream users and this reinforces the ambiguity between AWX and Controller imo.

This is a tricky one. Since it's the readme for the collection, the identical content shows up in Galaxy (related to AWX) and in Automation Hub (related to the controller collection). Since the link is talking about the CLI, it is today still the awx cli (all commands are awx-foo). That said, I think what this section really means is the user has to have awxkit installed to get that awx CLI, so maybe we can avoid it all by changing the link to https://pypi.org/project/awxkit/ ?

@samccann - That is fine in this context. Thanks for reminding me where the AWX kit lives!

awx_collection/README.md

oraNod · 2024-07-19T10:37:41Z

awx_collection/plugins/modules/job_template.py

-    U(https://docs.ansible.com/ansible-tower/latest/html/towerapi/api_ref.html#/Job_Templates/Job_Templates_job_templates_survey_spec_create)
-    for POST operation payload example.
+    U(https://developers.redhat.com/api-catalog/api/ansible-automation-controller) and search for 'survey' for information on job template survey creation
+    and POST operation payload example.


I'd probably point to https://ansible.readthedocs.io/projects/awx/en/latest/rest_api/api_ref.html#/Job_Templates/Job_Templates_job_templates_survey_spec_list

same problem - do the docs for this collection reflect awx or controller as the priority?

It's hard to tell, @samccann. I'll need to discuss further with @gundalow about this one.

After some discussion with @gundalow, I'll point readers to a landing page that has links for them to go to, depending on their situation. Since this page will ultimately go away, we will keep this an open issue (tracked elsewhere) until we are directed to do something different.

awx_collection/tools/roles/template_galaxy/templates/README.md.j2

Co-authored-by: Don Naro <dnaro@redhat.com>

samccann · 2024-07-22T20:51:07Z

awx_collection/README.md

@@ -32,7 +32,7 @@ Installing the `tar.gz` involves no special instructions.
 ## Running

 Non-deprecated modules in this collection have no Python requirements, but
-may require the official [AWX CLI](https://docs.ansible.com/ansible-tower/latest/html/towercli/index.html)
+may require the official [AWX CLI](https://docs.ansible.com/automation-controller/latest/html/controllercli/index.html)


This is a tricky one. Since it's the readme for the collection, the identical content shows up in Galaxy (related to AWX) and in Automation Hub (related to the controller collection). Since the link is talking about the CLI, it is today still the awx cli (all commands are awx-foo). That said, I think what this section really means is the user has to have awxkit installed to get that awx CLI, so maybe we can avoid it all by changing the link to https://pypi.org/project/awxkit/ ?

awx_collection/plugins/lookup/controller_api.py

samccann · 2024-07-22T20:56:46Z

awx_collection/plugins/modules/job_template.py

-    U(https://docs.ansible.com/ansible-tower/latest/html/towerapi/api_ref.html#/Job_Templates/Job_Templates_job_templates_survey_spec_create)
-    for POST operation payload example.
+    U(https://developers.redhat.com/api-catalog/api/ansible-automation-controller) and search for 'survey' for information on job template survey creation
+    and POST operation payload example.


same problem - do the docs for this collection reflect awx or controller as the priority?

…emovetowerefs

oraNod · 2024-07-24T10:18:03Z

awx_collection/plugins/lookup/controller_api.py

@@ -12,7 +12,7 @@
  - None
 description:
  - Returns GET requests from the Automation Platform Controller API. See
-    U(https://docs.ansible.com/ansible-tower/latest/html/towerapi/index.html) for API usage.
+    U(https://docs.ansible.com/automation-controller/latest/html/towerapi/) for API usage.


@tvo318 and @gundalow Maybe I missed some of the convo here about the awx_collection but I feel like it would be much better to avoid sending folks to docs.ansible.com for any platform / controller content. In fact the linked docs.ansible.com url here basically tells you to go to redhat.com so we might as well give them a more direct url. Or am I missing something?

https://developers.redhat.com/api-catalog/api/ansible-automation-controller

https://docs.ansible.com/automation-controller/latest/html/towerapi/ has two links:

The Automation Controller API Guide for Red Hat Ansible Automation Platform has been moved to the Red Hat Developer page.
For the latest community documentation on Read The Docs, refer to AWX API Reference.

@oraNod - I discussed this with @gundalow on our 1:1 and we agree just to merge what we have. The decision to use this link is just a temporary fix. I chose the link on docs.ansible because it gives readers a choice on where to go. We can fix this later with another PR when we have a better solution.

@oraNod

…15388) * Replaced all references of downstream docs to upstream docs. * Update README.md Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Incorpor'd review feedback from @oraNod and @samccann * Updated with agreed link (for now) until further change is needed. --------- Co-authored-by: Don Naro <dnaro@redhat.com>

@oraNod

…15388) * Replaced all references of downstream docs to upstream docs. * Update README.md Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Incorpor'd review feedback from @oraNod and @samccann * Updated with agreed link (for now) until further change is needed. --------- Co-authored-by: Don Naro <dnaro@redhat.com>

@oraNod

…15388) * Replaced all references of downstream docs to upstream docs. * Update README.md Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Incorpor'd review feedback from @oraNod and @samccann * Updated with agreed link (for now) until further change is needed. --------- Co-authored-by: Don Naro <dnaro@redhat.com> (cherry picked from commit 018f235)

@oraNod

* Update docs replacements to AWX (#15349) Update replacements to AWX Signed-off-by: Sandra McCann <samccann@redhat.com> (cherry picked from commit 9979fc6) * Remove remnants of controller terms from quickstart docs (#15350) Remove remnants of controller terms from quickstart Signed-off-by: Sandra McCann <samccann@redhat.com> (cherry picked from commit 864a30e) * Remove references to translated versions of the docs (#15354) remove references to translated versions of the docs Signed-off-by: Sandra McCann <samccann@redhat.com> Co-authored-by: TVo <thavo@redhat.com> (cherry picked from commit 5f42db6) * update terminology (#15357) * update terminology Replace some instances of Tower with AWX and remove some references to enterprise left over from the migration of RST content from the Automation Controller docs. * Update docs/docsite/rst/userguide/overview.rst Co-authored-by: TVo <thavo@redhat.com> --------- Co-authored-by: TVo <thavo@redhat.com> (cherry picked from commit f1448fc) * Replaced all references of downstream docs to upstream docs (#15388) * Replaced all references of downstream docs to upstream docs. * Update README.md Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Incorpor'd review feedback from @oraNod and @samccann * Updated with agreed link (for now) until further change is needed. --------- Co-authored-by: Don Naro <dnaro@redhat.com> (cherry picked from commit 018f235) * Re-do PR #14685 for alt-text inventories. (#15394) (cherry picked from commit 6d0c47f) * Docs: add Communication guide (#15469) * Docs: add Communication guide * Update docs/docsite/rst/contributor/communication.rst Co-authored-by: Don Naro <dnaro@redhat.com> * Update docs/docsite/rst/contributor/communication.rst --------- Co-authored-by: Don Naro <dnaro@redhat.com> (cherry picked from commit 79c1921) --------- Co-authored-by: Don Naro <dnaro@redhat.com> Co-authored-by: TVo <thavo@redhat.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

@oraNod

…15388) * Replaced all references of downstream docs to upstream docs. * Update README.md Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Update README.md.j2 Co-authored-by: Don Naro <dnaro@redhat.com> * Incorpor'd review feedback from @oraNod and @samccann * Updated with agreed link (for now) until further change is needed. --------- Co-authored-by: Don Naro <dnaro@redhat.com>

tvo318 added 2 commits July 18, 2024 16:36

Replaced all references of downstream docs to upstream docs.

878edec

Merge branch 'devel' of https://github.com/ansible/awx into removetow…

1f3afe8

…erefs

github-actions bot added component:awx_collection issues related to the collection for controlling AWX component:docs labels Jul 19, 2024

tvo318 requested review from oraNod and TheRealHaoLiu July 19, 2024 01:28

Merge branch 'devel' into removetowerefs

cb4857c

oraNod reviewed Jul 19, 2024

View reviewed changes

tvo318 and others added 3 commits July 19, 2024 13:59

Update README.md

c2b973a

Co-authored-by: Don Naro <dnaro@redhat.com>

Update README.md.j2

bf045c2

Co-authored-by: Don Naro <dnaro@redhat.com>

Update README.md.j2

b36a04d

Co-authored-by: Don Naro <dnaro@redhat.com>

samccann reviewed Jul 22, 2024

View reviewed changes

tvo318 added 4 commits July 22, 2024 22:28

Incorpor'd review feedback from @oraNod and @samccann

ce555f6

Merge branch 'devel' into removetowerefs

c1dc712

Merge branch 'removetowerefs' of https://github.com/tvo318/awx into r…

bea0bc8

…emovetowerefs

Updated with agreed link (for now) until further change is needed.

a279191

tvo318 requested review from gundalow, oraNod and samccann July 23, 2024 19:21

gundalow approved these changes Jul 23, 2024

View reviewed changes

samccann approved these changes Jul 23, 2024

View reviewed changes

oraNod reviewed Jul 24, 2024

View reviewed changes

tvo318 merged commit 018f235 into ansible:devel Jul 24, 2024
21 checks passed

tvo318 deleted the removetowerefs branch July 26, 2024 17:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replaced all references of downstream docs to upstream docs #15388

Replaced all references of downstream docs to upstream docs #15388

tvo318 commented Jul 19, 2024

oraNod Jul 19, 2024

samccann Jul 22, 2024

tvo318 Jul 23, 2024

oraNod Jul 19, 2024

samccann Jul 22, 2024

tvo318 Jul 23, 2024

tvo318 Jul 23, 2024

samccann Jul 22, 2024

samccann Jul 22, 2024

oraNod Jul 24, 2024

gundalow Jul 24, 2024

tvo318 Jul 24, 2024

Replaced all references of downstream docs to upstream docs #15388

Replaced all references of downstream docs to upstream docs #15388

Conversation

tvo318 commented Jul 19, 2024

SUMMARY

ISSUE TYPE

COMPONENT NAME

AWX VERSION

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment