Docs: Modernise docs build configuration

Add sphinxcontrib-mermaid to requirements-docs.txt to prepare for
migrating live seqdiag diagrams to Mermaid syntax.

Rename whitelist_externals to allowlist_externals in both tox.ini
files for tox 4.x compatibility.

Issue-ID: CIMAN-33
Change-Id: I0b9fc98970555f41cb21692b892be64f3ae468e6
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Matthew Watkins <mwatkins@linuxfoundation.org>

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 3797dc8..d3059ad 100644 (file)
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -9,12 +9,13 @@ formats:
   - htmlzip
 
 build:
-  image: latest
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
 
 python:
-  version: 3.7
   install:
     - requirements: docs/requirements-docs.txt
 
 sphinx:
-  configuration: docs/conf.py
+  configuration: docs/conf.py
\ No newline at end of file

diff --git a/docs/Chapter2/index.rst b/docs/Chapter2/index.rst
index 09e65bd..a28e502 100644 (file)
--- a/docs/Chapter2/index.rst
+++ b/docs/Chapter2/index.rst
@@ -334,8 +334,7 @@ Glossary
     NFVI
         Network Function Virtualization Infrastructure
 
-    VNFC
-        Virtualized Network Function Components
+
 
     MANO
         Management And Network Orchestration

diff --git a/docs/_static/css/ribbon.css b/docs/_static/css/ribbon.css
index 6008cb1..afb9480 100644 (file)
--- a/docs/_static/css/ribbon.css
+++ b/docs/_static/css/ribbon.css
@@ -59,5 +59,5 @@
 /* fix width of the screen */
 
 .wy-nav-content {
-    max-width: none;
+    max-width: 800px;
 }

diff --git a/docs/conf.py b/docs/conf.py
index 5785e83..1769e24 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,38 +1,79 @@
-from docs_conf.conf import *
+"""Sphinx configuration for vnfrqts/requirements documentation."""
 
-branch = 'latest'
-master_doc = 'index'
-version = 'honolulu'
+project = "onap"
+release = "master"
+version = "master"
+
+author = "Open Network Automation Platform"
+# yamllint disable-line rule:line-length
+copyright = "ONAP. Licensed under Creative Commons Attribution 4.0 International License"
+
+pygments_style = "sphinx"
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "style_nav_header_background": "white",
+    "sticky_navigation": "False",
+}
+html_logo = "_static/logo_onap_2017.png"
+html_favicon = "_static/favicon.ico"
+html_static_path = ["_static"]
+html_show_sphinx = False
+
+master_doc = "index"
+
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.ifconfig",
+    "sphinxcontrib.needs",
+    "sphinxcontrib.plantuml",
+    "sphinxcontrib.mermaid",
+]
+
+exclude_patterns = [
+    ".DS_Store",
+    "_build",
+    "Thumbs.db",
+    ".tox",
+]
+
+todo_include_todos = False
 
 linkcheck_ignore = [
-    'http://localhost',
+    "http://localhost",
 ]
 
-intersphinx_mapping.update({
-    'modeling': ('https://docs.onap.org/projects/onap-modeling-modelspec/en/latest/', None),
-    'dcae': ('https://docs.onap.org/projects/onap-dcaegen2/en/latest/', None),
-    'appc': ('https://docs.onap.org/projects/onap-appc/en/latest/', None),
-    'appc-deployment': ('https://docs.onap.org/projects/onap-appc-deployment/en/latest/', None),
-})
+branch = "latest"
+
+doc_url = "https://docs.onap.org/projects"
+
+intersphinx_mapping = {
+    "modeling": (
+        "{}/onap-modeling-modelspec/en/latest/".format(doc_url),
+        None,
+    ),
+    "dcae": (
+        "{}/onap-dcaegen2/en/latest/".format(doc_url),
+        None,
+    ),
+}
 
-html_last_updated_fmt = '%d-%b-%y %H:%M'
+html_last_updated_fmt = "%d-%b-%y %H:%M"
 
 
 def setup(app):
     app.add_css_file("css/ribbon.css")
 
 
-from docutils.parsers.rst import directives
-
-needs_extra_options = {
-    "target": directives.unchanged,
-    "keyword": directives.unchanged,
-    "introduced": directives.unchanged,
-    "updated": directives.unchanged,
-    "impacts": directives.unchanged,
-    "validation_mode": directives.unchanged,
-}
+needs_extra_options = [
+    "target",
+    "keyword",
+    "introduced",
+    "updated",
+    "impacts",
+    "validation_mode",
+]
 
 needs_id_regex = "^[A-Z0-9]+-[A-Z0-9]+"
 needs_id_required = True
-needs_title_optional = True
+needs_title_optional = True
\ No newline at end of file

diff --git a/docs/conf.yaml b/docs/conf.yaml
deleted file mode 100644 (file)
index ab59281..0000000
--- a/docs/conf.yaml
+++ /dev/null
@@ -1,7 +0,0 @@
----
-project_cfg: onap
-project: onap
-
-# Change this to ReleaseBranchName to modify the header
-default-version: latest
-#

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index 3b3441a..5f21095 100644 (file)
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -1,3 +1,5 @@
-lfdocs-conf
 sphinx>=4.2.0  # BSD
 sphinx-rtd-theme>=1.0.0  # MIT
+sphinxcontrib-mermaid>=1.0.0
+sphinxcontrib-needs
+sphinxcontrib-plantuml
\ No newline at end of file

diff --git a/docs/tox.ini b/docs/tox.ini
index 42ffa68..beff649 100644 (file)
--- a/docs/tox.ini
+++ b/docs/tox.ini
@@ -4,22 +4,21 @@ envlist = docs,
 skipsdist = true
 
 [testenv:docs]
-basepython = python3
+basepython = python3.13
 deps =
     -r{toxinidir}/requirements-docs.txt
-    -chttps://git.onap.org/doc/plain/etc/upper-constraints.os.txt
     -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt
 commands =
     sphinx-build -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html
     echo "Generated docs available in {toxinidir}/_build/html"
-whitelist_externals =
+allowlist_externals =
     echo
     git
     sh
 
 [testenv:docs-linkcheck]
-basepython = python3
+basepython = python3.13
 #deps = -r{toxinidir}/requirements-docs.txt
 commands = echo "Link Checking not enforced"
 #commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck
-whitelist_externals = echo
+allowlist_externals = echo

diff --git a/etc/requirements.txt b/etc/requirements.txt
index 71e0cfd..c8b8a77 100644 (file)
--- a/etc/requirements.txt
+++ b/etc/requirements.txt
@@ -13,4 +13,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #############################################################################
-lfdocs-conf
\ No newline at end of file
+sphinx>=4.2.0  # BSD
+sphinx-rtd-theme>=1.0.0  # MIT
+sphinxcontrib-mermaid>=1.0.0
+sphinxcontrib-needs
+sphinxcontrib-plantuml
\ No newline at end of file

diff --git a/tox.ini b/tox.ini
index 36bf6c4..b448930 100644 (file)
--- a/tox.ini
+++ b/tox.ini
@@ -27,7 +27,7 @@ commands =
     python3 check.py
     sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
     echo "Generated docs available in {toxinidir}/_build/html"
-whitelist_externals =
+allowlist_externals =
     echo
     git
     sh
@@ -36,15 +36,13 @@ whitelist_externals =
 [testenv:needs]
 basepython = python3
 deps = -r{toxinidir}/etc/requirements.txt
-       -chttps://git.onap.org/doc/plain/etc/upper-constraints.os.txt
        -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt
 commands = sphinx-build -c ./docs/ -b needs -n -d {envtmpdir}/doctrees ./docs/ ./docs/data/
 
 [testenv:docs-linkcheck]
 basepython = python3
 deps = -r{toxinidir}/etc/requirements.txt
-       -chttps://git.onap.org/doc/plain/etc/upper-constraints.os.txt
        -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt
 commands = echo "Link Checking not enforced"
 #commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck
-whitelist_externals = echo
\ No newline at end of file
+allowlist_externals = echo
\ No newline at end of file