Docs: Modernise docs build and replace swaggerdoc with openapi

Replace deprecated sphinxcontrib-swaggerdoc with sphinxcontrib-openapi.
Replace swaggerv2doc directive in sim-participant.rst with openapi.

Modernise docs build configuration:
- Remove OpenStack Yoga constraints (already removed in prior change)
- Update basepython from 3.8 to 3.12
- Add setuptools>=65.0.0 as explicit dependency
- Update .readthedocs.yaml to ubuntu-24.04 and python 3.12
- Align requirements-docs.txt versions with doc repo standards
- Add allowlist_externals to docs testenv

Issue-ID: CIMAN-33
Change-Id: I1332eb23d386354d21c0049471c3ad781a929224
Signed-off-by: Matthew Watkins <mwatkins@linuxfoundation.org>

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index e49b4bf..b005fff 100644 (file)
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -1,19 +1,19 @@
 ---
-# .readthedocs.yml
-# # Read the Docs configuration file
-# # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-# # Required
-#
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Required
+
 version: 2
 
 build:
-   os: ubuntu-20.04
-   tools:
-      python: "3.8"
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
 
 python:
-   install:
-   - requirements: docs/requirements-docs.txt
+  install:
+  - requirements: docs/requirements-docs.txt
 
 sphinx:
-   configuration: docs/conf.py
+  configuration: docs/conf.py

diff --git a/docs/clamp/acm/design-impl/participants/sim-participant.rst b/docs/clamp/acm/design-impl/participants/sim-participant.rst
index 96683a6..a528610 100644 (file)
--- a/docs/clamp/acm/design-impl/participants/sim-participant.rst
+++ b/docs/clamp/acm/design-impl/participants/sim-participant.rst
@@ -39,4 +39,4 @@ This API allows a Participant Simulator to be started and run for test purposes.
 
 :download:`Download Policy Participant Simulator API Swagger  <swagger/participant-sim.json>`
 
-.. swaggerv2doc:: swagger/participant-sim.json
+.. openapi:: swagger/participant-sim.json

diff --git a/docs/conf.py b/docs/conf.py
index 61e5f79..0e11e6b 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,7 +25,7 @@ extensions = [
     'sphinx.ext.graphviz',
     'sphinxcontrib.blockdiag',
     'sphinxcontrib.seqdiag',
-    'sphinxcontrib.swaggerdoc',
+    'sphinxcontrib.openapi',
     'sphinxcontrib.plantuml',
     'sphinx_toolbox.collapse',
     'sphinxcontrib.redoc'

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index fe1de1e..cbb8d36 100644 (file)
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -1,10 +1,10 @@
-sphinx>=4.2.0  # BSD
-sphinx-rtd-theme>=1.0.0  # MIT
-sphinxcontrib-blockdiag  # BSD
-sphinxcontrib-seqdiag # BSD
-sphinxcontrib-swaggerdoc
-sphinxcontrib-spelling
-sphinxcontrib-plantuml
-sphinx_toolbox
+sphinx>=7.1.2
+sphinx-rtd-theme>=2.0.0
+sphinxcontrib-blockdiag>=3.0.0
+sphinxcontrib-seqdiag>=3.0.0
+sphinxcontrib-openapi>=0.8.4
+sphinxcontrib-spelling>=8.0.0
+sphinxcontrib-plantuml>=0.27
 sphinxcontrib-redoc
+sphinx_toolbox>=3.5.0
 six

diff --git a/docs/tox.ini b/docs/tox.ini
index 096294e..8d9aa5c 100644 (file)
--- a/docs/tox.ini
+++ b/docs/tox.ini
@@ -4,24 +4,31 @@ envlist = docs,docs-linkcheck,docs-spellcheck
 skipsdist = true
 
 [testenv:docs]
-basepython = python3.8
+basepython = python3.12
 deps =
+    setuptools>=65.0.0
     -r{toxinidir}/requirements-docs.txt
     -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
 commands =
     sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html
+allowlist_externals =
+    echo
+    git
+    sh
 
 [testenv:docs-linkcheck]
-basepython = python3.8
+basepython = python3.12
 deps =
+    setuptools>=65.0.0
     -r{toxinidir}/requirements-docs.txt
     -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
 commands =
     sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck
 
 [testenv:docs-spellcheck]
-basepython = python3.8
+basepython = python3.12
 deps =
+    setuptools>=65.0.0
     -r{toxinidir}/requirements-docs.txt
     -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
 commands =