Chore: Modernize docs configuration for Python 3.12+

Remove broken/outdated Python modules that are incompatible with modern
Python versions. Update .readthedocs.yaml to use ubuntu-24.04 and Python
3.13. Modernize tox.ini (use allowlist_externals, pin basepython to
3.12, use local constraints instead of remote URLs that now 404).
Refresh docs/conf.py and update branch references to latest/master.
Add etc/upper-constraints.onap.txt from the doc repo.

Removed modules: sphinxcontrib-swaggerdoc, sphinxcontrib-spelling.

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

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 3797dc8..a57182b 100644 (file)
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -3,18 +3,16 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 # Required
-version: 2
-
-formats:
-  - htmlzip
 
+version: 2
 build:
-  image: latest
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
 
 python:
-  version: 3.7
   install:
-    - requirements: docs/requirements-docs.txt
+  - requirements: docs/requirements-docs.txt
 
 sphinx:
   configuration: docs/conf.py

diff --git a/docs/conf.py b/docs/conf.py
index e90ad58..1684cbc 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,6 +1,6 @@
 project = "onap"
-release = "kohn"
-version = "kohn"
+release = "master"
+version = "master"
 
 author = "Open Network Automation Platform"
 # yamllint disable-line rule:line-length
@@ -9,8 +9,8 @@ copyright = "ONAP. Licensed under Creative Commons Attribution 4.0 International
 pygments_style = "sphinx"
 html_theme = "sphinx_rtd_theme"
 html_theme_options = {
-  "style_nav_header_background": "white",
-  "sticky_navigation": "False" }
+    "style_nav_header_background": "white",
+    "sticky_navigation": "False" }
 html_logo = "_static/logo_onap_2017.png"
 html_favicon = "_static/favicon.ico"
 html_static_path = ["_static"]
@@ -21,37 +21,25 @@ extensions = [
     'sphinx.ext.graphviz',
     'sphinxcontrib.blockdiag',
     'sphinxcontrib.seqdiag',
-    'sphinxcontrib.swaggerdoc',
-    'sphinxcontrib.plantuml'
+    'sphinxcontrib.plantuml',
 ]
 
 exclude_patterns = ['archived/*.rst', '.tox']
-#
-# Map to 'latest' if this file is used in 'latest' (master) 'doc' branch.
-# Change to {releasename} after you have created the new 'doc' branch.
-#
 
-branch = 'kohn'
+branch = 'latest'
+master_doc = 'index'
 
 intersphinx_mapping = {}
 doc_url = 'https://docs.onap.org/projects'
-master_doc = 'index'
 
-spelling_word_list_filename='spelling_wordlist.txt'
+spelling_word_list_filename = 'spelling_wordlist.txt'
 spelling_lang = "en_GB"
 
-#
-# Example:
-# intersphinx_mapping['onap-aai-aai-common'] = ('{}/onap-aai-aai-common/en/%s'.format(doc_url) % branch, None)
-#
-
 html_last_updated_fmt = '%d-%b-%y %H:%M'
 
-
 def setup(app):
     app.add_css_file("css/ribbon.css")
 
-
 linkcheck_ignore = [
-  r'http://localhost:\d+/'
+    r'http://localhost:\d+/',
 ]

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index 71df2ab..d28f4f6 100644 (file)
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -1,7 +1,19 @@
-sphinx>=4.2.0  # BSD
-sphinx-rtd-theme>=1.0.0  # MIT
-sphinxcontrib-blockdiag  # BSD
-sphinxcontrib-seqdiag # BSD
-sphinxcontrib-swaggerdoc
-sphinxcontrib-spelling
-sphinxcontrib-plantuml
+# Compatibility
+setuptools>=65.0.0
+Pillow>=10.1.0
+
+# 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
+
+# API documentation
+sphinxcontrib-openapi>=0.8.4
+
+# Quality & tooling
+sphinxcontrib-spelling>=8.0.0
+sphinx-toolbox>=3.5.0

diff --git a/docs/tox.ini b/docs/tox.ini
index 2c0a396..714e263 100644 (file)
--- a/docs/tox.ini
+++ b/docs/tox.ini
@@ -1,25 +1,24 @@
 [tox]
 minversion = 1.6
-envlist = docs,
+envlist = docs,docs-linkcheck
 skipsdist = true
 
 [testenv:docs]
-basepython = python3.8
-deps = -r{toxinidir}/requirements-docs.txt
-       -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt
-       -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
-
+basepython = python3.12
+deps =
+    setuptools>=65.0.0
+    -r{toxinidir}/requirements-docs.txt
+    -c{toxinidir}/../etc/upper-constraints.onap.txt
 commands =
-    sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html
-    echo "Generated docs available in {toxinidir}/_build/html"
-whitelist_externals =
-    echo
+    sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html
+allowlist_externals =
     git
     sh
 
 [testenv:docs-linkcheck]
-basepython = python3
-#deps = -r{toxinidir}/requirements-docs.txt
-commands = echo "Link Checking not enforced"
-#commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck
-whitelist_externals = echo
+basepython = python3.12
+deps =
+    setuptools>=65.0.0
+    -r{toxinidir}/requirements-docs.txt
+    -c{toxinidir}/../etc/upper-constraints.onap.txt
+commands = sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck

diff --git a/etc/upper-constraints.onap.txt b/etc/upper-constraints.onap.txt
new file mode 100644 (file)
index 0000000..2be9f18
--- /dev/null
+++ b/etc/upper-constraints.onap.txt
@@ -0,0 +1,23 @@
+# Compatibility
+setuptools===69.0.3
+Pillow===10.4.0
+
+# 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.29
+
+# API documentation
+sphinxcontrib-openapi===0.8.4
+
+# Quality & tooling
+sphinxcontrib-spelling===8.0.0
+sphinx-toolbox===3.5.0
+
+# Code quality tools
+autopep8===2.3.1
+pylint===3.0.3