Create AWX docsite with RST content #14328

oraNod · 2023-08-09T15:51:58Z

SUMMARY

This PR adds AWX documentation in RST source migrated from the private ansible/product-docs repository.

This is currently a work in progress. The following items must be completed before final review/merge:

Modify all images and screenshots to remove downstream references.
Update all variables to replace downstream product names with community equivalents.
Remove content related to downstream subscriptions (https://github.com/ansible/product-docs/issues/1862).

ISSUE TYPE

New or Enhanced Feature

COMPONENT NAME

Docs

AWX VERSION

N/A

ADDITIONAL INFORMATION

N/A

.gitignore

AlanCoding · 2023-08-24T15:24:22Z

looks like the api checks failed with this:

linters: commands[2]> yamllint -s .
./docs/docsite/rst/common/containergroup-sa.yml
  14:1      error    wrong indentation: expected 2 but found 0  (indentation)
  30:1      error    wrong indentation: expected 2 but found 0  (indentation)

Would it be too much to patch that indentation up in the file? If not, it can be added to the yamllint exclude list.

oraNod · 2023-08-24T16:02:40Z

looks like the api checks failed with this:
linters: commands[2]> yamllint -s .
./docs/docsite/rst/common/containergroup-sa.yml
  14:1      error    wrong indentation: expected 2 but found 0  (indentation)
  30:1      error    wrong indentation: expected 2 but found 0  (indentation)
Would it be too much to patch that indentation up in the file? If not, it can be added to the yamllint exclude list.

Thanks! Should be fixed now. It's great to have ci tests catching formatting issues with the content etc.

AlanCoding · 2023-08-24T19:46:18Z

Ready to take this out of draft status?

oraNod · 2023-08-28T16:24:11Z

Ready to take this out of draft status?

@AlanCoding Hello. Sorry for the slight delay here, I've been on PTO. @tvo318 has gone through all the content and added several commits and I think we're ready to go. We're looking at a few last relics in the images but should have that sorted out here shortly. Let the reviews commence! Thanks!

oraNod · 2023-08-29T09:20:53Z

@tvo318 Thanks for the awesome work to port the content over! I think we're pretty much ready to go. I added a couple of commits to remove a few relic images that were downstream specific. I also dropped some unused insights images. Please take a look. I guess we could prune more stale images but I'd rather do that in a follow up PR. As long as it's appropriate to hand over to the community it should be fine.

One other thing I think we might want to address are some of the lurking instances of "controller" and "tower".

For example, on these lines you can see controller is mentioned. Should these change to AWX?

administration/ent_auth.rst:6. Create an optional private key for the controller to use as a service provider (SP) and enter it in the **SAML Service Provider Private Key** field.  
administration/ent_auth.rst:7. Provide the IdP with some details about the controller cluster during the SSO process in the **SAML Service Provider Organization Info** field.
administration/ent_auth.rst:   These fields are required in order to properly configure SAML within the controller

Also for the REST API should we s/<controller-host>/<awx-host> in places like this?

rest_api/authentication.rst:	curl -k -c - https://<controller-host>/api/login/

oraNod · 2023-08-29T09:23:00Z

@tvo318 One other that I haven't checked yet. Does /etc/tower/conf.d/ change to settings/defaults.py?

tvo318 · 2023-08-29T16:25:14Z

I also have a few things I saw that maybe we need to still address:

docs/docsite/_themes/version_dropdown.html (should we remove this since we are just supporting 'latest")?
docs/docsite/_themes/srtd/layout.html (still has references to AUTOMATION and CONTROLLER)
docs/docsite/conf.py (pointers to translated versions still have controller in them)
I was told these are the supported AWX versions (but you probably already know that)

AlanCoding · 2023-08-30T18:30:13Z

I tried to build this with tox -e docs and I got this result:

docs: install_deps> python -I -m pip install -r /home/alancoding/repos/awx/docs/docsite/requirements.txt
.pkg: install_requires> python -I -m pip install 'setuptools>=45' 'setuptools_scm[toml]>=6.2'
.pkg: _optional_hooks> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: get_requires_for_build_sdist> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: get_requires_for_build_wheel> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: install_requires_for_build_wheel> python -I -m pip install wheel
.pkg: prepare_metadata_for_build_wheel> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: build_sdist> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
docs: install_package> python -I -m pip install --force-reinstall --no-deps /home/alancoding/repos/awx/.tox/.tmp/package/1/awx-22.7.1.dev69+g878ce41083.tar.gz
docs: commands[0]> sphinx-build -T -E -W -n --keep-going --color -j auto -c docs/docsite -d docs/docsite/build/doctrees -b html docs/docsite/rst docs/docsite/build/html
Running Sphinx v5.1.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 109 source files that are out of date
updating environment: [new config] 109 added, 0 changed, 0 removed
reading sources... [100%] userguide/project-sign .. userguide/workflows                                       
/home/alancoding/repos/awx/docs/docsite/rst/rest_api/authentication.rst:169: ERROR: Unknown target name: "api_start".
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] userguide/organizations .. userguide/workflows                                       
generating indices... genindex done
writing additional pages... search done
copying images... [100%] common/images/workflow-diagram.png                                                   
copying downloadable files... [100%] ../../common/containergroup-sa.yml                                       
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 1 warning.
docs: exit 1 (6.36 seconds) /home/alancoding/repos/awx> sphinx-build -T -E -W -n --keep-going --color -j auto -c docs/docsite -d docs/docsite/build/doctrees -b html docs/docsite/rst docs/docsite/build/html pid=475519
.pkg: _exit> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
  docs: FAIL code 1 (76.18=setup[69.82]+cmd[6.36] seconds)
  evaluation failed :( (76.32 seconds)

I wanted to ask if you could help me figure out that error. It looks like it's at the "api_start" point.

oraNod · 2023-08-31T08:08:49Z

I tried to build this with tox -e docs and I got this result:

docs: install_deps> python -I -m pip install -r /home/alancoding/repos/awx/docs/docsite/requirements.txt
.pkg: install_requires> python -I -m pip install 'setuptools>=45' 'setuptools_scm[toml]>=6.2'
.pkg: _optional_hooks> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: get_requires_for_build_sdist> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: get_requires_for_build_wheel> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: install_requires_for_build_wheel> python -I -m pip install wheel
.pkg: prepare_metadata_for_build_wheel> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: build_sdist> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
docs: install_package> python -I -m pip install --force-reinstall --no-deps /home/alancoding/repos/awx/.tox/.tmp/package/1/awx-22.7.1.dev69+g878ce41083.tar.gz
docs: commands[0]> sphinx-build -T -E -W -n --keep-going --color -j auto -c docs/docsite -d docs/docsite/build/doctrees -b html docs/docsite/rst docs/docsite/build/html
Running Sphinx v5.1.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 109 source files that are out of date
updating environment: [new config] 109 added, 0 changed, 0 removed
reading sources... [100%] userguide/project-sign .. userguide/workflows                                       
/home/alancoding/repos/awx/docs/docsite/rst/rest_api/authentication.rst:169: ERROR: Unknown target name: "api_start".
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] userguide/organizations .. userguide/workflows                                       
generating indices... genindex done
writing additional pages... search done
copying images... [100%] common/images/workflow-diagram.png                                                   
copying downloadable files... [100%] ../../common/containergroup-sa.yml                                       
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 1 warning.
docs: exit 1 (6.36 seconds) /home/alancoding/repos/awx> sphinx-build -T -E -W -n --keep-going --color -j auto -c docs/docsite -d docs/docsite/build/doctrees -b html docs/docsite/rst docs/docsite/build/html pid=475519
.pkg: _exit> python /home/alancoding/repos/awx/env/lib64/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
  docs: FAIL code 1 (76.18=setup[69.82]+cmd[6.36] seconds)
  evaluation failed :( (76.32 seconds)

I wanted to ask if you could help me figure out that error. It looks like it's at the "api_start" point.

hey @AlanCoding yes it looks like there's a problem with a Sphinx ref from this commit: ea46505#diff-2a3bdf96e33ef2c6f65306a401b9874e7b7a1acdd7af9ea124deee3b040a26afR170

The fix is to modify that to use the ref: role. I'll push a commit.

Thanks for catching this. After we get this merged I'd like to add a step to CI to verify the docs build so we can get PR checks for this stuff too.

oraNod · 2023-08-31T08:48:15Z

I also have a few things I saw that maybe we need to still address:

* docs/docsite/_themes/version_dropdown.html (should we remove this since we are just supporting 'latest")?

* docs/docsite/_themes/srtd/layout.html (still has references to AUTOMATION and CONTROLLER)

* docs/docsite/conf.py (pointers to translated versions still have controller in them)
  I was told these are the supported AWX versions (but you probably already know that)
  ![image](https://user-images.githubusercontent.com/7514801/264088293-5217b1f5-8fcf-4da0-b0d0-77de9cf6ef15.png)

Nice one @tvo318 I've removed the old theme and static content. They're no longer needed with the Ansible community theme! I guess we still need to figure out translations but we can do that when we set things up on Read The Docs. We don't need those translation strings in the conf.py anyway as they were pulled in by the old layout.

AlanCoding

We understand that there's still some things to iterate on, but everyone is excited about getting this content and the build system in.

tvo318 · 2023-08-31T19:18:08Z

Remaining tower references to keep or revisit later (unsure of AWX equivalent):

rst/userguide/projects.rst: (points to example `helloworld.yml`` file available at: https://github.com/ansible/tower-example.git)
rst/userguide/inventory_plugins_templates.rst: (refers to plugin: awx.awx.tower for RHAAP inventory source)
rst/userguide/overview.rst: (refers to plugin: awx.awx.tower inventory plugin)
rst/userguide/ee_reference.rst: (refers to plugin: awx.awx.tower inventory plugin)
rst/userguide/instance_groups.rst: (xrefs a public blog)
rst/administration/ent_auth.rst: (refers to variable name)
rst/administration/logging.rst: (refers to variable name)
rst/administration/troubleshooting.rst: (references a file directory)
rst/rest_api/api_ref.rst: (in the stylesheet line 51)

oraNod · 2023-08-31T19:28:09Z

Thanks @tvo318 I forgot that the api reference (api_ref.rst) was pulling in some assets from the static folder but we can restore them - and make sure they're all good for the community docs - when we add in the swagger generation step.

Removed all of introductory text and graphic from User Interface section except for the include from the configure_awx.rst file.

Replaced text with new text from operator-docs.

tvo318 · 2023-08-31T21:19:56Z

Remaining controller references to keep or revisit later (unsure of AWX equivalent):

rst/userguide/best_practices.rst: (references controllercli guide since not sure what new CLI guide link is)
rst/userguide/inventories.rst: (contained in a URL and a reference to the )
rst/userguide/job_templates.rst: (contained in a URL)
rst/administration/ent_auth.rst: (contained in abbreviation for TACACS+)
rst/administration/tipsandtricks.rst: (references the CLI guide)

Co-authored-by: Thanhnguyet Vo <tvo@ansible.com> Co-authored-by: TVo <thavo@redhat.com>

oraNod marked this pull request as draft August 9, 2023 15:52

github-actions bot added community component:docs labels Aug 9, 2023

oraNod force-pushed the awx-docsite branch from c4b4a4a to ff3518a Compare August 11, 2023 16:21

oraNod commented Aug 11, 2023

View reviewed changes

.gitignore Outdated Show resolved Hide resolved

oraNod force-pushed the awx-docsite branch from ff3518a to 7ea343e Compare August 14, 2023 17:19

oraNod mentioned this pull request Aug 15, 2023

DaWGs (Documentation Working Group) Meeting Agenda 2023 ansible/community#678

Closed

oraNod force-pushed the awx-docsite branch from 6b954e5 to f342084 Compare August 24, 2023 15:57

oraNod force-pushed the awx-docsite branch from f342084 to e93c820 Compare August 28, 2023 15:10

oraNod marked this pull request as ready for review August 28, 2023 16:19

oraNod changed the title ~~[WIP] Create AWX docsite with RST content~~ Create AWX docsite with RST content Aug 28, 2023

oraNod force-pushed the awx-docsite branch from 83cecc4 to 07aa1ea Compare August 29, 2023 08:49

oraNod requested a review from thedoubl3j August 29, 2023 09:23

oraNod force-pushed the awx-docsite branch from 878ce41 to ec23c68 Compare August 31, 2023 08:10

AlanCoding approved these changes Aug 31, 2023

View reviewed changes

oraNod added 3 commits August 31, 2023 20:29

Create AWX docsite with RST content

2f3497b

drop import license

0ae0e23

rm docs.ansible sitemap

045a148

tvo318 and others added 21 commits August 31, 2023 20:29

Deleted delete button and warning

24a2d41

cleaning up some warnings

fa36e12

rm generated schema

f83d9f0

disable swagger in api ref

9b0f047

rm ignore exception for docsite swagger.json

85b1c35

fix weird rendering

ca6c4ef

Remaining cleanup - tower refs and images, etc

b93ba8b

Replaced and renamed hierarchy graphic

78b4d86

Removed hierarchy graphic with tower name.

022fed9

fix img ref

48a994a

drop some red hat images

fb8ede9

drop unused insights images

8f163ea

Replaced controller with AWX ent_auth.rst

863a77e

Added ref anchor to api_ref.rst

8015604

replaced controller with awx in rest_api/authentication.rst

0ce434f

Removed excess text from configure_awx.rst

df7b571

Removed all of introductory text and graphic from User Interface section except for the include from the configure_awx.rst file.

Replaced error log section in troubleshooting.rst

6b74f27

Replaced text with new text from operator-docs.

fix sphinx ref

180395f

drop the old theme

4e87a20

drop old static content

1805d78

minor tower removals and replacements.

5874eaf

tvo318 self-requested a review August 31, 2023 19:29

oraNod force-pushed the awx-docsite branch from 345e09a to 5874eaf Compare August 31, 2023 19:29

tvo318 approved these changes Aug 31, 2023

View reviewed changes

Replaced controller terminology and removed excess text.

730a493

tvo318 merged commit dc81aa4 into ansible:devel Sep 1, 2023

tvo318 mentioned this pull request Sep 1, 2023

Doc cleanup work for migration to AWX docs oraNod/awx#2

Closed

djyasin pushed a commit to djyasin/awx that referenced this pull request Sep 16, 2024

Create AWX docsite with RST content (ansible#14328)

a4facd5

Co-authored-by: Thanhnguyet Vo <tvo@ansible.com> Co-authored-by: TVo <thavo@redhat.com>

djyasin pushed a commit to djyasin/awx that referenced this pull request Nov 11, 2024

Create AWX docsite with RST content (ansible#14328)

fc0b048

Co-authored-by: Thanhnguyet Vo <tvo@ansible.com> Co-authored-by: TVo <thavo@redhat.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create AWX docsite with RST content #14328

Create AWX docsite with RST content #14328

oraNod commented Aug 9, 2023 •

edited

Loading

AlanCoding commented Aug 24, 2023

oraNod commented Aug 24, 2023

AlanCoding commented Aug 24, 2023

oraNod commented Aug 28, 2023

oraNod commented Aug 29, 2023

oraNod commented Aug 29, 2023

tvo318 commented Aug 29, 2023 •

edited

Loading

AlanCoding commented Aug 30, 2023

oraNod commented Aug 31, 2023

oraNod commented Aug 31, 2023

AlanCoding left a comment

tvo318 commented Aug 31, 2023 •

edited

Loading

oraNod commented Aug 31, 2023

tvo318 commented Aug 31, 2023

Create AWX docsite with RST content #14328

Create AWX docsite with RST content #14328

Conversation

oraNod commented Aug 9, 2023 • edited Loading

SUMMARY

ISSUE TYPE

COMPONENT NAME

AWX VERSION

ADDITIONAL INFORMATION

AlanCoding commented Aug 24, 2023

oraNod commented Aug 24, 2023

AlanCoding commented Aug 24, 2023

oraNod commented Aug 28, 2023

oraNod commented Aug 29, 2023

oraNod commented Aug 29, 2023

tvo318 commented Aug 29, 2023 • edited Loading

AlanCoding commented Aug 30, 2023

oraNod commented Aug 31, 2023

oraNod commented Aug 31, 2023

AlanCoding left a comment

Choose a reason for hiding this comment

tvo318 commented Aug 31, 2023 • edited Loading

oraNod commented Aug 31, 2023

tvo318 commented Aug 31, 2023

oraNod commented Aug 9, 2023 •

edited

Loading

tvo318 commented Aug 29, 2023 •

edited

Loading

tvo318 commented Aug 31, 2023 •

edited

Loading