Cleanup
- Use doc8 to check rst files
- Add spellcheck and VOLTHA-specific dictionary, fix spelling
- Other formatting and content fixes
Change-Id: I1eea3ab6eba4ec34af0788a681f1e8cd258ea988
diff --git a/.rstcheck.cfg b/.rstcheck.cfg
deleted file mode 100644
index c758ac4..0000000
--- a/.rstcheck.cfg
+++ /dev/null
@@ -1,3 +0,0 @@
-[rstcheck]
-ignore_directives=code
-report=warning
\ No newline at end of file
diff --git a/Makefile b/Makefile
index 34575c2..349938d 100644
--- a/Makefile
+++ b/Makefile
@@ -11,7 +11,7 @@
# Put it first so that "make" without argument is like "make help".
help: doc_venv
- source ./doc_venv/bin/activate ;\
+ source $</bin/activate ; set -u ;\
$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help test lint reload Makefile
@@ -19,25 +19,24 @@
# Create the virtualenv with all the tools installed
doc_venv:
virtualenv doc_venv ;\
- source ./doc_venv/bin/activate ;\
+ source $@/bin/activate ;\
pip install livereload ;\
pip install -r requirements.txt
# automatically reload changes in browser as they're made
reload: doc_venv
- source ./doc_venv/bin/activate ;\
- set -u ;\
+ source $</bin/activate ; set -u ;\
sphinx-reload $(SOURCEDIR)
# lint and link verification. linkcheck is part of sphinx
test: lint linkcheck
-lint: rst-lint
+lint: doc8
-rst-lint: doc_venv | $(OTHER_REPO_DOCS)
- source ./doc_venv/bin/activate ;\
- set -u ;\
- rstcheck -r $$(find . -name \*.rst ! -path "*doc_venv*" ! -path "./repos/*" ! -path "*vendor*")
+doc8: doc_venv | $(OTHER_REPO_DOCS)
+ source $</bin/activate ; set -u ;\
+ doc8 --max-line-length 119 \
+ $$(find . -name \*.rst ! -path "*doc_venv*" ! -path "*vendor*")
# markdown linting
# currently not enabled, should be added to lint target
@@ -105,7 +104,7 @@
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile doc_venv | $(OTHER_REPO_DOCS)
- source ./doc_venv/bin/activate ;\
+%: doc_venv Makefile | $(OTHER_REPO_DOCS)
+ source $</bin/activate ; set -u ;\
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/conf.py b/conf.py
index ce7ea51..8f6ce2d 100644
--- a/conf.py
+++ b/conf.py
@@ -60,6 +60,7 @@
'sphinxcontrib.packetdiag',
'sphinxcontrib.rackdiag',
'sphinxcontrib.seqdiag',
+ 'sphinxcontrib.spelling',
# 'sphinxcontrib.golangdomain',
# 'autoapi.extension',
]
@@ -76,6 +77,9 @@
# 'voltha-go/rw_core/utils',
# ]
+# Text files with lists of words that shouldn't fail the spellchecker:
+spelling_word_list_filename=['dict.txt', ]
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/dict.txt b/dict.txt
new file mode 100644
index 0000000..faa2c0a
--- /dev/null
+++ b/dict.txt
@@ -0,0 +1,98 @@
+Apps
+Autocomplete
+Broadcom
+Docsis
+Edgecore
+GOPATH
+Golang
+Graphviz
+IDE
+Indices
+Inline
+Kubernetes
+Ponsim
+Preprovision
+Protobuf
+Protos
+Pypi
+Quickstart
+README
+Sadis
+Ubuntu
+Username
+Voltha
+Wireshark
+aaa
+ack
+aggregator
+amd
+app
+apps
+auth
+autocomplete
+backhaul
+bbsim
+bbsimctl
+config
+dep
+dhcp
+dhcpl
+dockerhub
+eap
+eapol
+etcd
+filesystem
+gRPC
+gerrit
+github
+golang
+gz
+https
+internet
+io
+kafka
+kubernetes
+lifecycle
+localhost
+lossofomcichannel
+lossofploam
+macports
+md
+microservices
+ofagent
+olt
+online
+onos
+onu
+opencord
+openolt
+openonu
+oper
+org
+patchset
+poweron
+ppa
+preprovision
+protobuf
+protobufs
+protoc
+protos
+quickstart
+reStructuredText
+repo
+repos
+rst
+rw
+sadis
+signaldegrade
+src
+toolset
+vendored
+virtualenv
+virtualized
+voltctl
+voltha
+wiki
+wireshark
+xDSL
+zookeeper
diff --git a/index.rst b/index.rst
index bd1a3da..dc0c21e 100644
--- a/index.rst
+++ b/index.rst
@@ -10,6 +10,7 @@
:caption: Overview
overview/deploy-physical.rst
+ overview/physical_layout.rst
overview/deploy-virtual.rst
overview/development_loop.rst
overview/troubleshooting.rst
@@ -23,9 +24,6 @@
voltha-go/README.md
voltha-go/quickstart.md
voltha-go/BUILD.md
- voltha-go/python/adapters/BUILD_ENV.md
- voltha-go/python/adapters/README.md
- voltha-go/python/cli/docs/README.md
.. toctree::
:maxdepth: 1
diff --git a/overview/deploy-physical.rst b/overview/deploy-physical.rst
index 510c9ae..1758f03 100644
--- a/overview/deploy-physical.rst
+++ b/overview/deploy-physical.rst
@@ -6,7 +6,8 @@
Quickstart
----------
-The quickstart assumes you POD is already correctly cabled, if not you can refer to :ref:`Physical_Layout`
+The quickstart assumes you POD is already correctly cabled, if not you can
+refer to :ref:`Physical_Layout`
Requires:
@@ -14,7 +15,8 @@
- `kind-voltha <https://github.com/ciena/kind-voltha>`_ cloned on your machine
-Enter the ``kind-voltha`` directory and execute this command (``kubectl`` must be installed and poiting to your cluster):
+Enter the ``kind-voltha`` directory and execute this command (``kubectl`` must
+be installed and pointing to your cluster):
.. code:: bash
@@ -26,13 +28,13 @@
TLDR;
-----
-Below are the complete steps to install a physical cluster. It assumes ``kubectl`` and ``helm`` commands are already
-available.
+Below are the complete steps to install a physical cluster. It assumes
+``kubectl`` and ``helm`` commands are already available.
Configure Helm
--------------
-Helm provide a capabilty to install and manage Kubernetes applications.
+Helm provide a capability to install and manage Kubernetes applications.
VOLTHA’s default deployment mechanism utilized Helm. Before Helm can be
used to deploy VOLTHA it must be initialized and the repositories that
container the artifacts required to deploy VOLTHA must be added to Helm.
@@ -52,7 +54,7 @@
ETCD Operator is a utility that allows applications to create and manage
ETCD key/value clusters as Kubernetes resources. VOLTHA utilizes this
utility to create its key/value store. *NOTE: it is not required that
-VOLTHA create its own datastore as VOLTHA can utilize and existing
+VOLTHA create its own datastore as VOLTHA can utilize an existing
datastore, but for this example VOLTHA will creates its own datastore*
.. code:: bash
@@ -62,7 +64,7 @@
Wait for operator pods
~~~~~~~~~~~~~~~~~~~~~~
-Before continuing the Kubernetes pods associated with ETCD Operator must
+Before continuing, the Kubernetes pods associated with ETCD Operator must
be in the ``Running`` state.
.. code:: bash
@@ -85,21 +87,20 @@
---------------------
To demonstrate the capability of VOLTHA other *partner* applications are
-required, such as ONOS. The followins sections describe how to install
+required, such as ONOS. The following sections describe how to install
and configure these *partner* applications.
-*NOTE: It is important to start ONOS before VOLTHA as if they are
-started in the reverse order ofagent sometimes does not connect to the
-SDN
+*NOTE: It is important to start ONOS before VOLTHA as if they are started in
+the reverse order the ``ofagent`` sometimes does not connect to the SDN
controller*\ `VOL-1764 <https://jira.opencord.org/browse/VOL-1764>`__.
ONOS (OpenFlow Controller)
~~~~~~~~~~~~~~~~~~~~~~~~~~
-VOLTHA exposes an OLT and its connected ONUs as an OpenFlow switch. To
-control that virtual OpenFlow switch an OpenFlow controller is required.
-For most VOLTHA deployments that controller is ONOS with a set of ONOS
-applications installed. To install ONOS use the following Helm command:
+VOLTHA exposes an OLT and its connected ONUs as an OpenFlow switch. To control
+that virtual OpenFlow switch an OpenFlow controller is required. For most
+VOLTHA deployments that controller is ONOS, with a set of ONOS applications
+installed. To install ONOS use the following Helm command:
.. code:: bash
@@ -146,7 +147,7 @@
The ONOS applications leverage the *Subscriber and Device Information
Store (SADIS)* when processing EAPOL and DHCP packets from VOLTHA
-controlled devices. In order for VOLTHA to function propperly SADIS
+controlled devices. In order for VOLTHA to function properly, SADIS
entries must be configured into ONOS.
The repository contains two example SADIS configuration that can be used
@@ -179,7 +180,7 @@
--namespace voltha --name voltha onf/voltha
During the install of the core VOLTHA components some containers may
-“crash” or restart. This is normal as there are dependencies, such as
+"crash" or restart. This is normal as there are dependencies, such as
the read/write cores cannot start until the ETCD cluster is established
and so they crash until the ETCD cluster is operational. Eventually all
the containers should be in a ``Running`` state as queried by the
@@ -225,7 +226,7 @@
Exposing VOLTHA Services
------------------------
-At this point VOLTHA is deployed and from within the Kubernetes cluster
+At this point VOLTHA is deployed, and from within the Kubernetes cluster
the VOLTHA services can be reached. However, from outside the Kubernetes
cluster the services cannot be reached.
@@ -244,7 +245,7 @@
Configure ``voltctl`` to Connect to VOLTHA
------------------------------------------
-In order for ``voltctl`` to connect to the VOLTHA instance deplpoyed in
+In order for ``voltctl`` to connect to the VOLTHA instance deployed in
the Kubernetes cluster it must know which IP address and port to use.
This configuration can be persisted to a local config file using the
following commands.
@@ -255,15 +256,11 @@
voltctl -a v2 -s localhost:55555 config > $HOME/.volt/config
To test the connectivity you can query the version of the VOLTHA client
-and server.
-
-.. code:: bash
+and server::
voltctl version
-The output should be similar to the following
-
-.. code:: bash
+The output should be similar to the following::
Client:
Version unknown-version
@@ -279,4 +276,4 @@
Vcs feference: 28f120f1f4751284cadccf73f2f559ce838dd0a5
Vcs dirty: false
Built: 2019-06-26T16:58:22Z
- OS/Arch: linux/amd64
\ No newline at end of file
+ OS/Arch: linux/amd64
diff --git a/overview/deploy-virtual.rst b/overview/deploy-virtual.rst
index dfec06d..6e4445f 100644
--- a/overview/deploy-virtual.rst
+++ b/overview/deploy-virtual.rst
@@ -26,7 +26,7 @@
-------------------------
Kind provides a command line control tool to easily create Kubernetes
-clusters using just a basic Docker envionrment. The following commands
+clusters using just a basic Docker environment. The following commands
will create the desired deployment of Kubernetes and then configure your
local copy of ``kubectl`` to connect to this cluster.
@@ -39,7 +39,7 @@
Initialize Helm
---------------
-Helm provide a capabilty to install and manage Kubernetes applications.
+Helm provide a capability to install and manage Kubernetes applications.
VOLTHA’s default deployment mechanism utilized Helm. Before Helm can be
used to deploy VOLTHA it must be initialized and the repositories that
container the artifacts required to deploy VOLTHA must be added to Helm.
@@ -58,7 +58,8 @@
kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
kubectl patch deploy --namespace kube-system tiller-deploy -p '{"spec":{"template":{"spec":{"serviceAccount":"tiller"}}}}'
-From this point follow the :ref:`physical VOLTHA POD installation instructions <installation_steps>`. Come back here once done.
+From this point follow the :ref:`physical VOLTHA POD installation instructions
+<installation_steps>`. Come back here once done.
Install BBSIM (Broad Band OLT/ONU Simulator)
--------------------------------------------
@@ -82,4 +83,4 @@
.. code:: bash
- voltctl device enable $(voltctl device list --filter Type~openolt -q)
\ No newline at end of file
+ voltctl device enable $(voltctl device list --filter Type~openolt -q)
diff --git a/overview/development_loop.rst b/overview/development_loop.rst
index 581a1e7..34ab2d7 100644
--- a/overview/development_loop.rst
+++ b/overview/development_loop.rst
@@ -50,4 +50,5 @@
.. code:: bash
- $ DEPLOY_K8S=no ./voltha down && DEPLOY_K8S=no EXTRA_HELM_FLAGS="-f dev-values.yaml" ./voltha up
\ No newline at end of file
+ $ DEPLOY_K8S=no ./voltha down && DEPLOY_K8S=no EXTRA_HELM_FLAGS="-f dev-values.yaml" ./voltha up
+
diff --git a/overview/physical_layout.rst b/overview/physical_layout.rst
index 978be8f..850a64a 100644
--- a/overview/physical_layout.rst
+++ b/overview/physical_layout.rst
@@ -5,5 +5,7 @@
Coming Soon.
-For the time being you can refer to the `SEBA LAB Setup guide <https://guide.opencord.org/profiles/seba/lab-setup.html#configuring-a-lab-setup>`_,
-just remember that the ``AggSwitch`` is optional in a VOLTHA deployment.
\ No newline at end of file
+For the time being you can refer to the `SEBA LAB Setup guide
+<https://guide.opencord.org/profiles/seba/lab-setup.html#configuring-a-lab-setup>`_,
+just remember that the ``AggSwitch`` is optional in a VOLTHA deployment.
+
diff --git a/readme.rst b/readme.rst
index d73f458..a0acf09 100644
--- a/readme.rst
+++ b/readme.rst
@@ -17,6 +17,10 @@
in Jenkins to validate the documentation, so please do this before you create a
patchset.
+To check spelling, run ``make spelling``. If there are additional words that
+are correctly spelled but not in the dictionary (acronyms, trademarks, etc.)
+please add them to the ``dict.txt`` file.
+
Writing Docs
------------
diff --git a/requirements.txt b/requirements.txt
index 340b706..4f5937c 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,17 +1,18 @@
Sphinx~=1.8.5
actdiag~=0.5.4
blockdiag~=1.5.4
+doc8~=0.8.0
livereload~=2.6.1
nwdiag~=1.0.4
recommonmark~=0.6.0
-rstcheck~=3.3.1
seqdiag~=0.9.6
sphinx-reload~=0.2.0
sphinx-rtd-theme~=0.4.3
sphinxcontrib-actdiag~=0.8.5
sphinxcontrib-blockdiag~=1.5.5
sphinxcontrib-nwdiag~=0.9.5
-sphinxcontrib-seqdiag~=0.8.5
sphinxcontrib-openapi~=0.5.0
+sphinxcontrib-seqdiag~=0.8.5
+sphinxcontrib-spelling~=4.2.1
# sphinx-autoapi~=1.2.1
# sphinxcontrib-golangdomain