From: Matthew Watkins <mwatkins@linuxfoundation.org>
Date: Mon, 2 Mar 2026 15:24:45 +0000 (+0000)
Subject: Docs: Replace swaggerv2doc directive with openapi
X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F30%2F143430%2F3;p=dcaegen2.git

Docs: Replace swaggerv2doc directive with openapi

Replace deprecated swaggerv2doc directive in PRH.rst with the openapi
directive from sphinxcontrib-openapi. The swaggerv2doc extension has been
removed from conf.py and requirements-docs.txt.

Modernise docs build configuration:
- Remove OpenStack Yoga constraints (conflicted with ONAP constraints)
- 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

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

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index f56b3b71..be88ea97 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -6,9 +6,9 @@
 
 version: 2
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
-    python: "3.8"
+    python: "3.12"
 
 python:
   install:
diff --git a/docs/conf.py b/docs/conf.py
index 6abc4786..cd883e38 100644
--- 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'
 ]
 
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index 097282b9..058bcb46 100644
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -1,8 +1,8 @@
-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>=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
 six
diff --git a/docs/sections/apis/PRH.rst b/docs/sections/apis/PRH.rst
index 52d12d1d..bdbd3831 100644
--- a/docs/sections/apis/PRH.rst
+++ b/docs/sections/apis/PRH.rst
@@ -26,7 +26,7 @@ in plug and play manner.
 
    "PNF Registration Handler", ":download:`link <PRH.json>`", ":download:`link <PRH.yaml>`"
 
-.. swaggerv2doc:: PRH.json
+.. openapi:: PRH.json
 
 Introduction
 ============
diff --git a/docs/tox.ini b/docs/tox.ini
index 01fe1a3d..3710e3ca 100644
--- a/docs/tox.ini
+++ b/docs/tox.ini
@@ -4,32 +4,31 @@ envlist = docs,docs-linkcheck,docs-spellcheck
 skipsdist = true
 
 [testenv:docs]
-allowlist_externals =
-    echo
-    git
-    sh
-basepython = python3.8
+basepython = python3.12
 deps =
+    setuptools>=65.0.0
     -r{toxinidir}/requirements-docs.txt
-    -chttps://releases.openstack.org/constraints/upper/yoga
     -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}/_build/html
-    echo "Generated docs available in {toxinidir}/_build/html"
-
+    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://releases.openstack.org/constraints/upper/yoga
     -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://releases.openstack.org/constraints/upper/yoga
     -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
-commands = sphinx-build -W -q -b spelling -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/spellcheck
+commands =
+    sphinx-build -W -q -b spelling -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/spellcheck