VOL-4836 - Cosmetic edits to force a jenkins job.
Makefile
bandwidth-profiles/bandwidth-profiles.rst
-----------------------------------------
o Update document text to force trivial deltas.
o For readability: reformat runon command output to fit 80cpl.
howto/edit_voltha_docs.rst
--------------------------
o Copy in gendocs howto text from repo:infra-docs.
overview/troubleshooting.rst
----------------------------
o Update document text to force trivial deltas.
o Change variable delimiter syntax $()-makefile into ${}-shell since context is the command line.
o cat | grep command can be replaced by a single grep command to avoid the extra process.
testing/index.rst
-----------------
o Minor reformatting for readability.
o Include URLs for both voltha-system-test repository access: gerrit & github.
o Added a "See Also" section to hilight cord-* resources.
Change-Id: Ibf0881a6172abcb866f54dce57ce67a4c29b1bb1
diff --git a/Makefile b/Makefile
index 908e7b2..0787d60 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
# -*- makefile -*-
# -----------------------------------------------------------------------
-# Copyright 2022 Open Networking Foundation
+# Copyright 2022-2023 Open Networking Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -80,7 +80,7 @@
@echo "========================================"
@echo "Applying python virtualenv patches as needed (v3.10+)"
@echo "========================================"
- ./patches/python_310_migration.sh '--venv' "$@" 'apply'
+ ./patches/python_310_migration.sh '--venv' "$@" 'apply'
endif
# automatically reload changes in browser as they're made
@@ -185,7 +185,7 @@
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
# %: $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
-include $(MAKEDIR)/voltha/docs-catchall-targets.mk
+include $(MAKEDIR)/voltha/docs-catchall-targets.mk
$(voltha-docs-catchall): $(VENV_NAME) Makefile | $(OTHER_REPO_DOCS) $(STATIC_DOCS)
@echo " ** CATCHALL: $@"
source $</bin/activate ; set -u ;\
diff --git a/VERSION b/VERSION
index cf686df..b791a2f 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.10.16
+2.10.17
diff --git a/bandwidth-profiles/bandwidth-profiles.rst b/bandwidth-profiles/bandwidth-profiles.rst
index fe78939..6fe7661 100644
--- a/bandwidth-profiles/bandwidth-profiles.rst
+++ b/bandwidth-profiles/bandwidth-profiles.rst
@@ -10,7 +10,7 @@
===========================================
The ONOS Sadis application supports configuration of the bandwidth profiles in two formats, `IETF` and `MEF`.
The values contained are expressed in kilobits/second (kbps).
-THe expectation is that a `Default` meter is always present for workflows that have flow rules installed at port
+The expectation is a `Default` meter will always present for workflows that have flow rules installed at port
startup, such as for EAPOL and DHCP. Meters referred by subscribers must also be present.
The `MEF` Brandwidth Profile format is as follows:
@@ -39,14 +39,18 @@
"gir": 0
}
-Independently of the format the `olt` ONOS apps will generate a meter per bandwidth profile.
+Independent of format the `olt` ONOS apps will generate a meter-per-bandwidth profile.
An example of a meter in ONOS is:
.. code:: bash
onos> meters
- DefaultMeter{device=of:00000a0a0a0a0a0a, cellId=1, appId=DefaultApplicationId{id=411, name=org.opencord.olt}, unit=KB_PER_SEC, isBurst=true, state=ADDED, bands=[DefaultBand{rate=600, burst-size=30, type=DROP, drop-precedence=null}, DefaultBand{rate=101000, burst-size=60, type=DROP, drop-precedence=null}, DefaultBand{rate=100000, burst-size=0, type=DROP, drop-precedence=null}], annotations={}}
+ DefaultMeter{device=of:00000a0a0a0a0a0a, cellId=1, appId=DefaultApplicationId{id=411, name=org.opencord.olt},
+ unit=KB_PER_SEC, isBurst=true, state=ADDED,
+ bands=[DefaultBand{rate=600, burst-size=30, type=DROP, drop-precedence=null},
+ DefaultBand{rate=101000, burst-size=60, type=DROP, drop-precedence=null},
+ DefaultBand{rate=100000, burst-size=0, type=DROP, drop-precedence=null}], annotations={}}
note the different bands that map to the values of the `Default` bandwidth profile as well.
The number of bands in the meter are based on the BW profile. If BW profile has only PIR value, then there is only
@@ -107,7 +111,9 @@
.. code:: bash
- ADDED, bytes=0, packets=0, table=0, priority=10000, selector=[IN_PORT:256, ETH_TYPE:eapol], treatment=[immediate=[OUTPUT:CONTROLLER, VLAN_PUSH:vlan, VLAN_ID:4091], meter=METER:1, metadata=METADATA:ffb004000000001/0]
+ ADDED, bytes=0, packets=0, table=0, priority=10000, selector=[IN_PORT:256, ETH_TYPE:eapol],
+ treatment=[immediate=[OUTPUT:CONTROLLER, VLAN_PUSH:vlan, VLAN_ID:4091], meter=METER:1,
+ metadata=METADATA:ffb004000000001/0]
TCONT Mapping
diff --git a/howto/edit_voltha_docs.rst b/howto/edit_voltha_docs.rst
index 17beb08..fcbf98e 100644
--- a/howto/edit_voltha_docs.rst
+++ b/howto/edit_voltha_docs.rst
@@ -14,6 +14,39 @@
- :vol-ger:`voltha-docs`
- :vol-git:`voltha-docs`
+Documentation Guide
+===================
+
+Building the Docs
+"""""""""""""""""
+
+Building requires python, creates a virtualenv (``doc_venv``) which has all the
+necessary tools.
+
+Run ``make html`` to generate html documentation in ``_build/html``.
+
+Run ``make reload`` to get a live reload in your browser (refreshes on document
+save).
+
+Run ``make latexpdf`` to generate html documentation in ``_build/latex``.
+Requires that you have a recent LaTeX installation and ``latexmk`` installed
+
+Writing Docs
+""""""""""""
+
+Docs written using sphinx: http://www.sphinx-doc.org
+
+Documentation is done in reStructuredText or Markdown, but only ``.rst`` files
+can contain embedded diagrams.
+
+Guides for RST:
+
+- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+- http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+
+RST has multiple heading formats possible, the ones we're using are in the
+order for the HTML h1-h5: ``=``, ``-`` ``"``, ``'``, ``^``.
+
Checkout, modify and test
"""""""""""""""""""""""""
diff --git a/overview/troubleshooting.rst b/overview/troubleshooting.rst
index 1bd2fc9..3ff63f1 100644
--- a/overview/troubleshooting.rst
+++ b/overview/troubleshooting.rst
@@ -17,13 +17,17 @@
-------------------------------
Given that ``VOLTHA`` is a collection of microservices we strongly suggest the usage of a log aggregator like
-`stern <https://github.com/stern/stern>`_ installed. You can then aggregate logs from multiple containers in
+`stern <https://github.com/stern/stern>`_. Stern is able to aggregate logs from multiple containers in
a simple way, for example to track all the ``packet-ins`` and ``packet-outs``:
.. code:: bash
+ # Capture to a file
$ stern -n voltha "voltha|adapter" | grep -E "packet-out|packet-in" > packets.trace
+ # Live streaming packet capture using the tee command:
+ $ stern -n voltha "voltha|adapter" | grep -E "packet-out|packet-in" | tee packets.trace
+
Once you have captured the packets you need, you can see them in wireshark by transforming the logs with:
.. code:: bash
@@ -34,9 +38,9 @@
Or you can decode a single packet using this online tool: `https://hpd.gasmi.net <https://hpd.gasmi.net>`_
-To get all the EAPOL packets: ``cat packets.trace | grep 888e``
+To get all the EAPOL packets: ``grep -e '888e' packets.trace``
-or if you have `hl <https://github.com/mbornet-hl/hl>`__ installed you can highlight with:
+or if you have the colorization program `hl <https://github.com/mbornet-hl/hl>`__ installed you can highlight with:
.. code:: bash
@@ -60,12 +64,15 @@
.. code:: bash
- mkdir -p $(HOME)/.local/lib/wireshark/plugins
- cd $(HOME)/.local/lib/wireshark/plugins
+ mkdir -p "${HOME}/.local/lib/wireshark/plugins"
+ cd "${HOME}/.local/lib/wireshark/plugins"
wget "https://wiki.wireshark.org/Contrib?action=AttachFile&do=get&target=omci.lua"
wget "https://wiki.wireshark.org/Contrib?action=AttachFile&do=get&target=BinDecHex.lua"
-IMPORTANT - Apply `this <https://ask.wireshark.org/question/4557/bindechexlua-error-bad-argument-to-module-packageseeall/?answer=4573#post-id-4573>`_ fix to BinDecHex.lua.
+- IMPORTANT - Apply `this <https://ask.wireshark.org/question/4557/bindechexlua-error-bad-argument-to-module-packageseeall/?answer=4573#post-id-4573>`_ fix to BinDecHex.lua.
+
+- TODO NOTE - The BinDecHex.lua thread is 4 years old, is the patch still
+ required or has it been incorporated into the code base ?
To capture the OMCI packets for all ONUs:
diff --git a/testing/index.rst b/testing/index.rst
index 0e457af..2124721 100644
--- a/testing/index.rst
+++ b/testing/index.rst
@@ -2,10 +2,14 @@
===========================
Below are links to the documentation generated by ``robot.libdoc`` from the
-Robot resources in the `voltha-system-tests
-<https://github.com/opencord/voltha-system-tests>`_ repository. These files
-can also be generated locally by checking out the repo and running **make
-gendocs**.
+Robot resources in the voltha-system-tests repository.
+
+| These files can also be generated locally by checking out the repo and running:
+
+- % **make gendocs**
+
+ - `voltha-system-tests (gerrit) <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests>`_
+ - `voltha-system-tests (github) <https://github.com/opencord/voltha-system-tests>`_
Libraries
---------
@@ -65,9 +69,9 @@
Below are links to the documentation generated by ``robot.libdoc`` for the
Robot resources in the `cord-robot <https://pypi.org/project/cord-robot/>`_
-Python package These files can also be generated locally by checking out the
-`cord-tester <https://github.com/opencord/cord-tester>`_ repo and running
-**make gendocs**.
+Python package.
+
+| These files can also be generated locally by checking out the `cord-tester <https://github.com/opencord/cord-tester>`_ repo and running **make gendocs**.
Libraries
---------
@@ -82,3 +86,9 @@
- `utils.resource <../_static/cord-tester/cord-robot/CORDRobot/rf-resources/utils.html>`_
- `CORDDictUtils.py <../_static/cord-tester/cord-robot/CORDRobot/CORDDictUtils.html>`_
- `testCaseUtils.py <../_static/cord-tester/cord-robot/CORDRobot/testCaseUtils.html>`_
+
+See Also
+--------
+
+- `cord-robot <https://pypi.org/project/cord-robot/>`_
+- `cord-tester <https://github.com/opencord/cord-tester>`_