Docs: Modernise docs build configuration

Follow-up to the merged swaggerdoc removal (143028). Modernise the
remaining docs build configuration:
- 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
- Uncomment docs-linkcheck testenv (Yoga constraints removed)
- Add allowlist_externals to docs testenv
- Comment out swaggerv2doc directive in bp-processor.rst (source
  JSON file contains malformed JSON that no Sphinx directive can parse)
- Remove orphaned test_test_test label in node-type.rst that causes
  duplicate target error with docs-linkcheck

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

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 7effcde..b005fff 100644 (file)
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -1,5 +1,5 @@
 ---
-# .readthedocs.yml
+# .readthedocs.yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 # Required
@@ -7,9 +7,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/api-reference/bp-processor.rst b/docs/api-reference/bp-processor.rst
index 590aa06..4720f29 100644 (file)
--- a/docs/api-reference/bp-processor.rst
+++ b/docs/api-reference/bp-processor.rst
@@ -153,10 +153,13 @@ HTTP Status 202 OK
 API Reference
 --------------
 
-The full API reference is available in the swagger file provided in the `Download`_ section above.
-You can explore the API interactively by importing the swagger file into tools such as
-`Swagger UI <https://swagger.io/tools/swagger-ui/>`_ or
-`Postman <https://www.postman.com/>`_.
+.. note::
+   The embedded API documentation has been removed because the source swagger
+   file contains malformed JSON and cannot be rendered by Sphinx.
+   Use the download link above or paste the file into
+   `Swagger Editor <https://editor.swagger.io/>`_ to browse the API reference.
+
+.. .. openapi:: media/cds-bp-processor-api-swagger.json
 
 
 

diff --git a/docs/conf.py b/docs/conf.py
index a6c20e4..339f36b 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -49,5 +49,15 @@ def setup(app):
     app.add_css_file("css/ribbon.css")
 
 linkcheck_ignore = [
-  r'http://localhost:\d+/'
+  # Local/development URLs referenced in installation and usage guides
+  r'http://localhost:\d+/',
+  r'https?://127\.0\.0\.1:\d+/',
+  # GitHub rate-limits CI runners (HTTP 429) making checks unreliable;
+  # also, line-number anchors (#L123) are rendered via JavaScript and
+  # cannot be resolved by the link checker
+  r'https://github\.com/onap/',
+  # Wiki attachment/thumbnail images were lost during the wiki.onap.org
+  # migration to lf-onap.atlassian.net; the old download URLs now 404
+  r'https://wiki\.onap\.org/download/attachments/',
+  r'https://wiki\.onap\.org/download/thumbnails/',
 ]

diff --git a/docs/index.rst b/docs/index.rst
index 9e226e5..7650a35 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -99,7 +99,7 @@ Library
     itself.
 
     The helper can be found in below link:
-    https://github.com/onap/ccsdk-apps/blob/master/components/scripts/python/ccsdk_netconf/common.py
+    https://github.com/onap/ccsdk-cds/blob/master/components/scripts/python/ccsdk_netconf/common.py
 
 .. |toscaModel| image:: media/tosca_model.jpg
    :width: 500pt

diff --git a/docs/modelingconcepts/node-type.rst b/docs/modelingconcepts/node-type.rst
index 98c99a6..d237115 100644 (file)
--- a/docs/modelingconcepts/node-type.rst
+++ b/docs/modelingconcepts/node-type.rst
@@ -204,8 +204,6 @@ listed in the other section.
             `Script executor type <https://github.com/onap/ccsdk-cds/blob/master/components/model-catalog/definition-type/starter-type/node_type/component-script-executor.json>`_
             is the definition
 
-            .. _test_test_test:
-
             .. code-block:: json
               :caption: **component-script-executor**
 
@@ -712,7 +710,7 @@ listed in the other section.
                  - Mandatory
 
 
-            `DB source type <https://github.com/onap/ccsdk-cds/blob/master/components/model-catalog/definition-type/starter-type/node_type/source-processor-db.json>`_
+            `DB source type <https://github.com/onap/ccsdk-cds/blob/master/components/model-catalog/definition-type/starter-type/node_type/source-db.json>`_
             is the definition:
 
             .. code-block:: json

diff --git a/docs/modelingconcepts/test.rst b/docs/modelingconcepts/test.rst
index afb273d..f2693f1 100644 (file)
--- a/docs/modelingconcepts/test.rst
+++ b/docs/modelingconcepts/test.rst
@@ -38,7 +38,7 @@ Reference link for sample generated uat.yaml file for pnf plug & play use case:
 `uat.yaml file <https://gerrit.onap.org/r/gitweb?p=ccsdk/cds.git;a=tree;f=components/model-catalog/blueprint-model/uat-blueprints/pnf_config/Tests;h=230d506720c4a1066784c1fe9e0ba0206bbb13cf;hb=refs/heads/master>`_.
 
 As UAT is part of unit testing, it runs in jenkins job
-`ccsdk-cds-master-verify-java <https://jenkins.onap.org/job/ccsdk-cds-master-verify-java/>`_
+`ccsdk-cds-master-verify-java <https://jenkins.onap.org/job/ccsdk-cds-maven-verify-master-mvn39-openjdk21/>`_
 whenever a new commit/patch pushed on gerrit in ccsdk/cds repo.
 
 Executing UAT based test inside you own CBA as SpringBootTest based JUnit test

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index e9abe26..dd71cc9 100644 (file)
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -1,8 +1,9 @@
-sphinx>=4.2.0  # BSD
-sphinx-rtd-theme>=1.0.0  # MIT
-sphinxcontrib-blockdiag  # BSD
-sphinxcontrib-seqdiag # BSD
-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
 sphinx-tabs
 six

diff --git a/docs/resourcedefinition/index.rst b/docs/resourcedefinition/index.rst
index aa83920..d177367 100644 (file)
--- a/docs/resourcedefinition/index.rst
+++ b/docs/resourcedefinition/index.rst
@@ -96,7 +96,7 @@ Also please click below for resource source available details
    resourcesource
 
 .. _TOSCA: http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/csprd01/TOSCA-Simple-Profile-YAML-v1.0-csprd01.html#DEFN_ENTITY_NODE_TYPE
-.. _Resource: https://wiki.onap.org/display/DW/Modeling+Concepts#ModelingConcepts-NodeResourceSource
+.. _Resource: https://docs.onap.org/projects/onap-ccsdk-cds/en/latest/modelingconcepts/node-type.html
 
 
 .. |image0| image:: media/mandatory.JPG

diff --git a/docs/tox.ini b/docs/tox.ini
index 7aef9a5..fd864cf 100644 (file)
--- a/docs/tox.ini
+++ b/docs/tox.ini
@@ -4,25 +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 -q -W -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html
+allowlist_externals =
+    echo
+    git
+    sh
 
-#[testenv:docs-linkcheck]
-#basepython = python3.8
-#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 =
-#    sphinx-build -q -W -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck
+[testenv:docs-linkcheck]
+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 -q -W -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 =

diff --git a/docs/usecases/pnf-simulator.rst b/docs/usecases/pnf-simulator.rst
index 765b70a..df53347 100644 (file)
--- a/docs/usecases/pnf-simulator.rst
+++ b/docs/usecases/pnf-simulator.rst
@@ -29,7 +29,7 @@ it is easy and enables debugging.
 
 * CDS in Microk8s: https://wiki.onap.org/display/DW/Running+CDS+on+Microk8s (RDT link to be added)
 * CDS in Minikube: https://wiki.onap.org/display/DW/Running+CDS+in+minikube (RDT link to be added)
-* CDS in an IDE:  https://docs.onap.org/projects/onap-ccsdk-cds/en/latest/userguide/running-bp-processor-in-ide.html
+* CDS in an IDE:  ../userguides/developer-guide/running-bp-processor-in-ide.html
 
 Run PNF Simulator and install module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -303,7 +303,7 @@ here but they are not tested by the author of this guide.
       .. warning::
          This method of setting up the PNF simulator is not tested by the author of this guide
 
-      You can refer to `PnP PNF Simulator wiki page <https://wiki.onap.org/display/DW/PnP+PNF+Simulator>`_
+      You can refer to `PnP PNF Simulator wiki page <https://lf-onap.atlassian.net/wiki/spaces/DW/pages/16529416>`_
       to clone the GIT repo and start the required docker containers. We are interested in the
       `sysrepo/sysrepo-netopeer2` docker container to load a simple YANG similar to vFW Packet Generator.
 

diff --git a/docs/usecases/vfw-cnf-use-case.rst b/docs/usecases/vfw-cnf-use-case.rst
index e36cfbf..8fa9c93 100644 (file)
--- a/docs/usecases/vfw-cnf-use-case.rst
+++ b/docs/usecases/vfw-cnf-use-case.rst
@@ -433,7 +433,7 @@ CBA of vFW CNF use case is already enriched and VSP of vFW CNF has CBA included
 
 Further information about the use case, role of the CDS and all the steps required to reproduce the process can be found in the dedicated web page
 
-:ref:`vFirewall CNF Use Case<onap-integration:docs_vFW_CNF_CDS>`
+`vFirewall CNF Use Case <https://docs.onap.org/projects/onap-integration/en/latest/docs_vFW_CNF_CDS.html>`_
 
 The vFW CNF use case is an official use case used for verification of the CNF Orchestration extensions.
 

diff --git a/docs/userguides/design-time-guide/resourceassignment.rst b/docs/userguides/design-time-guide/resourceassignment.rst
index aa4f6b5..e37187d 100644 (file)
--- a/docs/userguides/design-time-guide/resourceassignment.rst
+++ b/docs/userguides/design-time-guide/resourceassignment.rst
@@ -71,4 +71,4 @@ capability-data: defines what capability to use to create a specific resource, a
 
 In order to facilitate NETCONF interaction within scripts, a python NetconfClient binded to our Kotlin implementation is made available. This NetconfClient can be used when using the netconf-component-executor.
 
-The client can be find here: https://github.com/onap/ccsdk-apps/blob/master/components/scripts/python/ccsdk_netconf/netconfclient.py
\ No newline at end of file
+The client can be find here: https://github.com/onap/ccsdk-cds/blob/master/components/scripts/python/ccsdk_netconf/netconfclient.py
\ No newline at end of file

diff --git a/docs/userguides/developer-guide/running-bp-processor-in-ide.rst b/docs/userguides/developer-guide/running-bp-processor-in-ide.rst
index f2a2a59..879a4c6 100644 (file)
--- a/docs/userguides/developer-guide/running-bp-processor-in-ide.rst
+++ b/docs/userguides/developer-guide/running-bp-processor-in-ide.rst
@@ -17,7 +17,7 @@ This way, code changes can be conveniently tested and debugged.
 Check out the code
 ~~~~~~~~~~~~~~~~~~~
 
-Check out the code from Gerrit: https://gerrit.onap.org/r/#/admin/projects/ccsdk/cds
+Check out the code from Gerrit: https://gerrit.onap.org/r/admin/repos/ccsdk/cds
 
 Build it locally
 ~~~~~~~~~~~~~~~~~~

diff --git a/docs/userguides/installation.rst b/docs/userguides/installation.rst
index bf76dd9..3377c9f 100644 (file)
--- a/docs/userguides/installation.rst
+++ b/docs/userguides/installation.rst
@@ -23,7 +23,7 @@ Get the chart
 
 Make sure to checkout the release to use, by replacing $release-tag in bellow command
 
-git clone https://gerrit.onap.org/r/oom
+git clone https://gerrit.onap.org/r/a/oom
 git checkout tags/$release-tag