# Creating AWX CLI Guide

(note: Some links go to internal Red Had Jenkins jobs and are not accessable to the general community at this point).

## Problem

We want to be able to generate and publish the CLI guide to AWX documentation instead of [controller docsite](https://docs.ansible.com/automation-controller/latest/html/controllercli/index.html).

The current Jenkins job and supporting playbooks are controller-branded.

Also, the tool (awxcli) generates a complete html docsite (stand alone).

## Options

The AWX/Controller CLI guide depends on having an active AWX/Controller instance running to pull the details from.

The current code that generates the CLI guide creates HTML for a standalone docsite. We have the following options to create the guide for AWX:

Option 1. Integrate awxkit files and conf.py into AWX docsite generation.
Option 2 Generate RST and integrate into AWX docsite
Option 3 - Create Standalone docsite using existing resources with branding modifications.

**NOTE** would be beneficial to downstream docs if we can produce some interim output they can bring into their downstream toolchain. Today, downstream publishing supports asciidoc, but .md is coming soon. Sphinx can generate .xml files in the docutils format so that might be an option to consider (``sphinx-build -b xml source build``).

### 1. Integrate awxkit cli files into AWX docsite

There are two steps here:

1. static doc files are in another directory - we can use a symlink to get them where they need to be. (Tested and this works).
2. Integrate the actual cli generation (requires a running AWX instance to communicate with).

Can test this locally but how would the RTD docs generation instantiate a running AWX instance?? Possibly with GitHub actions?

----------------------------------------
Ideas below here have been rejected...

### 2. Generate RST and integrate into AWX docsite

Since the existing code is branded and generates html for a standalone site, we cannot use it directly. Instead we could:
1. Modify the code generation to pull out an intermediate step of creating rst files.
2. Modify the AWX docs creation to pull in this additional RST.
3. Publish to the AWX docsite.

**NOTE: We need to keep the existing generation working for the Controller CLI Guide so cannot break that rendering option.**

#### Cannot get RST out of existing extension

The existing code creates a foo.doctree file, but docutils tools like [xml2rst](https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/xml2rst/) can't seem to convert this back to an .rst file (not to mention the tool is python2 based and requires some changes to run).

I've been experimenting with the sphinx extension, [sphinx-contrib.autoprogram](https://github.com/sphinx-contrib/autoprogram/blob/master/sphinxcontrib/autoprogram.py) and the [awxcli custom extenstion](https://github.com/ansible/awx/blob/devel/awxkit/awxkit/cli/sphinx.py) based on this. I can see they build up a docutils document structure within the code, but similarly cannot see how to get this to an RST file.

Seems sphinx directives produce .doctree files that also include the TOC for the whole site so can't use this directly, but perhaps the next step is to try and move some of the awxkit/cli stuff into the /docs/docsite folder and see how far I get.

### 3. Create Standalone docsite

The following are basic steps to create a standalone AWX CLI guide (not part of the AWX docsite). It uses existing resources and rebrands for AWX:

The [static CLI rst files](https://github.com/ansible/awx/tree/devel/awxkit/awxkit/cli/docs/source) already exist in the AWX repo, so we could
1. Copy the playbooks to GitHub actions to generate the HTML with AWX branding.
2. Publish to RTD as awx-cli-guide (standalone site).

#### GitHub Workflow

Drafting out how a new **awx_cli_docs workflow** would go.
1. Run the awx image (with [run_awx_devel](https://github.com/ansible/awx/tree/devel/.github/actions/run_awx_devel) action), which will call [awx_devel_image](https://github.com/ansible/awx/tree/devel/.github/actions/awx_devel_image) action) to generate the awx devel images.
2. Run a new action - ``awx_cli_docs_generate`` action with the following:
`CONTROLLER_HOST=https://awx.example.org CONTROLLER_USERNAME=example CONTROLLER_PASSWORD=secret make clean html`
`CONTROLLER_HOST=https://awx.localhost:8043 CONTROLLER_USERNAME=admin CONTROLLER_PASSWORD=password make clean html`

Where the details come from step 1 on where the awx instance is, password, etc. (seems from the .yaml that username is admin and password is password).

3. Append the [tox.ini](https://github.com/ansible/awx/blob/devel/tox.ini#L33) for docs to combine this HTML with the `spinx-build` HTML.

## Current CLI guide generation

You can [build the CLI locally](https://github.com/samccann/awx/tree/devel/awxkit/awxkit/cli) if you have an AWX instance running with:

`CONTROLLER_HOST=https://awx.example.org CONTROLLER_USERNAME=example CONTROLLER_PASSWORD=secret make clean html`

The following steps show how the published guide is created:

1. Trigger the [Build_AWX_CLI_Docs jenkins job](https://main-jenkins-csb-aap.apps.ocp-c1.prod.psi.redhat.com/view/all/job/Docs/job/Build_AWX_Cli_Docs/) (which comes from [this PR](https://github.com/ansible/aap-jenkins-shared-library/pull/515)).
2. Job generates the CLI docs with [build-awx-cli-docs.yml](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/build-awx-cli-docs.yml) playbook.
3. Job publishes the CLI docs with [publish-awx-cli-docs.yml](
https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/publish-awx-cli-docs.yml), which publishes as controller docs.

With the current job, the CLI guide is built from tasks and resources in ansible/tower-packaging, ansible/product-docs, and ansible/tower repositories. The latter seems to be a downstream sync of ansible/awx.

## Issues with current jenkins job that we'd have to address to reuse it for both AWX and controller CLI guides

- Since the jenkins job and playbook all pull from AAP/controller versions, do we need to have a separate job/playbook for AWX? (Aka does AWX release more often than controller)?
- [This line](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/roles/build-awx-cli-docs/tasks/main.yml#L19) clones the product-docs repo, based on [this variable](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/roles/clone-repo/vars/main.yml#L15). Should this now point to the awx docs repo (awx/awx)?
- [This task](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/roles/build-awx-cli-docs/tasks/main.yml#L21) pulls in resources from product-docs repo. These create a 'theme' that matches controller docs, not AWX. We likely need to copy these over to awx/awx and update the jenkins job to choose between awx or controller (so it picks the correct theme). Note this is not just color, it brings in the footer that talks about AAP etc. 
- [This and following tasks](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/roles/build-awx-cli-docs/tasks/main.yml#L28) use awxkit resources from ansible/tower instead of ansible/awx repo. Should it clone from awx now instead of tower?
- [This task](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/roles/build-awx-cli-docs/tasks/main.yml#L40) pulls an [install.rst.j2](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/roles/build-awx-cli-docs/templates/install.rst.j2) template from the tower-packaging repo, but it uses controller in the template text. If we remove that patch task, it looks like the playbook will use the [install.rst](https://github.com/ansible/tower/blob/devel/awxkit/awxkit/cli/docs/source/install.rst) that is in the tower repo instead. Ideally, we'd want it coming from ansible/awx not ansible/tower.
- [Multiple tasks](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/roles/build-awx-cli-docs/tasks/main.yml#L46) after this involve version and version dropdown which are not applicable for AWX.
- The [final task](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/roles/build-awx-cli-docs/tasks/main.yml#L69) generates the CLI html, based on the ansible/tower repo.
- The [publish-awx-cli-docs.yml playbook](https://github.com/ansible/tower-packaging/blob/devel/tools/ansible/publish-awx-cli-docs.yml) publishes controller docs.