Add makefile targets for doc8 lint, fix formatting/spelling issues
Change-Id: I0f45ffe0ba94fab89f9b38c9b73ed7b9091f1795
diff --git a/Makefile b/Makefile
index 7d9dc5c..05ed311 100644
--- a/Makefile
+++ b/Makefile
@@ -90,11 +90,14 @@
docker-run-dev: # @HELP Runs the container locally (intended for development purposes, not in detached mode)
docker run ${DOCKER_PORTS} --privileged --rm --name bbsim ${DOCKER_REGISTRY}${DOCKER_REPOSITORY}bbsim:${DOCKER_TAG} /app/bbsim ${DOCKER_RUN_ARGS}
-.PHONY: docs
+.PHONY: docs docs-lint
docs: swagger # @HELP Generate docs and opens them in the browser
- cd docs; make doc_venv; make html; cd -
+ make -C docs html
@echo -e "\nBBSim documentation generated in file://${PWD}/docs/build/html/index.html"
+docs-lint:
+ make -C docs lint
+
# Release related items
# Generates binaries in $RELEASE_DIR with name $RELEASE_NAME-$RELEASE_OS_ARCH
# Inspired by: https://github.com/kubernetes/minikube/releases
diff --git a/docs/Makefile b/docs/Makefile
index 379e0e2..13176dc 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,5 +1,7 @@
# Minimal makefile for Sphinx documentation
-#
+
+# use bash safe mode, fail quickly
+SHELL = bash -e -o pipefail
# You can set these variables from the command line.
SPHINXOPTS =
@@ -7,19 +9,32 @@
SOURCEDIR = source
BUILDDIR = build
-# Put it first so that "make" without argument is like "make help".
-help:
- @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.PHONY: help Makefile lint
-.PHONY: help Makefile
+# Put it first so that "make" without argument is like "make help".
+help: doc_venv
+ source $</bin/activate ; set -u ;\
+ $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
doc_venv:
- virtualenv doc_venv ;\
- source ./doc_venv/bin/activate ;\
+ virtualenv $@ ;\
+ source $@/bin/activate ;\
pip install livereload ;\
pip install -r requirements.txt
+lint: doc8
+
+doc8: doc_venv
+ source $</bin/activate ; set -u ;\
+ doc8 --max-line-length 119 \
+ $$(find . -name \*.rst ! -path "*doc_venv*")
+
+clean:
+ rm -rf doc_venv build
+
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
- @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+%: doc_venv Makefile
+ source $</bin/activate ; set -u ;\
+ $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 2fdbc75..cc4662f 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -4,7 +4,7 @@
livereload~=2.6.1
nwdiag~=1.0.4
recommonmark~=0.6.0
-rstcheck~=3.3.1
+doc8~=0.8.0
seqdiag~=0.9.6
sphinx-reload~=0.2.0
sphinx-rtd-theme~=0.4.3
@@ -12,4 +12,4 @@
sphinxcontrib-blockdiag~=1.5.5
sphinxcontrib-nwdiag~=0.9.5
sphinxcontrib-seqdiag~=0.8.5
-sphinxcontrib-openapi~=0.5.0
\ No newline at end of file
+sphinxcontrib-openapi~=0.5.0
diff --git a/docs/source/api.rst b/docs/source/api.rst
index 37c653b..466e3e1 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -3,15 +3,24 @@
BBSimAPI
--------
-BBSim exposes gRPC and REST APIs for external control of the simulated OLT. The API is defined using the protocol buffer specification in `api/bbsim/bbsim.proto`.
-By default, the gRPC server is started on port 50070 and the REST server is started on port 50071. The following endpoints are currently defined:
+BBSim exposes gRPC and REST APIs for external control of the simulated OLT. The
+API is defined using the protocol buffer specification in
+`api/bbsim/bbsim.proto`.
+
+By default, the gRPC server is started on port 50070 and the REST server is
+started on port 50071. The following endpoints are currently defined:
.. openapi:: ../swagger/bbsim/bbsim.swagger.json
Legacy BBSimAPI
---------------
-Additionally, a legacy API is available, defined in `api/legacy/bbsim.proto`. This API is deprecated and will be removed once BBSim reaches feature parity with the legacz version.
-By default, the legacy gRPC server is started on port 50072 and the corresponding REST server is started on port 50073. The following endpoints are currently defined:
+Additionally, a legacy API is available, defined in `api/legacy/bbsim.proto`.
+This API is deprecated and will be removed once BBSim reaches feature parity
+with the legacy version.
+
+By default, the legacy gRPC server is started on port 50072 and the
+corresponding REST server is started on port 50073. The following endpoints are
+currently defined:
.. openapi:: ../swagger/legacy/bbsim.swagger.json
diff --git a/docs/source/bbr.rst b/docs/source/bbr.rst
index 88856bd..dfdaa39 100644
--- a/docs/source/bbr.rst
+++ b/docs/source/bbr.rst
@@ -7,7 +7,7 @@
is responsible to emulate ONOS and VOLTHA in order to quickly reply to
any message that BBSim sends.
-Here is a graph of the measuraments of BBSim performance captured over
+Here is a graph of the measurements of BBSim performance captured over
10 runs with different PON Layout
.. figure:: ./_static/bbr_runs.png
@@ -47,7 +47,7 @@
$ ./bbr -onu 16 -pon 4
``bbr`` will run to completion and output the time it took to bring all
-the ONUs to the ``dhcp_ack`` state. If the ``bbr`` process doesn’t exit,
+the ONUs to the ``dhcp_ack`` state. If the ``bbr`` process doesn't exit,
it means something went wrong.
Debugging and issue reporting
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 4b0af7d..7c04a68 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -22,8 +22,8 @@
Quickstart
----------
-BBSim (a.k.a. BroadBand Simulator) is a tool designed to emulate an `Openolt <https://github.com/opencord/openolt>`_
-compatible device.
+BBSim (a.k.a. BroadBand Simulator) is a tool designed to emulate an `Openolt
+<https://github.com/opencord/openolt>`_ compatible device.
In order to use BBSim you need to have:
@@ -31,7 +31,8 @@
- helm
- a working installation of VOLTHA
-We strongly recommend the utilization of `kind-voltha <https://github.com/ciena/kind-voltha>`_ to setup such environment.
+We strongly recommend the utilization of `kind-voltha
+<https://github.com/ciena/kind-voltha>`_ to setup such environment.
Installation
------------
@@ -48,7 +49,8 @@
helm install -n bbsim cord/bbsim --set images.bbsim.repository=bbsim --set images.bbsim.tag=candidate --set images.bbsim.pullPolicy=Never
-The BBSim installation can be customized to emulate multiple ONUs and multiple PON Ports:
+The BBSim installation can be customized to emulate multiple ONUs and multiple
+PON Ports:
.. code:: bash
@@ -84,7 +86,8 @@
BBSim startup options
---------------------
-``BBSim`` supports a series of options that can be set at startup, you can see the list via ``./bbsim --help``
+``BBSim`` supports a series of options that can be set at startup, you can see
+the list via ``./bbsim --help``
.. code:: bash
@@ -115,20 +118,27 @@
-s_tag int
S-Tag value (default 900)
-``BBSim`` also looks for a configuration file in ``configs/bbsim.yaml`` from which it reads a number of default settings. The command line options listed above override the corresponding coniguration file settings. A sample configuration file is given below:
+``BBSim`` also looks for a configuration file in ``configs/bbsim.yaml`` from
+which it reads a number of default settings. The command line options listed
+above override the corresponding configuration file settings. A sample
+configuration file is given below:
.. literalinclude:: ../../configs/bbsim.yaml
Using the BBSim Sadis server in ONOS
------------------------------------
-BBSim provides a simple server for testing with the ONOS Sadis app. The server listens on port 50074 by default and provides the endpoints ``subscribers/<id>`` and ``bandwidthprofiles/<id>``.
+BBSim provides a simple server for testing with the ONOS Sadis app. The server
+listens on port 50074 by default and provides the endpoints
+``subscribers/<id>`` and ``bandwidthprofiles/<id>``.
-To configure ONOS to use the BBSim ``Sadis`` server endpoints, the Sadis app must use be configured as follows (see ``examples/sadis-in-bbsim.json``):
+To configure ONOS to use the BBSim ``Sadis`` server endpoints, the Sadis app
+must use be configured as follows (see ``examples/sadis-in-bbsim.json``):
.. literalinclude:: ../../examples/sadis-in-bbsim.json
-This base configuration may also be obtained directly from the BBSim Sadis server:
+This base configuration may also be obtained directly from the BBSim Sadis
+server:
.. code:: bash
@@ -151,4 +161,3 @@
curl --user karaf:karaf http://localhost:8181/onos/v1/network/configuration/apps/org.opencord.sadis
In ONOS subscriber information can be queried using ``sadis <id>``.
-
diff --git a/docs/source/olt-state-machine.rst b/docs/source/olt-state-machine.rst
index d92d6f8..e40774a 100644
--- a/docs/source/olt-state-machine.rst
+++ b/docs/source/olt-state-machine.rst
@@ -39,4 +39,5 @@
created -> initialized -> enabled -> disabled -> deleted
disabled -> enabled
deleted -> initialized
- }
\ No newline at end of file
+ }
+
diff --git a/docs/source/onu-state-machine.rst b/docs/source/onu-state-machine.rst
index 3af8f5a..2815a64 100644
--- a/docs/source/onu-state-machine.rst
+++ b/docs/source/onu-state-machine.rst
@@ -98,10 +98,10 @@
- Notes
* - shutdown
- disable
- - Emulates a devide shutdown. Sends a ``DyingGaspInd`` and then an ``OnuIndication{OperState: 'down'}``
+ - Emulates a device shutdown. Sends a ``DyingGaspInd`` and then an ``OnuIndication{OperState: 'down'}``
* - poweron
- enable
- - Emulates a devide power on. Sends a ``OnuDiscInd`` and then an ``OnuIndication{OperState: 'up'}``
+ - Emulates a device power on. Sends a ``OnuDiscInd`` and then an ``OnuIndication{OperState: 'up'}``
* - auth_restart
- start_auth
- Forces the ONU to send a new ``EapStart`` packet.
@@ -133,7 +133,7 @@
created [peripheries=2]
initialized
discovered
- {
+ {
rank=same
enabled
disabled [fillcolor="#f9d6ff"]
@@ -147,13 +147,13 @@
style=rounded
style=dotted
node [fillcolor="#e6ffc2"]
-
+
eapol_flow_received
auth_started
eap_start_sent
eap_response_identity_sent
eap_response_challenge_sent
- {
+ {
rank=same
eap_response_success_received
auth_failed
@@ -177,16 +177,16 @@
node [fillcolor="#fffacc"]
style=rounded
style=dotted
-
+
dhcp_started
dhcp_discovery_sent
dhcp_request_sent
- {
+ {
rank=same
dhcp_ack_received
dhcp_failed
}
-
+
dhcp_started -> dhcp_discovery_sent -> dhcp_request_sent -> dhcp_ack_received
dhcp_started -> dhcp_failed
dhcp_discovery_sent -> dhcp_failed
@@ -210,4 +210,4 @@
dhcp_ack_received -> disabled
dhcp_failed -> disabled
disabled -> enabled
- }
\ No newline at end of file
+ }
diff --git a/docs/source/operations.rst b/docs/source/operations.rst
index 0879a84..cc977f3 100644
--- a/docs/source/operations.rst
+++ b/docs/source/operations.rst
@@ -60,4 +60,5 @@
get
list
poweron
- shutdown
\ No newline at end of file
+ shutdown
+