From 340c15c6ed34ce60c821b5260fec3eb11d65dcb7 Mon Sep 17 00:00:00 2001 From: Paul Vinciguerra Date: Tue, 5 Nov 2019 15:34:36 -0500 Subject: docs: add spellcheck to 'make docs' sphinx docs The CI gate will fail if there are typos in the docs. writing output... [ 21%] events/Summits/OpensourceSummit... writing output... [ 22%] events/Summits/UKNO/2017_04_30_... featuresbyrelease/vpp16.06.rst:34:Rasberry:vpp16.06 writing output... [100%] usecases/vppinazure Spelling checker messages written to /vpp/docs/_build/html/output.txt Warning, treated as error: Found 1 misspelled words Makefile:31: recipe for target 'html' failed make[1]: *** [html] Error 2 make[1]: Leaving directory '/vpp/docs' If you introduce a term that is not recognized, please add it to custom dictionary at docs/spelling_wordlist.txt. Type: feature Change-Id: Id49be4fbee617f544f1ab8e78e7de8a4df36448b Signed-off-by: Paul Vinciguerra --- docs/Makefile | 26 +++++++++ docs/conf.py | 15 +++-- docs/etc/requirements.txt | 1 + docs/featuresbyrelease/vpp16.06.rst | 70 ++++++++++++------------ docs/featuresbyrelease/vpp17.01.rst | 2 +- docs/featuresbyrelease/vpp17.04.rst | 4 +- docs/featuresbyrelease/vpp17.07.rst | 6 +- docs/featuresbyrelease/vpp18.07.rst | 2 +- docs/featuresbyrelease/vpp18.10.rst | 4 +- docs/gettingstarted/developers/fib20/routes.rst | 4 +- docs/gettingstarted/developers/fib20/tunnels.rst | 2 +- docs/gettingstarted/developers/metadata.md | 4 +- docs/gettingstarted/developers/vlib.md | 2 +- docs/reference/vppvagrant/VagrantVMSetup.rst | 2 +- docs/usecases/ConnectingVPC.rst | 2 +- docs/usecases/contiv/K8s_Overview.md | 2 +- docs/usecases/simpleperf/iperf3.rst | 2 +- src/plugins/quic/quic_plugin.rst | 2 +- 18 files changed, 92 insertions(+), 60 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 430877792a8..a67b28a3f1b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,5 +1,16 @@ # Minimal makefile for Sphinx documentation # +# We support MacOS for docs generation +ifeq ($(shell uname),Darwin) +OS_ID = darwin +endif + +# Work out the OS if we haven't already +OS_ID ?= $(shell grep '^ID=' /etc/os-release | cut -f2- -d= | sed -e 's/\"//g') + +DOC_DEB_DEPENDS = enchant libenchant-dev +DOC_RPM_DEPENDS = enchant libenchant-dev + # You can set these variables from the command line. SPHINXOPTS = @@ -17,4 +28,19 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile + @echo "Checking whether dependencies for Docs are installed..." +ifeq ($(OS_ID),ubuntu) + @set -e; inst=; \ + for i in $(DOC_DEB_DEPENDS); do \ + dpkg-query --show $$i >/dev/null 2>&1 || inst="$$inst $$i"; \ + done; \ + if [ "$$inst" ]; then \ + sudo apt-get update; \ + sudo apt-get $(CONFIRM) $(FORCE) install $$inst; \ + fi +else ifneq ("$(wildcard /etc/redhat-release)","") + @sudo yum install $(CONFIRM) $(DOC_RPM_DEPENDS) +endif + @python3 -m pip install sphinxcontrib-spelling + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -W -b spelling $(O) @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py index e9d7bb88f95..eb66cb38ac0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,8 +41,9 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'recommonmark', -] + 'sphinxcontrib.spelling'] +spelling_word_list_filename = 'spelling_wordlist.txt' # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -52,7 +53,7 @@ templates_path = ['_templates'] source_suffix = { '.rst': 'restructuredtext', '.md': 'markdown' - } +} # The master toctree document. master_doc = 'index' @@ -106,6 +107,7 @@ html_logo = '_static/fd-io_red_white.png' # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] + def setup(app): app.add_stylesheet('css/rules.css') @@ -150,7 +152,8 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'Vector Packet Processor.tex', u'Vector Packet Processor Documentation', + (master_doc, 'Vector Packet Processor.tex', + u'Vector Packet Processor Documentation', u'John DeNisco', 'manual'), ] @@ -160,7 +163,8 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'Vector Packet Processor', u'Vector Packet Processor Documentation', + (master_doc, 'Vector Packet Processor', + u'Vector Packet Processor Documentation', [author], 1) ] @@ -171,7 +175,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'Vector Packet Processor', u'Vector Packet Processor Documentation', + (master_doc, 'Vector Packet Processor', + u'Vector Packet Processor Documentation', author, 'Vector Packet Processor', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/etc/requirements.txt b/docs/etc/requirements.txt index 660fc6cc882..b8b69bba966 100644 --- a/docs/etc/requirements.txt +++ b/docs/etc/requirements.txt @@ -27,4 +27,5 @@ sphinxcontrib-htmlhelp==1.0.2 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.2 sphinxcontrib-serializinghtml==1.1.3 +sphinxcontrib-spelling==4.3.0 urllib3==1.24.3 diff --git a/docs/featuresbyrelease/vpp16.06.rst b/docs/featuresbyrelease/vpp16.06.rst index b8d213b15a6..7b2a19552db 100644 --- a/docs/featuresbyrelease/vpp16.06.rst +++ b/docs/featuresbyrelease/vpp16.06.rst @@ -1,35 +1,35 @@ -.. _vpp16.06: - -############################### -Features for Release VPP 16.06 -############################### - -The FD.io Project, relentlessly focused on data IO speed and efficiency supporting the creation of high performance, flexible, and scalable software defined infrastructures, announces the availability of the community’s first software release (16.06). - -In the four months since launching, FD.io has brought together more than 75 developers from 11 different companies including network operators, solution providers chip vendors, and network equipment vendors who are collaborating to enhance and innovate around the Vector Packet Processing (VPP) technology. The FD.io community has quickly formed to grow the number of projects from the initial VPP project to an additional 6 projects addressing a diverse set of requirements and usability across a variety of deployment environments. - -The 16.06 release brings unprecedented performance: 480Gbps/200mpps with 8 million routes and 2k whitelist entries on standard high volume x86 servers. - - -Features -========= - -In addition to the existing full suite of vswitch/vrouter features, the new 16.06 release adds: - -* Enhanced Switching and Routing: - - IPv6 Segment Routing multicast support - - LISP xTR support - - VXLAN over IPv6 underlay - - Per interface whitelists - - Shared adjacencies in FIB -* New and improved interface support: - - Jumbo frame support for vhost-user - - Netmap interface support - - AF_Packet interface support -* Expanded and improved programmability: - - Python API bindings - - Enhanced JVPP Java API bindings - - Debugging CLI -* Expanded Hardware and Software Support: - - Support for ARM 32 targets including Rasberry Pi single-board computer - - Support for DPDK 16.04 +.. _vpp16.06: + +############################### +Features for Release VPP 16.06 +############################### + +The FD.io Project, relentlessly focused on data IO speed and efficiency supporting the creation of high performance, flexible, and scalable software defined infrastructures, announces the availability of the community's first software release (16.06). + +In the four months since launching, FD.io has brought together more than 75 developers from 11 different companies including network operators, solution providers chip vendors, and network equipment vendors who are collaborating to enhance and innovate around the Vector Packet Processing (VPP) technology. The FD.io community has quickly formed to grow the number of projects from the initial VPP project to an additional 6 projects addressing a diverse set of requirements and usability across a variety of deployment environments. + +The 16.06 release brings unprecedented performance: 480Gbps/200mpps with 8 million routes and 2k whitelist entries on standard high volume x86 servers. + + +Features +========= + +In addition to the existing full suite of vswitch/vrouter features, the new 16.06 release adds: + +* Enhanced Switching and Routing: + - IPv6 Segment Routing multicast support + - LISP xTR support + - VXLAN over IPv6 underlay + - Per interface whitelists + - Shared adjacencies in FIB +* New and improved interface support: + - Jumbo frame support for vhost-user + - Netmap interface support + - AF_Packet interface support +* Expanded and improved programmability: + - Python API bindings + - Enhanced JVPP Java API bindings + - Debugging CLI +* Expanded Hardware and Software Support: + - Support for ARM 32 targets including Raspberry Pi single-board computer + - Support for DPDK 16.04 diff --git a/docs/featuresbyrelease/vpp17.01.rst b/docs/featuresbyrelease/vpp17.01.rst index ab7a969e756..b4022b6e358 100644 --- a/docs/featuresbyrelease/vpp17.01.rst +++ b/docs/featuresbyrelease/vpp17.01.rst @@ -14,7 +14,7 @@ Features * Performance Improvements - Improvements in DPDK input and output nodes - Improvements in L2 path - - Improvmeents in IPv4 lookup node + - Improvements in IPv4 lookup node * Feature Arcs Improvements - Consolidation of the code - New feature arcs diff --git a/docs/featuresbyrelease/vpp17.04.rst b/docs/featuresbyrelease/vpp17.04.rst index f62b880e03b..ca26ddcd15b 100644 --- a/docs/featuresbyrelease/vpp17.04.rst +++ b/docs/featuresbyrelease/vpp17.04.rst @@ -55,14 +55,14 @@ Network features - CGN (Deterministic and dynamic) - CGN configurable port allocation algorithm - ICMP support - - Tentant VRF id for SNAT outside addresses + - Tenant VRF id for SNAT outside addresses - Session dump / User dump - Port allocation per protocol * Security groups - Routed interface support - L2+L3 unified processing node - Improve fragment handling -* Segement routing v6 +* Segment routing v6 - SR policies with weighted SID lists - Binding SID - SR steering policies diff --git a/docs/featuresbyrelease/vpp17.07.rst b/docs/featuresbyrelease/vpp17.07.rst index 977442175e2..57b3a5260b5 100644 --- a/docs/featuresbyrelease/vpp17.07.rst +++ b/docs/featuresbyrelease/vpp17.07.rst @@ -32,7 +32,7 @@ Interfaces * memif: IP mode, jumbo frames, multi queue * virtio-user support -* vhost-usr; adaptive (poll/interupt) support. +* vhost-usr; adaptive (poll/interrupt) support. Network features ++++++++++++++++++ @@ -41,13 +41,13 @@ Network features * BFD FIB integration * NAT64 support * GRE over IPv6 -* Segement routing MPLS +* Segment routing MPLS * IOAM configuration for SRv6 localsid * LISP - NSH support - native forward static routes - L2 ARP -* ACL multi-core suuport +* ACL multi-core support * Flowprobe: - Add flowstartns, flowendns and tcpcontrolbits - Stateful flows and IPv6, L4 recording diff --git a/docs/featuresbyrelease/vpp18.07.rst b/docs/featuresbyrelease/vpp18.07.rst index b4ee1aea461..1f82f5c620c 100644 --- a/docs/featuresbyrelease/vpp18.07.rst +++ b/docs/featuresbyrelease/vpp18.07.rst @@ -13,7 +13,7 @@ Infrastructure - Complete rework of the dpdk-input node - Display rx/tx burst function name in "show hardware detail" - - Improve buffer alloc perfomance + - Improve buffer alloc performance + This is ~50% improvement in buffer alloc performance. For a 256 buffer allocation, it was ~10 clocks/buffer, now is < 5 clocks. - Add per-numa page allocation info to 'show memory' - Vectorized bihash_{48,40,24,16}_8 key compare diff --git a/docs/featuresbyrelease/vpp18.10.rst b/docs/featuresbyrelease/vpp18.10.rst index 8fb9d22d281..f21ac640344 100644 --- a/docs/featuresbyrelease/vpp18.10.rst +++ b/docs/featuresbyrelease/vpp18.10.rst @@ -33,9 +33,9 @@ Host stack * Support for applications with multiple workers * Support for binds from multiple app workers to same ip:port * Switched to a message queue for io and control event notifications -* Support for eventfd based notifications as alternative to mutext-condvar pair +* Support for eventfd based notifications as alternative to mutex-condvar pair * VCL refactor to support async event notifications and multiple workers -* TLS async support in client for HW accleration +* TLS async support in client for HW acceleration * Performance optimizations and bug-fixing * A number of binary APIs will be deprecated in favor of using the event message queue. Details in the API section. diff --git a/docs/gettingstarted/developers/fib20/routes.rst b/docs/gettingstarted/developers/fib20/routes.rst index 464a24af5d3..1ee09ced448 100644 --- a/docs/gettingstarted/developers/fib20/routes.rst +++ b/docs/gettingstarted/developers/fib20/routes.rst @@ -27,7 +27,7 @@ The route data is decomposed into three parts; entry, path-list and paths; * Attached next-hop: the path is described with an interface and a next-hop. The next-hop is in the same sub-net as the router's own address on that interface, hence the peer is considered to be *attached* - * Attached: the path is described only by an interface. All address covered by the prefix are on the same L2 segment to which that router's interface is attached. This means it is possible to ARP for any address covered by the prefix Рwhich is usually not the case (hence the proxy ARP debacle in IOS). An attached path is only appropriate for a point-to-point (P2P) interface where ARP is not required, i.e. a GRE tunnel. + * Attached: the path is described only by an interface. All address covered by the prefix are on the same L2 segment to which that router's interface is attached. This means it is possible to ARP for any address covered by the prefix which is usually not the case (hence the proxy ARP debacle in IOS). An attached path is only appropriate for a point-to-point (P2P) interface where ARP is not required, i.e. a GRE tunnel. * Recursive: The path is described only via the next-hop and table-id. @@ -132,7 +132,7 @@ is attached are installed in forwarding. This requires the use of *cover trackin where a route maintains a dependency relationship with the route that is its less specific cover. When this cover changes (i.e. there is a new covering route) or the forwarding information of the cover is updated, then the covered route is notified. -Adj-fibs that fail this cover check are not installed in the fib_table_tճ forwarding +Adj-fibs that fail this cover check are not installed in the fib_table_t's forwarding table, there are only present in the non-forwarding table. Overlapping sub-nets are not supported, so no adj-fib has multiple paths. The control diff --git a/docs/gettingstarted/developers/fib20/tunnels.rst b/docs/gettingstarted/developers/fib20/tunnels.rst index 1613a69df8c..c33d63c3b92 100644 --- a/docs/gettingstarted/developers/fib20/tunnels.rst +++ b/docs/gettingstarted/developers/fib20/tunnels.rst @@ -18,7 +18,7 @@ Figure 11 shows the control plane object graph for a route via a tunnel. The two sub-graphs for the route via the tunnel and the route for the tunnel's destination are shown to the right and left respectively. The red line shows the relationship form by stacking the two sub-graphs. The adjacency on the tunnel -interface is termed a ԭid-chainՠthis it is now present in the middle of the +interface is termed a 'mid-chain' this it is now present in the middle of the graph/chain rather than its usual terminal location. The mid-chain adjacency is contributed by the gre_tunnel_t , which also becomes diff --git a/docs/gettingstarted/developers/metadata.md b/docs/gettingstarted/developers/metadata.md index 2f20596c0d9..34400ef4568 100644 --- a/docs/gettingstarted/developers/metadata.md +++ b/docs/gettingstarted/developers/metadata.md @@ -10,7 +10,7 @@ We will examine vpp buffer metadata in some detail, but folks who need to manipulate and/or extend the scheme should expect to do a certain level of code inspection. -Vlib (Vector library) primary buffer metatdata +Vlib (Vector library) primary buffer metadata ---------------------------------------------- The first 64 octets of each vlib_buffer_t carries the primary buffer @@ -119,7 +119,7 @@ Important fields: * NAT fields * u32 unused[6] -Vnet (network stack) secondary buffer metatdata +Vnet (network stack) secondary buffer metadata ----------------------------------------------- Vnet primary buffer metadata occupies space reserved in the vlib diff --git a/docs/gettingstarted/developers/vlib.md b/docs/gettingstarted/developers/vlib.md index 462168618b2..504ee07a7a0 100644 --- a/docs/gettingstarted/developers/vlib.md +++ b/docs/gettingstarted/developers/vlib.md @@ -527,7 +527,7 @@ Here is a complete example: This example implements the "show ip tuple match" debug cli command. In ordinary usage, the vlib cli is available via the "vppctl" -applicationn, which sends traffic to a named pipe. One can configure +application, which sends traffic to a named pipe. One can configure debug CLI telnet access on a configurable port. The cli implementation has an output redirection facility which makes it diff --git a/docs/reference/vppvagrant/VagrantVMSetup.rst b/docs/reference/vppvagrant/VagrantVMSetup.rst index f9f4304ed94..c13a87e30f9 100644 --- a/docs/reference/vppvagrant/VagrantVMSetup.rst +++ b/docs/reference/vppvagrant/VagrantVMSetup.rst @@ -34,7 +34,7 @@ Become the root with: Now *install* VPP in the VM. Keep in mind that VPP is already built (but not yet installed) at this point based on the commands from the provisioned script *build.sh*. -When you ssh into your Vagrant box you will be placed in the directory */home/vagrant*. Change directories to */vpp/build-root*, and run these commands to install VPP based on your OS and architechture: +When you ssh into your Vagrant box you will be placed in the directory */home/vagrant*. Change directories to */vpp/build-root*, and run these commands to install VPP based on your OS and architecture: For Ubuntu systems: diff --git a/docs/usecases/ConnectingVPC.rst b/docs/usecases/ConnectingVPC.rst index cc8c927b2cb..f5b2c5dc9ae 100644 --- a/docs/usecases/ConnectingVPC.rst +++ b/docs/usecases/ConnectingVPC.rst @@ -25,7 +25,7 @@ In our VPC we will have two instances: one, in which we will install VPP and the Figure 2: Example of the resources present inside our VPC -Notice that the following example works with two VPCs, where in each of them there are a VM with VPP and a VM. Hence, you will have to execute the same commands also in the other VPC to make the connection between the two VPC possibile. +Notice that the following example works with two VPCs, where in each of them there are a VM with VPP and a VM. Hence, you will have to execute the same commands also in the other VPC to make the connection between the two VPC possible. Now, create a new VM instance (you can use same setting as before (Ubuntu Server 16.04 and m5 type)) and attach a NIC. Remember that the two Client/Server machine's NICs should stay in two different IPv4 Subnet. Afterwards, on the VM's terminal execute these commands: diff --git a/docs/usecases/contiv/K8s_Overview.md b/docs/usecases/contiv/K8s_Overview.md index ba3a8e12524..69f144b2953 100644 --- a/docs/usecases/contiv/K8s_Overview.md +++ b/docs/usecases/contiv/K8s_Overview.md @@ -6,7 +6,7 @@ Kubernetes is a container orchestration system that efficiently manages Docker containers. The Docker containers and container platforms provide many advantages over traditional virtualization. Container isolation is done on the kernel level, which eliminates the need for a guest virtual operating system, and therefore makes containers much more efficient, faster, and lightweight. The containers in Contiv/VPP are referred to as PODs. Contiv/VPP is a Kubernetes network plugin that uses [FD.io VPP](https://fd.io/) -to provide network connectivity between PODs in a k8s cluster (k8s is an abbreviated reference for kubernates). +to provide network connectivity between PODs in a k8s cluster (k8s is an abbreviated reference for kubernetes). It deploys itself as a set of system PODs in the `kube-system` namespace, some of them (`contiv-ksr`, `contiv-etcd`) on the master node, and some of them (`contiv-cni`, `contiv-vswitch`, `contiv-stn`) on each node in the cluster. diff --git a/docs/usecases/simpleperf/iperf3.rst b/docs/usecases/simpleperf/iperf3.rst index 0b0de373bff..6f5d345c598 100644 --- a/docs/usecases/simpleperf/iperf3.rst +++ b/docs/usecases/simpleperf/iperf3.rst @@ -3,7 +3,7 @@ Introduction ============ -This tutorial shows how to use VPP use iperf3 and Trex to get some basic performance +This tutorial shows how to use VPP use iperf3 and TRex to get some basic performance numbers from a few basic configurations. Four examples are shown. In the first two examples, the **iperf3** tool is used to generate traffic, and in the last two examples the Cisco's `TRex Realistic Traffic Generator `_ is used. For diff --git a/src/plugins/quic/quic_plugin.rst b/src/plugins/quic/quic_plugin.rst index 3bbddd83169..429b83e7a70 100644 --- a/src/plugins/quic/quic_plugin.rst +++ b/src/plugins/quic/quic_plugin.rst @@ -47,7 +47,7 @@ After having setup two interconnected vpps, you can attach the quic_echo binary * To run the client & server use ``quic_echo socket-name /vpp.sock client|server uri quic://1.1.1.1/1234`` * Several options are available to customize the amount of data sent, number of threads, logging and timing. -The behavior of this app when run with ``nclient 2/4`` is two first establish 2 connections with the given peer, and once everything has been openend start opening 4 quic streams, and transmit data. Flow is as follows. +The behavior of this app when run with ``nclient 2/4`` is two first establish 2 connections with the given peer, and once everything has been opened start opening 4 quic streams, and transmit data. Flow is as follows. .. image:: /_images/quic_plugin_echo_flow.png -- cgit 1.2.3-korg