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
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?
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)
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.
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 …
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.
