From: Matthew Watkins Date: Mon, 2 Mar 2026 16:42:53 +0000 (+0000) Subject: Docs: Modernise docs build configuration X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F32%2F143432%2F9;p=ccsdk%2Fcds.git 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 --- diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 7effcde5c..b005fff2d 100644 --- 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 590aa06a6..4720f2915 100644 --- 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 `_ or -`Postman `_. +.. 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 `_ to browse the API reference. + +.. .. openapi:: media/cds-bp-processor-api-swagger.json diff --git a/docs/conf.py b/docs/conf.py index a6c20e463..339f36b94 100644 --- 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 9e226e537..7650a3506 100644 --- 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 98c99a61e..d23711518 100644 --- a/docs/modelingconcepts/node-type.rst +++ b/docs/modelingconcepts/node-type.rst @@ -204,8 +204,6 @@ listed in the other section. `Script executor type `_ 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 `_ + `DB source type `_ is the definition: .. code-block:: json diff --git a/docs/modelingconcepts/test.rst b/docs/modelingconcepts/test.rst index afb273d52..f2693f1da 100644 --- 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 `_. As UAT is part of unit testing, it runs in jenkins job -`ccsdk-cds-master-verify-java `_ +`ccsdk-cds-master-verify-java `_ 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 e9abe2667..dd71cc91e 100644 --- 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 aa83920cb..d17736794 100644 --- 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 7aef9a52b..fd864cf58 100644 --- 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 765b70abd..df5334733 100644 --- 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 `_ + You can refer to `PnP PNF Simulator wiki page `_ 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 e36cfbfc3..8fa9c9390 100644 --- 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` +`vFirewall CNF Use Case `_ 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 aa4f6b559..e37187dc3 100644 --- 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 f2a2a59d2..879a4c61a 100644 --- 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 bf76dd9d6..3377c9fef 100644 --- 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