[VOL-5061] - docs.voltha.org: Update release page.On branch dev-joey
[VOL-5079]
conf.py
sphinx_conf/exclude_patterns.py
sphinx_conf/linkcheck_ignore.py
-------------------------------
o Refactor large URL and path exclusion lists into separate files.
o Update linkcheck release_notes/*.html patterns to exclude by regex.
release_notes/voltha_2.12.rst
-----------------------------
o Update deployed package grid with current version strings.
o Re-arrange structure to display 'artifacts', include links
for pkg, pkg-app and pkg-api artifact downloads.
o Replace sonatype/nexus urls(staging) with direct links to maven central.
requirements.txt
----------------
o Added missing python package sphinx-reload.
howto/release/components/apache-karaf/
howto/release/components/atomix/
howto/release/components/onos/
--------------------------------------
o Capture dependencies, version upgrades and sources to endit
for current package release deployments.
To view changes live:
o git checkout voltha-docs
o cd voltha-docs
o make reload
Change-Id: I7b88f9d4d3329abcbe98ebbb4dbb94587088f8b9
diff --git a/conf.py b/conf.py
index 2bff845..e98cf61 100644
--- a/conf.py
+++ b/conf.py
@@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
-#
+
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
@@ -19,9 +19,16 @@
import sys
from pathlib import Path
-if True:
- pwd = Path(__file__).parent.as_posix()
- sys.path.append(pwd)
+# --------------------------------------------------------------
+# Large exclusion list(s) extracted from conf.py => .sphinx/*.py
+if True: # Set searchpath early
+ abs_path = Path('.').resolve().as_posix()
+ sys.path.insert(0, abs_path)
+
+# from sphinx_conf import *
+from sphinx_conf.exclude_patterns import exclude_patterns
+from sphinx_conf.linkcheck_ignore import linkcheck_ignore
+# --------------------------------------------------------------
# -----------------------------------------------------------------------
# -----------------------------------------------------------------------
@@ -117,41 +124,6 @@
# Usually you set "language" from the command line for these cases.
language = None
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = [
- '*/LICENSE.md',
- '*/RELEASE_NOTES.md',
- '*/vendor',
- '.DS_Store',
- 'Thumbs.db',
- '_build',
- 'voltha-go/BUILD.md',
- 'cord-tester/venv_cord',
- 'cord-tester/docs',
- 'cord-tester/src',
- 'cord-tester/README.md',
- 'cord-tester/cord-robot/README.rst',
- 'openolt/agent/*',
- 'repos',
- 'requirements.txt',
- 'bbsim/README.md',
- 'CODE_OF_CONDUCT.md',
- '*/CODE_OF_CONDUCT.md',
-# Ignore all:
- 'makefiles',
- '__pycache__',
- '**/__pycache__', # generated - faster traversal
- '.venv',
- '**/.venv', # external virtual env
-# Revisit: one directory pattern is sufficient.
- '**/doc_venv',
- '**/venv_docs',
- '**/virtualenv',
- '**/vst_venv',
-]
-
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
@@ -311,34 +283,7 @@
# -- Options for linkcheck ---------------------------------------------------
# The link checker strips off .md from links and then complains
-linkcheck_ignore=\
- [
- r'https://github.com/opencord/voltctl/blob/master/LICENSE',
- r'https://github.com/ciena/kind-voltha#voltha-up-configuration-options',
- r'https://www.sphinx-doc.org',
- r'https://github.com/opencord/bbsim/blob/master/docs/source/DMI_Server_README',
- r'https://github.com/opencord/voltha-helm-charts/blob/master/README',
- r'https://github.com/atomix/atomix/releases/tag/atomix-3.1.9',
- r'https://github.com/atomix/atomix/releases/tag/atomix-3.1.8',
- #
- r'../release_notes/voltha_2.2.html',
- r'../release_notes/voltha_2.3.html',
- r'../release_notes/voltha_2.4.html',
- r'../release_notes/voltha_2.5.html',
- r'../release_notes/voltha_2.6.html',
- r'../release_notes/voltha_2.7.html',
- r'../release_notes/voltha_2.8.html',
- r'../release_notes/voltha_2.9.html',
- r'../release_notes/voltha_2.10.html',
- r'../release_notes/voltha_2.11.html',
- r'../release_notes/voltha_2.12.html',
- #
- r'../voltha-helm-charts/README.html',
- r'https://mvnrepository.com/artifact/org.slf4j/slf4j-api',
- r'https://mvnrepository.com/artifact/org.mockito/mockito-all',
- r'https://mvnrepository.com/artifact/com.h3xstream.findsecbugs/findsecbugs-plugin',
- r'https://mvnrepository.com/artifact/com.github.spotbugs/spotbugs-maven-plugin',
- ]
+# linkcheck_ignore SEE .sphinx/linkcheck_ignore.py
# -- Configure recommonmark to use AutoStructify -----------------------------
# Docs: https://recommonmark.readthedocs.io/en/latest/auto_structify.html
diff --git a/howto/release/components/apache-karaf/index.rst b/howto/release/components/apache-karaf/index.rst
new file mode 100644
index 0000000..71787d0
--- /dev/null
+++ b/howto/release/components/apache-karaf/index.rst
@@ -0,0 +1,8 @@
+ONOS Component: Atomix
+======================
+
+Dependency will be deprecated by the v2.13 release so no need to upgrade.
+
+See Also
+--------
+- `VOL-5065 <https://jira.opencord.org/browse/VOL-5065>`_
diff --git a/howto/release/components/atomix/index.rst b/howto/release/components/atomix/index.rst
new file mode 100644
index 0000000..71787d0
--- /dev/null
+++ b/howto/release/components/atomix/index.rst
@@ -0,0 +1,8 @@
+ONOS Component: Atomix
+======================
+
+Dependency will be deprecated by the v2.13 release so no need to upgrade.
+
+See Also
+--------
+- `VOL-5065 <https://jira.opencord.org/browse/VOL-5065>`_
diff --git a/howto/release/components/index.rst b/howto/release/components/index.rst
index 3d4dfdb..3910d27 100644
--- a/howto/release/components/index.rst
+++ b/howto/release/components/index.rst
@@ -15,6 +15,10 @@
voltha-openolt-adapter
voltha-openonu-adapter-go
+ apache-karaf/index
+ atomix/index
+ onos/index
+
maclearner/index
mcast/index
olt/index
diff --git a/howto/release/components/onos/index.rst b/howto/release/components/onos/index.rst
new file mode 100644
index 0000000..71787d0
--- /dev/null
+++ b/howto/release/components/onos/index.rst
@@ -0,0 +1,8 @@
+ONOS Component: Atomix
+======================
+
+Dependency will be deprecated by the v2.13 release so no need to upgrade.
+
+See Also
+--------
+- `VOL-5065 <https://jira.opencord.org/browse/VOL-5065>`_
diff --git a/release_notes/voltha_2.12.rst b/release_notes/voltha_2.12.rst
index 433be42..59a5474 100644
--- a/release_notes/voltha_2.12.rst
+++ b/release_notes/voltha_2.12.rst
@@ -101,11 +101,12 @@
+++++++++
.. list-table:: ONOS Apps
- :widths: 30, 5, 5, 5, 5, 5, 5
+ :widths: 10, 5, 2, 3, 5, 5, 5, 1
:header-rows: 2
* - Component
- VOLTHA
+ - Maven
- Component
- with
- Gerrit
@@ -113,7 +114,8 @@
- Release
* - Name
- Version
- - Version
+ - Version(s)
+ - Artifact
- Chart
- URL
- URL
@@ -125,45 +127,62 @@
-
-
-
+ -
* - `aaa <https://gerrit.opencord.org/gitweb?p=aaa.git;a=summary>`_
- - N/A
- - `2.10.3 <https://central.sonatype.com/artifact/org.opencord/aaa/2.10.3>`_
+ -
+ - `2.10.3 <https://mvnrepository.com/artifact/org.opencord/aaa>`_
+ - `api <https://central.sonatype.com/artifact/org.opencord/aaa-api/2.10.3>`__
+ `app <https://central.sonatype.com/artifact/org.opencord/aaa-app/2.10.3>`__
+ `pkg <https://central.sonatype.com/artifact/org.opencord/aaa/2.10.3>`__
-
- `X <https://gerrit.opencord.org/plugins/gitiles/aaa/+/refs/tags/2.10.3>`__
- `X <https://github.com/opencord/aaa/tree/2.10.3>`__
-
* - `bng <https://gerrit.opencord.org/gitweb?p=bng.git;a=summary>`_
-
- - `2.5.0 <https://central.sonatype.com/artifact/org.opencord/bng/2.5.0>`_
+ - `2.5.0 <https://central.sonatype.com/artifact/org.opencord/bng>`__
+ - `api <https://mvnrepository.com/artifact/org.opencord/bng-api/2.5.0>`__
+ `app <https://mvnrepository.com/artifact/org.opencord/bng-app/2.5.0>`__
+ `pkg <https://mvnrepository.com/artifact/org.opencord/bng/2.5.0>`__
-
- `X <https://github.com/opencord/bng/tree/2.5.0>`__
- `X <https://gerrit.opencord.org/plugins/gitiles/bng/+/refs/tags/2.5.0>`__
-
* - `dhcpl2relay <https://gerrit.opencord.org/gitweb?p=dhcpl2relay.git;a=summary>`_
-
- - `2.10.0 <https://central.sonatype.com/artifact/org.opencord/dhcpl2relay/2.10.0>`_
+ - `2.10.0 <https://mvnrepository.com/artifact/org.opencord/dhcpl2relay>`_
+ - `api <https://mvnrepository.com/artifact/org.opencord/dhcpl2relay-api/2.10.0>`_
+ `app <https://mvnrepository.com/artifact/org.opencord/dhcpl2relay-app/2.10.0>`_
+ `pkg <https://mvnrepository.com/artifact/org.opencord/dhcpl2relay/2.10.0>`_
-
- `X <https://gerrit.opencord.org/plugins/gitiles/dhcpl2relay/+/refs/tags/2.10.0>`__
- `X <https://github.com/opencord/dhcpl2relay/tree/2.10.0>`__
-
* - `igmpproxy <https://gerrit.opencord.org/gitweb?p=igmpproxy.git;a=summary>`_
-
- - ``2.7.0``
+ - `2.8.0 <https://mvnrepository.com/artifact/org.opencord/onos-app-igmpproxy>`__
+ - `app <https://mvnrepository.com/artifact/org.opencord/onos-app-igmpproxy-app/2.8.0>`__
+ `api <https://mvnrepository.com/artifact/org.opencord/onos-app-igmpproxy-api/2.8.0>`__
+ `pkg <https://mvnrepository.com/artifact/org.opencord/onos-app-igmpproxy/2.8.0>`__
-
- `X <https://gerrit.opencord.org/plugins/gitiles/igmpproxy/+/refs/tags/2.7.0>`__
- `X <https://github.com/opencord/igmpproxy/tree/2.7.0>`__
- !
* - `kafka <https://gerrit.opencord.org/gitweb?p=kafka-onos.git;a=summary>`_
-
- - ``2.11.1``
+ - `2.12-unpublished <https://mvnrepository.com/artifact/org.opencord/kafka>`__
+ - `api <https://mvnrepository.com/artifact/org.opencord/kafka-api/2.10.0>`__
+ `app <https://mvnrepository.com/artifact/org.opencord/kafka-app/2.10.0>`__
+ `pkg <https://mvnrepository.com/artifact/org.opencord/kafka/2.10.0>`__
-
- - `X <https://gerrit.opencord.org/plugins/gitiles/kafka-onos/+/refs/tags/2.11.1>`__
- - `X <https://github.com/opencord/kafka-onos/tree/2.11.1>`__
+ - ``X-unpublished`` ``https://gerrit.opencord.org/plugins/gitiles/kafka-onos/+/refs/tags/2.12.0``
+ - ``X-unpublished`` ``https://github.com/opencord/kafka-onos/tree/2.12.0``
- !
* - `mcast <https://gerrit.opencord.org/gitweb?p=mcast.git;a=summary>`_
-
- `2.9.0 <https://central.sonatype.com/artifact/org.opencord/mcast/2.9.0>`_
-
+ -
- `X <https://gerrit.opencord.org/plugins/gitiles/mcast/+/refs/tags/2.9.0>`__
- `X <https://github.com/opencord/mcast/tree/2.9.0>`__
-
@@ -171,6 +190,7 @@
-
- `5.2.4 <https://central.sonatype.com/artifact/org.opencord/olt/5.2.4>`_
-
+ -
- `X <https://gerrit.opencord.org/plugins/gitiles/olt/+/refs/tags/5.2.4>`__
- `X <https://github.com/opencord/olt/tree/5.2.4>`__
-
@@ -178,6 +198,7 @@
-
- `5.11.1 <https://central.sonatype.com/artifact/org.opencord/sadis/5.11.1>`_
-
+ -
- `X <https://gerrit.opencord.org/plugins/gitiles/sadis/+/refs/tags/5.11.1>`__
- `X <https://github.com/opencord/sadis/tree/5.11.1>`__
-
@@ -185,6 +206,7 @@
-
- ``1.2.0``
-
+ -
- `X <https://gerrit.opencord.org/plugins/gitiles/pppoeagent/+/refs/tags/1.2.1>`__
- `X <https://github.com/opencord/pppoeagent/tree/1.2.1>`__
- !
@@ -192,6 +214,7 @@
-
- ``1.2.0``
-
+ -
- `X <https://gerrit.opencord.org/plugins/gitiles/olttopology/+/refs/tags/1.2.1>`__
- `X <https://github.com/opencord/olttopology/tree/1.2.1>`__
- !
diff --git a/requirements.txt b/requirements.txt
index 57a2bbc..83daea2 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,5 @@
+# -*- makefile -*-
+
Sphinx~=4.1.2
doc8~=0.9.0
docutils==0.16
@@ -6,3 +8,7 @@
sphinxcontrib-openapi~=0.6.0
sphinxcontrib-spelling~=7.2.1
git+https://github.com/zdw/sphinx-multiversion@ec7c01cdaf2f9241245e84483dfb9bc0d0dffc62
+
+sphinx-reload
+
+# [EOF]
diff --git a/sphinx_conf/__init__.py b/sphinx_conf/__init__.py
new file mode 100644
index 0000000..299be16
--- /dev/null
+++ b/sphinx_conf/__init__.py
@@ -0,0 +1,20 @@
+# -*- python -*-
+'''Augment searchpath for import.'''
+
+##-------------------##
+##---] IMPORTS [---##
+##-------------------##
+import sys
+from pathlib import Path
+
+## ---------------------------------------
+## Artificial scope created for local vars
+## ---------------------------------------
+# pylint: disable=invalid-name
+# pylint: disable=using-constant-test
+if True:
+ mod_path = Path('..').resolve().as_posix()
+ if mod_path not in sys.path:
+ sys.path.insert(0, mod_path)
+
+# [EOF]
diff --git a/sphinx_conf/exclude_patterns.py b/sphinx_conf/exclude_patterns.py
new file mode 100644
index 0000000..82bf7c7
--- /dev/null
+++ b/sphinx_conf/exclude_patterns.py
@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# -----------------------------------------------------------------------
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+ '*/LICENSE.md',
+ '*/RELEASE_NOTES.md',
+ '*/vendor',
+ '.DS_Store',
+ 'Thumbs.db',
+ '_build',
+ 'voltha-go/BUILD.md',
+ 'cord-tester/venv_cord',
+ 'cord-tester/docs',
+ 'cord-tester/src',
+ 'cord-tester/README.md',
+ 'cord-tester/cord-robot/README.rst',
+ 'openolt/agent/*',
+ 'repos',
+ 'requirements.txt',
+ 'bbsim/README.md',
+ 'CODE_OF_CONDUCT.md',
+ '*/CODE_OF_CONDUCT.md',
+
+ # Ignore all:
+ 'makefiles',
+ '__pycache__',
+ '**/__pycache__', # generated - faster traversal
+ '.venv',
+ '**/.venv', # external virtual env
+
+ # Revisit: one directory pattern is sufficient.
+ # makefiles/virtualenv.mk normalizes all of this
+ '**/doc_venv',
+ '**/venv_docs',
+ '**/virtualenv',
+ '**/vst_venv',
+]
+
+# [EOF]
diff --git a/sphinx_conf/linkcheck_ignore.py b/sphinx_conf/linkcheck_ignore.py
new file mode 100644
index 0000000..a4f5b8f
--- /dev/null
+++ b/sphinx_conf/linkcheck_ignore.py
@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# -----------------------------------------------------------------------
+
+
+# -- Options for linkcheck ---------------------------------------------------
+# The link checker strips off .md from links and then complains
+linkcheck_ignore=\
+ [
+ r'https://github.com/opencord/voltctl/blob/master/LICENSE',
+ r'https://github.com/ciena/kind-voltha#voltha-up-configuration-options',
+ r'https://www.sphinx-doc.org',
+ r'https://github.com/opencord/bbsim/blob/master/docs/source/DMI_Server_README',
+ r'https://github.com/opencord/voltha-helm-charts/blob/master/README',
+ #
+ r'https://github.com/atomix/atomix/releases/tag/atomix-3.1.9',
+ r'https://github.com/atomix/atomix/releases/tag/atomix-3.1.8',
+ #
+ r'../voltha-helm-charts/README.html',
+ r'https://mvnrepository.com/artifact/org.slf4j/slf4j-api',
+ r'https://mvnrepository.com/artifact/org.mockito/mockito-all',
+ r'https://mvnrepository.com/artifact/com.h3xstream.findsecbugs/findsecbugs-plugin',
+ r'https://mvnrepository.com/artifact/com.github.spotbugs/spotbugs-maven-plugin',
+ ]
+
+linkcheck_ignore.extend([
+
+ # [RELEASE: generated html from rst
+ r'../release_notes/voltha_\d+.\d+.html',
+
+ # [RELEASE: Maven artifacts]
+ r'https://mvnrepository.com/artifact/org.opencord/\S+',
+])
+
+## -----------------------------------------------------------------------
+## https://jira.opencord.org/browse/VOL-5079
+## -----------------------------------------------------------------------
+linkcheck_ignore.extend([
+
+ # (voltha-openonu-adapter-go/docs/PM_Notes: line 287) broken https://github.com/opencord/voltha-protos/blob/master/protos/voltha_protos/extensions.proto#L259 - Anchor 'L259' not found
+ r'https://github.com/opencord/voltha-protos/blob/master/protos/voltha_protos/extensions.proto#L259',
+
+ # (voltha-openonu-adapter-go/docs/PM_Notes: line 311) broken https://github.com/opencord/voltha-protos/blob/master/protos/voltha_protos/extensions.proto#L157 - Anchor 'L157' not found
+ r'https://github.com/opencord/voltha-protos/blob/master/protos/voltha_protos/extensions.proto#L157',
+
+ # (voltha-openonu-adapter-go/docs/ONU_Upgrade_Notes: line 69) broken https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L106 - Anchor 'L106' not found
+ r'https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L106',
+
+ # (voltha-openonu-adapter-go/docs/PM_Notes: line 15) broken https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L61 - Anchor 'L61' not found
+ r'https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L61',
+
+ # (voltha-openonu-adapter-go/docs/ONU_Upgrade_Notes: line 70) broken https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L125 - Anchor 'L125' not found
+ r'https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L125',
+
+ # (voltha-openonu-adapter-go/docs/ONU_Upgrade_Notes: line 71) broken https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L116 - Anchor 'L116' not found
+ r'https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L116',
+ ])
+
+# [SEE ALSO]
+# -----------------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
+
+# [EOF]