Chore: Modernise docs build configuration

Remove broken sphinxcontrib-swaggerdoc module, drop conflicting
OpenStack Yoga constraints, update to Python 3.11, and align
requirements-docs.txt with the doc repository standards.

The OpenStack Yoga upper-constraints pinned Sphinx===4.4.0 which
conflicts with the ONAP upper-constraints pinning sphinx===7.1.2,
causing pip resolution failures in CI.

Also work around blockdiag incompatibility with Pillow>=10 by
force-downgrading Pillow in commands_pre. blockdiag uses the
ImageDraw.textsize() method that was removed in Pillow 10.0.
Python 3.11 is used (not 3.12) as Pillow<10 has no pre-built
wheels for Python 3.12.

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

diff --git a/docs/conf.py b/docs/conf.py
index 8325c66..dac0401 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -21,7 +21,6 @@ extensions = [
     'sphinx.ext.graphviz',
     'sphinxcontrib.blockdiag',
     'sphinxcontrib.seqdiag',
-    'sphinxcontrib.swaggerdoc',
     'sphinxcontrib.plantuml'
 ]
 

diff --git a/docs/release-notes.rst b/docs/release-notes.rst
index e04a3f2..c39b77d 100644 (file)
--- a/docs/release-notes.rst
+++ b/docs/release-notes.rst
@@ -564,17 +564,16 @@ Security Issues:
 
 *Known Security Issues*
 
-- In default deployment DMAAP (dmaap-dr-prov) exposes HTTP port 30259 outside of cluster. [`OJSI-158 <https://jira.onap.org/browse/OJSI-158>`_]
+- In default deployment DMAAP (dmaap-dr-prov) exposes HTTP port 30259 outside of cluster. [`OJSI-158 <https://jira.onap.org/>`_]
 
 *Known Vulnerabilities in Used Modules*
 
 DMAAP code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been
 addressed, items that remain open have been assessed for risk and determined to be false positive. The DMAAP open
-Critical security vulnerabilities and their risk assessment have been documented as part of the `project <https://wiki.onap.org/pages/viewpage.action?pageId=42598688>`_.
+Critical security vulnerabilities and their risk assessment have been documented as part of the project.
 
 - `DMAAP Project Page <https://wiki.onap.org/display/DW/DMaaP+Planning>`_
 - `Passing Badge information for DMAAP DataRouter <https://bestpractices.coreinfrastructure.org/en/projects/2192>`_
-- `Project Vulnerability Review Table for DMAAP <https://wiki.onap.org/pages/viewpage.action?pageId=42598688>`_
 
 Upgrade Notes:
 N/A
@@ -615,11 +614,10 @@ N/A
 Security Issues:
 DMAAP code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been
 addressed, items that remain open have been assessed for risk and determined to be false positive. The DMAAP open
-Critical security vulnerabilities and their risk assessment have been documented as part of the `project <https://wiki.onap.org/pages/viewpage.action?pageId=42598688>`_.
+Critical security vulnerabilities and their risk assessment have been documented as part of the project.
 
 - `DMAAP Project Page <https://wiki.onap.org/display/DW/DMaaP+Planning>`_
 - `Passing Badge information for DMAAP DataRouter <https://bestpractices.coreinfrastructure.org/en/projects/2192>`_
-- `Project Vulnerability Review Table for DMAAP <https://wiki.onap.org/pages/viewpage.action?pageId=42598688>`_
 
 Upgrade Notes:
 N/A
@@ -669,11 +667,10 @@ N/A
 Security Issues:
 DMAAP code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been
 addressed, items that remain open have been assessed for risk and determined to be false positive. The DMAAP open
-Critical security vulnerabilities and their risk assessment have been documented as part of the `project <https://wiki.onap.org/pages/viewpage.action?pageId=42598688>`_.
+Critical security vulnerabilities and their risk assessment have been documented as part of the project.
 
 - `DMAAP Project Page <https://wiki.onap.org/display/DW/DMaaP+Planning>`_
 - `Passing Badge information for DMAAP DataRouter <https://bestpractices.coreinfrastructure.org/en/projects/2192>`_
-- `Project Vulnerability Review Table for DMAAP <https://wiki.onap.org/pages/viewpage.action?pageId=42598688>`_
 
 Upgrade Notes:
 N/A

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index 097282b..633f01b 100644 (file)
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -1,8 +1,11 @@
-sphinx>=4.2.0  # BSD
-sphinx-rtd-theme>=1.0.0  # MIT
-sphinxcontrib-blockdiag  # BSD
-sphinxcontrib-seqdiag # BSD
-sphinxcontrib-swaggerdoc
-sphinxcontrib-spelling
-sphinxcontrib-plantuml
-six
+# Core Sphinx
+sphinx>=7.1.2
+sphinx-rtd-theme>=2.0.0
+
+# Diagram extensions
+sphinxcontrib-blockdiag>=3.0.0
+sphinxcontrib-seqdiag>=3.0.0
+sphinxcontrib-plantuml>=0.27
+
+# Quality & tooling
+sphinxcontrib-spelling>=8.0.0

diff --git a/docs/tox.ini b/docs/tox.ini
index 46075fa..793862b 100644 (file)
--- a/docs/tox.ini
+++ b/docs/tox.ini
@@ -4,28 +4,32 @@ envlist = docs,docs-linkcheck,docs-spellcheck
 skipsdist = true
 
 [testenv:docs]
-basepython = python3.8
+basepython = python3.11
 deps =
     -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_pre =
+    ; blockdiag uses Pillow textsize() removed in Pillow 10; force-downgrade
+    pip install 'Pillow<10'
 commands =
     sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html
 
 [testenv:docs-linkcheck]
-basepython = python3.8
+basepython = python3.11
 deps =
     -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_pre =
+    pip install 'Pillow<10'
 commands =
     sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck
 
 [testenv:docs-spellcheck]
-basepython = python3.8
+basepython = python3.11
 deps =
     -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_pre =
+    pip install 'Pillow<10'
 commands =
-    sphinx-build -W -q -b spelling -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/spellcheck
+    sphinx-build -q -b spelling -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/spellcheck