From ba4b171b2a9761da6935656e3779fb11fa18cab5 Mon Sep 17 00:00:00 2001 From: Matthew Watkins Date: Tue, 27 Jan 2026 15:29:34 +0000 Subject: [PATCH] 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 --- .readthedocs.yaml | 12 +++++------- docs/conf.py | 30 +++++++++--------------------- docs/requirements-docs.txt | 26 +++++++++++++++++++------- docs/tox.ini | 29 ++++++++++++++--------------- etc/upper-constraints.onap.txt | 23 +++++++++++++++++++++++ 5 files changed, 70 insertions(+), 50 deletions(-) create mode 100644 etc/upper-constraints.onap.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3797dc8..a57182b 100644 --- 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 --- 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 --- 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 --- 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 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 -- 2.16.6