Cannot build documentation

[Andrew C]

I am have cloned the latest version of the GIT repo.

TOWER_HOST=http://awx-demo.test.com TOWER_USERNAME=admin TOWER_PASSWORD=REznGWmHfcDFlm5awGtYf52OEVO1sYsw  make clean html

When I try to run make html to create the documentation I get the following error:

Running Sphinx v4.1.1

Exception occurred:

  File "/usr/local/lib/python3.6/site-packages/awxkit/cli/sphinx.py", line 4, in <module>

    from sphinxcontrib.autoprogram import AutoprogramDirective

  File "/usr/local/lib/python3.6/site-packages/sphinxcontrib/autoprogram.py", line 11

    from __future__ import annotations

                                     ^

SyntaxError: future feature annotations is not defined

The full traceback has been saved in /tmp/sphinx-err-s32qna1i.log, if you want to report the issue to the developers.

Please also report this if it was a user error, so that a better error message can be provided next time.

A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

make: *** [html] Error 2

Alternatively if there a publicly available AWX documentation site or somewhere that I can download it from?

[Vincent Rubiolo]

Hi Andrew,

I am interesting in the answer on the documentation local build from the git repo too.

In the meantime, since AWX forms the base of the Redhat Automation Controller Platform, these are the docs that I am using: https://docs.ansible.com/automation.html (User's Guide, Admin Guide and API Guide)

HTH,

Vincent

[Vincent Rubiolo]

Hi Andrew,

Did you manage to build the documentation eventually?

Thanks for the feedback,

Vincent

[Andrew C]

Hi Vincent,

I gave up and used the link in this thread. The documentation is about 90% correct, however it does not cover the differences in the open-source version so you have to work out a couple of things for yourself.

Regards,

Andrew

[Vincent Rubiolo]

Hi Andrew,

Thanks for the feedback, glad to see the link was useful!

For what I gathered browsing the AWX source code, the internal doc from the repo at https://github.com/ansible/awx/tree/devel/docs describes the design internals in pretty good details but is different from the customer facing user manual I referenced above. 

Both complement one another, I don't know though if there is a way to generate a documentation site from the abovementioned Markdown files ...

Vincent

[Vincent Rubiolo]

Hi again Andrew,

I proceeded to install the AWX CLI today and it reminded me of this thread. I thus went ahead and tried to generate the documentation from my source tree.

I reach my AWX instance via SSL but the certificate is self-signed and it does not seem there is a way to pass down the '--conf.insecure' flag when sphinx is calling the awx commandline (it directly drives it via the Python entry point) so I had to modify my install  $HOME/.local/lib/python3.9/site-packages/awxkit/cli/client.py at l102 to set it to insecure by default:

101         # vrubiolo: default is untrusted for docs generation

102         config.assume_untrusted = True

After that, generation via the normal instructions worked fine:

$ cd awxkit/awxkit/cli/docs/build/html

$ TOWER_HOST=https://awx.mine.onprem TOWER_USERNAME=admin TOWER_PASSWORD=XXX make clean html

$ cd build/html

$ python -m http.server

I could then browse the generated doc on my machine.

Given the look of your error within the future Python statement, I would tend to think this is a Python environment-related error. In my case, I am using Fedora 34 and Python 3.9.7. The HEAD of my awx repo is at ba324c73ceefa22d516d872527649d090d3bc0cc and I am using awx CLI 19.4.0 from pip.

HTH,

Vincent

[Andrew C]

Hi Vincent,

I updated my AWX to 19.5.0 using  ansible/awx-operator: An Ansible AWX operator for Kubernetes built with Operator SDK and Ansible. and the Help link takes you to the Ansible Controller version 4.0 so I don't think I need to serve my own doc server anymore.

Automation Controller User Guide v4.0.0 — Automation Controller User Guide v4.0.0 (ansible.com)

Regards,

Andrew

[Vincent Rubiolo]

Hi Andrew,

Great to hear you can reach the Automation Controller doc from your instance now!

Did the update to 19.5.0 go smoothly and you were able to keep your existing data?

Vincent

[Andrew C]

Hi Vincent,

This is a crash and burn environment so I didn't really have anything to migrate.

[Vincent Rubiolo]

On Tuesday, November 30, 2021 at 6:34:24 PM UTC+1 Andrew C wrote:

Hi Vincent,

This is a crash and burn environment so I didn't really have anything to migrate.

Understood. This indeed makes migrations easier :)

Vincent