diff --git a/docs/docsite/conf.py b/docs/docsite/conf.py index dacf2389eb..8761c649a1 100644 --- a/docs/docsite/conf.py +++ b/docs/docsite/conf.py @@ -1,6 +1,7 @@ import sys import os import shlex +import warnings from datetime import datetime from importlib import import_module @@ -8,10 +9,10 @@ from importlib import import_module sys.path.insert(0, os.path.abspath('./rst/rest_api/_swagger')) project = u'Ansible AWX' -copyright = u'2024, Red Hat' +copyright = u'2026, Red Hat' author = u'Red Hat' -pubdateshort = '2024-11-22' +pubdateshort = '2026-01-07' pubdate = datetime.strptime(pubdateshort, '%Y-%m-%d').strftime('%B %d, %Y') # The name for this set of Sphinx documents. If None, it defaults to @@ -35,6 +36,7 @@ extensions = [ 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'sphinx_ansible_theme', + 'sphinxcontrib.redoc', 'notfound.extension', 'swagger', ] @@ -61,6 +63,27 @@ language = 'en' locale_dirs = ['locale/'] # path is example but recommended. gettext_compact = False # optional. +redoc = [ + { + 'name': 'AWX OpenAPI Reference', + 'page': 'open_api/explorer', + 'spec': 'rst/open_api/schema.json', + 'embed': True, + 'opts': { + 'suppress-warnings': True, + 'hide-hostname': True, + } + } +] + +# Suppress pkg_resources deprecation from sphinxcontrib-redoc +warnings.filterwarnings( + 'ignore', + message='pkg_resources is deprecated', + category=UserWarning, + module='sphinxcontrib.redoc', +) + rst_epilog = """ .. |atapi| replace:: *AWX API Guide* .. |atrn| replace:: *AWX Release Notes* @@ -89,3 +112,4 @@ rst_epilog = """ pubdateshort, pubdate, ) + diff --git a/docs/docsite/download-json.py b/docs/docsite/download-json.py new file mode 100644 index 0000000000..1105004976 --- /dev/null +++ b/docs/docsite/download-json.py @@ -0,0 +1,19 @@ +import requests + +downloads = [ + {"url": "https://awx-public-ci-files.s3.amazonaws.com/community-docs/swagger.json", "path": "./docs/docsite/rst/rest_api/_swagger/swagger.json"}, + {"url": "https://s3.amazonaws.com/awx-public-ci-files/awx/devel/schema.json", "path": "./docs/docsite/rst/open_api/schema.json"}, +] + +for item in downloads: + url = item["url"] + filepath = item["path"] + + response = requests.get(url) + + if response.status_code == 200: + with open(filepath, 'wb') as file: + file.write(response.content) + print(f"JSON file downloaded to {filepath}") + else: + print(f"Request failed with status code: {response.status_code}") diff --git a/docs/docsite/requirements.in b/docs/docsite/requirements.in index 86997b5da2..8dc58e4512 100644 --- a/docs/docsite/requirements.in +++ b/docs/docsite/requirements.in @@ -3,6 +3,8 @@ sphinx # Tooling to build HTML from RST source. sphinx-ansible-theme # Ansible community theme for Sphinx doc builds. sphinx-notfound-page # Sphinx extension for custom 404 page. +sphinxcontrib-redoc # Renders OpenAPI spec in human readable format. +setuptools >= 65.0 # Provides pkg_resources module for compatibility. Needed by sphinxcontrib-redoc. docutils # Tooling for RST processing and the swagger extension. Jinja2 # Requires investigation. Possibly inherited from previous repo with a custom theme. PyYaml # Requires investigation. Possibly used as tooling for swagger API reference content. diff --git a/docs/docsite/requirements.txt b/docs/docsite/requirements.txt index 03131a075b..a99a24051a 100644 --- a/docs/docsite/requirements.txt +++ b/docs/docsite/requirements.txt @@ -8,6 +8,10 @@ alabaster==1.0.0 # via sphinx ansible-pygments==0.1.1 # via sphinx-ansible-theme +attrs==25.4.0 + # via + # jsonschema + # referencing babel==2.16.0 # via sphinx certifi==2024.8.30 @@ -27,6 +31,11 @@ jinja2==3.1.4 # via # -r docs/docsite/requirements.in # sphinx + # sphinxcontrib-redoc +jsonschema==4.26.0 + # via sphinxcontrib-redoc +jsonschema-specifications==2025.9.1 + # via jsonschema markupsafe==3.0.2 # via jinja2 packaging==24.2 @@ -36,9 +45,21 @@ pygments==2.18.0 # ansible-pygments # sphinx pyyaml==6.0.2 - # via -r docs/docsite/requirements.in + # via + # -r docs/docsite/requirements.in + # sphinxcontrib-redoc +referencing==0.37.0 + # via + # jsonschema + # jsonschema-specifications requests==2.32.3 # via sphinx +rpds-py==0.30.0 + # via + # jsonschema + # referencing +six==1.17.0 + # via sphinxcontrib-redoc snowballstemmer==2.2.0 # via sphinx sphinx==8.1.3 @@ -48,6 +69,7 @@ sphinx==8.1.3 # sphinx-notfound-page # sphinx-rtd-theme # sphinxcontrib-jquery + # sphinxcontrib-redoc sphinx-ansible-theme==0.10.3 # via -r docs/docsite/requirements.in sphinx-notfound-page==1.0.4 @@ -66,7 +88,15 @@ sphinxcontrib-jsmath==1.0.1 # via sphinx sphinxcontrib-qthelp==2.0.0 # via sphinx +sphinxcontrib-redoc==1.6.0 + # via -r docs/docsite/requirements.in sphinxcontrib-serializinghtml==2.0.0 # via sphinx +typing-extensions==4.15.0 + # via referencing urllib3==2.2.3 # via requests + +# The following packages are considered to be unsafe in a requirements file: +setuptools==80.9.0 + # via -r docs/docsite/requirements.in diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst index a26d2fd6f5..6ca650a9cb 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -18,9 +18,11 @@ Ansible AWX helps teams manage complex multi-tier deployments by adding control, contributor/DJANGO_REQUIREMENTS contributor/API_REQUIREMENTS + .. toctree:: :maxdepth: 2 :caption: Developers rest_api/index + open_api/index diff --git a/docs/docsite/rst/open_api/explorer.rst b/docs/docsite/rst/open_api/explorer.rst new file mode 100644 index 0000000000..8feca331c5 --- /dev/null +++ b/docs/docsite/rst/open_api/explorer.rst @@ -0,0 +1 @@ +:orphan: diff --git a/docs/docsite/rst/open_api/index.rst b/docs/docsite/rst/open_api/index.rst new file mode 100644 index 0000000000..260d6ad4fb --- /dev/null +++ b/docs/docsite/rst/open_api/index.rst @@ -0,0 +1,10 @@ +=================== +AWX OpenAPI Schema +=================== + +This document describes the OpenAPI 3.0.3 specification for the AWX API (version v2). + +This schema serves as the complete API documentation and contract for interacting programmatically with AWX, which is used for managing Ansible automation workflows, inventories, credentials, and job execution. + +* `Explore the AWX OpenAPI Schema `_ +* `Download the AWX OpenAPI Schema `_ diff --git a/docs/docsite/rst/rest_api/_swagger/download-json.py b/docs/docsite/rst/rest_api/_swagger/download-json.py deleted file mode 100644 index 47ded50a2a..0000000000 --- a/docs/docsite/rst/rest_api/_swagger/download-json.py +++ /dev/null @@ -1,13 +0,0 @@ -import requests - -url = "https://awx-public-ci-files.s3.amazonaws.com/community-docs/swagger.json" -swagger_json = "./docs/docsite/rst/rest_api/_swagger/swagger.json" - -response = requests.get(url) - -if response.status_code == 200: - with open(swagger_json, 'wb') as file: - file.write(response.content) - print(f"JSON file downloaded to {swagger_json}") -else: - print(f"Request failed with status code: {response.status_code}") diff --git a/sonar-project.properties b/sonar-project.properties index 0c9b431801..628e1b7c17 100644 --- a/sonar-project.properties +++ b/sonar-project.properties @@ -77,7 +77,9 @@ sonar.exclusions=\ **/*.pyd,\ **/build/**,\ **/dist/**,\ - **/*.egg-info/** + **/*.egg-info/**,\ + **/download-json.py,\ + docs/docsite/conf.py # ============================================================================= # COVERAGE EXCLUSIONS diff --git a/tox.ini b/tox.ini index a011afdca4..e374047717 100644 --- a/tox.ini +++ b/tox.ini @@ -36,5 +36,5 @@ deps = -r{toxinidir}/docs/docsite/requirements.in -c{toxinidir}/docs/docsite/requirements.txt commands = - python {toxinidir}/docs/docsite/rst/rest_api/_swagger/download-json.py + python {toxinidir}/docs/docsite/download-json.py sphinx-build -T -E -W -n --keep-going {tty:--color} -j auto -c docs/docsite -d docs/docsite/build/doctrees -b html docs/docsite/rst docs/docsite/build/html