From baccf260590ca2a059d7f642af8a7340db195f75 Mon Sep 17 00:00:00 2001 From: Matthew Watkins Date: Mon, 2 Mar 2026 16:40:57 +0000 Subject: [PATCH] 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 --- .readthedocs.yaml | 22 +++++++++++----------- .../design-impl/participants/sim-participant.rst | 2 +- docs/conf.py | 2 +- docs/requirements-docs.txt | 16 ++++++++-------- docs/tox.ini | 13 ++++++++++--- 5 files changed, 31 insertions(+), 24 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index e49b4bfb..b005fff2 100644 --- 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 96683a6a..a528610a 100644 --- 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 ` -.. swaggerv2doc:: swagger/participant-sim.json +.. openapi:: swagger/participant-sim.json diff --git a/docs/conf.py b/docs/conf.py index 61e5f792..0e11e6b4 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', 'sphinx_toolbox.collapse', 'sphinxcontrib.redoc' diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index fe1de1ed..cbb8d367 100644 --- 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 096294e1..8d9aa5cd 100644 --- 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 = -- 2.16.6