docs: Update sphinx, requirements, support markdown tables

Change-Id: Ie7c546f5720b10fe5423397204e1ab5c22d7a2ba
Signed-off-by: jdenisco <jdenisco@cisco.com>

9 files changed, 50 insertions, 30 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 1d60e29f1a7..8e8d422e519 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -40,6 +40,8 @@ release = u'1.0'
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'recommonmark',
+    'sphinx_markdown_tables'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -48,10 +50,11 @@ templates_path = ['_templates']
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = ['.rst', '.md']
-source_parsers = {
-   '.md': 'recommonmark.parser.CommonMarkParser',
-}
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown'
+    }
+
 # The master toctree document.
 master_doc = 'index'
 
diff --git a/docs/etc/requirements.txt b/docs/etc/requirements.txt
index 194e750d775..660fc6cc882 100644
--- a/docs/etc/requirements.txt
+++ b/docs/etc/requirements.txt
@@ -1,23 +1,30 @@
 alabaster==0.7.12
 Babel==2.6.0
-certifi==2018.11.29
+certifi==2019.3.9
 chardet==3.0.4
-CommonMark==0.5.4
+commonmark==0.9.0
 docutils==0.14
+future==0.17.1
 idna==2.8
 imagesize==1.1.0
-Jinja2==2.10
-MarkupSafe==1.1.0
-packaging==18.0
-Pygments==2.3.0
-pyparsing==2.3.0
-pytz==2018.7
-recommonmark==0.4.0
+Jinja2==2.10.1
+Markdown==2.6.11
+MarkupSafe==1.1.1
+packaging==19.0
+Pygments==2.4.0
+pyparsing==2.4.0
+pytz==2019.1
+recommonmark==0.5.0
 requests==2.21.0
 six==1.12.0
 snowballstemmer==1.2.1
-Sphinx==1.8.2
-sphinx-rtd-theme==0.4.2
-sphinxcontrib-websupport==1.1.0
-typing==3.6.6
-urllib3==1.24.2
+Sphinx==2.0.1
+sphinx-markdown-tables==0.0.9
+sphinx-rtd-theme==0.4.3
+sphinxcontrib-applehelp==1.0.1
+sphinxcontrib-devhelp==1.0.1
+sphinxcontrib-htmlhelp==1.0.2
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.2
+sphinxcontrib-serializinghtml==1.1.3
+urllib3==1.24.3
diff --git a/docs/gettingstarted/developers/infrastructure.md b/docs/gettingstarted/developers/infrastructure.md
index b99460732c5..9dde9829906 100644
--- a/docs/gettingstarted/developers/infrastructure.md
+++ b/docs/gettingstarted/developers/infrastructure.md
@@ -48,7 +48,7 @@ macro! It's smart about NULL pointers.\]
 
 Typically, the user header is not present. User headers allow for other
 data structures to be built atop vppinfra vectors. Users may specify the
-alignment for first data element of a vector via the [vec]()\*\_aligned
+alignment for first data element of a vector via the \[vec\]()\*\_aligned
 macros. 
 
 Vector elements can be any C type e.g. (int, double, struct bar). This
@@ -57,7 +57,7 @@ Many macros have \_a variants supporting alignment of vector elements
 and \_h variants supporting non-zero-length vector headers. The \_ha
 variants support both.  Additionally cacheline alignment within a
 vector element structure can be specified using the
-[CLIB_CACHE_LINE_ALIGN_MARK]() macro.
+\[CLIB_CACHE_LINE_ALIGN_MARK\]() macro.
 
 Inconsistent usage of header and/or alignment related macro variants
 will cause delayed, confusing failures.
diff --git a/docs/gettingstarted/writingdocs/styleguidemd/styleguide03.md b/docs/gettingstarted/writingdocs/styleguidemd/styleguide03.md
index 462006fd6f3..4c66dc4de33 100644
--- a/docs/gettingstarted/writingdocs/styleguidemd/styleguide03.md
+++ b/docs/gettingstarted/writingdocs/styleguidemd/styleguide03.md
@@ -20,3 +20,13 @@ referenced with following construct. This is the image created to show a
 pull request.
 
 ![](/_images/examplePullReq.png)
+
+Tables
+======
+
+An example of a table in markdown is shown here:
+
+| This Column | This Column   | This Column |
+| ------------|:-------------:|------------:|
+| is left     | is            | is right    |
+| aligned     | centered      | aligned     |
diff --git a/docs/usecases/contiv/BUG_REPORTS.md b/docs/usecases/contiv/BUG_REPORTS.md
index 23c9a7c393c..648e67f2422 100644
--- a/docs/usecases/contiv/BUG_REPORTS.md
+++ b/docs/usecases/contiv/BUG_REPORTS.md
@@ -151,7 +151,7 @@ index 3676047..ffa4473 100644
                valueFrom:
 ```
 
-If VPP is the crashing process, please follow the [CORE_FILES](CORE_FILES.html) guide and provide the coredump file.
+If VPP is the crashing process, please follow the \[CORE_FILES\](CORE_FILES.html) guide and provide the coredump file.
 
 
 ### Inspect VPP Config
diff --git a/docs/usecases/contiv/K8s_Overview.md b/docs/usecases/contiv/K8s_Overview.md
index f9cf9c5a9ba..e3d8e1a0d44 100644
--- a/docs/usecases/contiv/K8s_Overview.md
+++ b/docs/usecases/contiv/K8s_Overview.md
@@ -78,7 +78,7 @@ network stack, and data-plane NIC interface controlled by VPP:
  - data-plane NIC is controlled directly by VPP using DPDK. Note, this means that
  this interface is not visible to the host Linux network stack, and the node either needs another
  management interface for k8s control plane communication, or 
- [STN (Steal The NIC)](SINGLE_NIC_SETUP.html) deployment must be applied.
+ \[STN (Steal The NIC)\](SINGLE_NIC_SETUP.html) deployment must be applied.
 
 **Contiv VPP Agent** is the control plane part of the vSwitch container. It is responsible
 for configuring the VPP according to the information gained from ETCD, and requests
@@ -99,11 +99,11 @@ and replies with a response, which is then forwarded back to Kubelet.
 
 
 ### Contiv STN Daemon
-This section discusses how the Contiv [STN (Steal The NIC)](SINGLE_NIC_SETUP.html) daemon operation works. As already mentioned, the default setup of Contiv/VPP requires two network interfaces
+This section discusses how the Contiv \[STN (Steal The NIC)\](SINGLE_NIC_SETUP.html) daemon operation works. As already mentioned, the default setup of Contiv/VPP requires two network interfaces
 per node: one controlled by VPP for data facing PODs, and one controlled by the host
 network stack for k8s control plane communication. In case that your k8s nodes
 do not provide two network interfaces, Contiv/VPP can work in the single NIC setup,
 when the interface will be "stolen" from the host network stack just before starting
 the VPP and configured with the same IP address on VPP, as well as 
 on the host-VPP interconnect TAP interface, as it had in the host before it. 
-For more information on STN setup, read the [Single NIC Setup README](./SINGLE_NIC_SETUP.html)
+For more information on STN setup, read the \[Single NIC Setup README\](./SINGLE_NIC_SETUP.html)
diff --git a/docs/usecases/contiv/NETWORKING.md b/docs/usecases/contiv/NETWORKING.md
index 0b6d08127fb..25ce3ce0410 100644
--- a/docs/usecases/contiv/NETWORKING.md
+++ b/docs/usecases/contiv/NETWORKING.md
@@ -20,7 +20,7 @@ ID is released back to the pool and will be re-used by the next node.
 The Node ID is used to calculate per-node IP subnets for PODs
 and other internal subnets that need to be unique on each node. Apart from the Node ID,
 the input for IPAM calculations is a set of config knobs, which can be specified
-in the `IPAMConfig` section of the [Contiv/VPP deployment YAML](../../../k8s/contiv-vpp.yaml):
+in the `IPAMConfig` section of the \[Contiv/VPP deployment YAML\](../../../k8s/contiv-vpp.yaml):
 
 - **PodSubnetCIDR** (default `10.1.0.0/16`): each pod gets an IP address assigned 
 from this range. The size of this range (default `/16`) dictates upper limit of 
@@ -132,6 +132,6 @@ whenever a node is added/deleted in the k8s cluster.
 
 
 #### More Info
-Please refer to the [Packet Flow Dev Guide](../dev-guide/PACKET_FLOW.html) for more 
+Please refer to the \[Packet Flow Dev Guide\](../dev-guide/PACKET_FLOW.html) for more 
 detailed description of paths traversed by request and response packets 
 inside Contiv/VPP Kubernetes cluster under different situations.
\ No newline at end of file
diff --git a/docs/usecases/contiv/SINGLE_NIC_SETUP.md b/docs/usecases/contiv/SINGLE_NIC_SETUP.md
index 875a7323fff..83dd47d99a6 100644
--- a/docs/usecases/contiv/SINGLE_NIC_SETUP.md
+++ b/docs/usecases/contiv/SINGLE_NIC_SETUP.md
@@ -52,7 +52,7 @@ or individually for every node in the cluster.
 Global configuration is used in homogeneous environments where all nodes in 
 a given cluster have the same hardware configuration, for example only a single
 Network Adapter. To enable the STN feature globally, put the `StealFirstNIC: True`
-stanza into the [`contiv-vpp.yaml`][1] deployment file, for example:
+stanza into the \[`contiv-vpp.yaml`\]\[1\] deployment file, for example:
 ```
 data:
   contiv.yaml: |-
@@ -67,13 +67,13 @@ Setting `StealFirstNIC` to `True` will tell the STN Daemon on every node in the
 cluster to steal the first NIC from the kernel and assign it to VPP. Note that
 the Network Adapters on different nodes do not need to be of the same type. You
 still need to create the respective vswitch configurations on every node in the
-cluster, as shown [above](#creating-a-vpp-interface-configuration).
+cluster, as shown \[above\](#creating-a-vpp-interface-configuration).
 
 ##### Individual Configuration:
 Individual configuration is used in heterogeneous environments where each node
 in a given cluster may be configured differently. To enable the STN feature 
 for a specific node in the cluster, put the following stanza into its Node
-Configuration in the [`contiv-vpp.yaml`][1] deployment file, for example:
+Configuration in the \[`contiv-vpp.yaml`\]\[1\] deployment file, for example:
 ```
 ...
     NodeConfig:
diff --git a/docs/usecases/contiv/VPPTRACE.md b/docs/usecases/contiv/VPPTRACE.md
index 2b397427cb3..c9d2088266b 100644
--- a/docs/usecases/contiv/VPPTRACE.md
+++ b/docs/usecases/contiv/VPPTRACE.md
@@ -1,7 +1,7 @@
 ## Using vpptrace.sh for VPP Packet Tracing
 
 VPP allows tracing of incoming packets using CLI commands `trace add` and `show trace`
-as explained [here](VPP_PACKET_TRACING_K8S.html), but it is a rather cumbersome process.
+as explained \[here\](VPP_PACKET_TRACING_K8S.html), but it is a rather cumbersome process.
 
 The buffer for captured packets is limited in size, and once it gets full the tracing stops. The user has to manually clear the buffer content, and then repeat the trace command to resume the packet capture, losing information about all packets received in the meantime.