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
+