aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorjdenisco <jdenisco@cisco.com>2019-05-13 12:40:21 -0400
committerDave Barach <openvpp@barachs.net>2019-05-16 17:42:13 +0000
commit8a6e1b190c63cc596aed33f84b5989b64d276423 (patch)
tree016c181103861da2791c090a3b874b9bc385234e
parent8fa01c17aa65c03b1f25f9accaa5bb0f9d0862c4 (diff)
docs: Update sphinx, requirements, support markdown tables
Change-Id: Ie7c546f5720b10fe5423397204e1ab5c22d7a2ba Signed-off-by: jdenisco <jdenisco@cisco.com>
-rw-r--r--docs/conf.py11
-rw-r--r--docs/etc/requirements.txt35
-rw-r--r--docs/gettingstarted/developers/infrastructure.md4
-rw-r--r--docs/gettingstarted/writingdocs/styleguidemd/styleguide03.md10
-rw-r--r--docs/usecases/contiv/BUG_REPORTS.md2
-rw-r--r--docs/usecases/contiv/K8s_Overview.md6
-rw-r--r--docs/usecases/contiv/NETWORKING.md4
-rw-r--r--docs/usecases/contiv/SINGLE_NIC_SETUP.md6
-rw-r--r--docs/usecases/contiv/VPPTRACE.md2
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.