From 06dcd45ff81e06bc8cf40ed487c0b2652d346a5a Mon Sep 17 00:00:00 2001
From: John DeNisco <jdenisco@cisco.com>
Date: Thu, 26 Jul 2018 12:45:10 -0400
Subject: Initial commit of Sphinx docs

Change-Id: I9fca8fb98502dffc2555f9de7f507b6f006e0e77
Signed-off-by: John DeNisco <jdenisco@cisco.com>
---
 .../writingdocs/styleguide/index.rst               |  30 ++++++
 .../writingdocs/styleguide/iperf-vm.xml            | 106 +++++++++++++++++++++
 .../writingdocs/styleguide/rawhtml.rst             |  10 ++
 .../writingdocs/styleguide/styleguide.rst          |  20 ++++
 .../writingdocs/styleguide/styleguide02.rst        |  83 ++++++++++++++++
 .../writingdocs/styleguide/styleguide02table.rst   |  76 +++++++++++++++
 .../writingdocs/styleguide/styleguide03.rst        |  32 +++++++
 .../writingdocs/styleguide/styleguide04.rst        |  12 +++
 .../writingdocs/styleguide/styleguide05.rst        |  11 +++
 .../writingdocs/styleguide/xmlexample.rst          |  11 +++
 10 files changed, 391 insertions(+)
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/index.rst
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/iperf-vm.xml
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/rawhtml.rst
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/styleguide.rst
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/styleguide02.rst
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/styleguide02table.rst
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/styleguide03.rst
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/styleguide04.rst
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/styleguide05.rst
 create mode 100644 docs/gettingstarted/writingdocs/styleguide/xmlexample.rst

(limited to 'docs/gettingstarted/writingdocs/styleguide')

diff --git a/docs/gettingstarted/writingdocs/styleguide/index.rst b/docs/gettingstarted/writingdocs/styleguide/index.rst
new file mode 100644
index 00000000000..79d28c37493
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/index.rst
@@ -0,0 +1,30 @@
+.. _styleguide:
+
+#############################
+reStructured Text Style Guide
+#############################
+
+Most of the these documents are written ins reStructured Text (rst). This chapter describes some of
+the Sphinx Markup Constructs used in these documents. The Sphinx style guide can be found at:
+`Sphinx Style Guide <http://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html>`_
+For a more detailed list of Sphinx Markup Constructs please refer to:
+`Sphinx Markup Constructs <http://www.sphinx-doc.org/en/stable/markup/index.html>`_
+
+This document is also an example of a directory structure for a document that spans mutliple pages.
+Notice we have the file **index.rst** and the then documents that are referenced in index.rst. The
+referenced documents are shown at the bottom of this page.
+
+A label is shown at the top of this page. Then the first construct describes a the document title
+**FD.io Style Guide**. Text usually follows under each title or heading.
+
+A **Table of Contents** structure is shown below. Using **toctree** in this way will show the headings
+in a nicely in the generated documents.
+
+.. toctree::
+
+  styleguide.rst
+  styleguide02.rst
+  styleguide02table.rst
+  styleguide03.rst
+  styleguide04.rst
+  styleguide05.rst
diff --git a/docs/gettingstarted/writingdocs/styleguide/iperf-vm.xml b/docs/gettingstarted/writingdocs/styleguide/iperf-vm.xml
new file mode 100644
index 00000000000..be354c5f977
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/iperf-vm.xml
@@ -0,0 +1,106 @@
+<domain type='kvm' id='54'>
+  <name>iperf-server</name>
+  <memory unit='KiB'>1048576</memory>
+  <currentMemory unit='KiB'>1048576</currentMemory>
+  <memoryBacking>
+    <hugepages>
+      <page size='2048' unit='KiB'/>
+    </hugepages>
+  </memoryBacking>
+  <vcpu placement='static'>1</vcpu>
+  <resource>
+    <partition>/machine</partition>
+  </resource>
+  <os>
+    <type arch='x86_64' machine='pc-i440fx-xenial'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <features>
+    <acpi/>
+    <apic/>
+  </features>
+  <cpu mode='host-model'>
+    <model fallback='allow'></model>
+    <numa>
+      <cell id='0' cpus='0' memory='262144' unit='KiB' memAccess='shared'/>
+    </numa>
+  </cpu>
+  <clock offset='utc'>
+    <timer name='rtc' tickpolicy='catchup'/>
+    <timer name='pit' tickpolicy='delay'/>
+    <timer name='hpet' present='no'/>
+  </clock>
+  <on_poweroff>destroy</on_poweroff>
+  <on_reboot>restart</on_reboot>
+  <on_crash>restart</on_crash>
+  <pm>
+    <suspend-to-mem enabled='no'/>
+    <suspend-to-disk enabled='no'/>
+  </pm>
+  <devices>
+    <emulator>/usr/bin/kvm</emulator>
+    <disk type='file' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <source file='/tmp/xenial-mod.img'/>
+      <backingStore/>
+      <target dev='vda' bus='virtio'/>
+      <alias name='virtio-disk0'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
+    </disk>
+    <disk type='file' device='cdrom'>
+      <driver name='qemu' type='raw'/>
+      <source file='/scratch/jdenisco/sae/configs/cloud-config.iso'/>
+      <backingStore/>
+      <target dev='hda' bus='ide'/>
+      <readonly/>
+      <alias name='ide0-0-0'/>
+      <address type='drive' controller='0' bus='0' target='0' unit='0'/>
+    </disk>
+    <controller type='usb' index='0' model='ich9-ehci1'>
+      <alias name='usb'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x06' function='0x7'/>
+    </controller>
+    <controller type='pci' index='0' model='pci-root'>
+      <alias name='pci.0'/>
+    </controller>
+    <controller type='ide' index='0'>
+      <alias name='ide'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x1'/>
+    </controller>
+    <controller type='virtio-serial' index='0'>
+      <alias name='virtio-serial0'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x05' function='0x0'/>
+    </controller>
+    <interface type='vhostuser'>
+      <mac address='52:54:00:4c:47:f2'/>
+      <source type='unix' path='/tmp//vm00.sock' mode='server'/>
+      <model type='virtio'/>
+      <alias name='net1'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/>
+    </interface>
+    <serial type='pty'>
+      <source path='/dev/pts/2'/>
+      <target port='0'/>
+      <alias name='serial0'/>
+    </serial>
+    <console type='pty' tty='/dev/pts/2'>
+      <source path='/dev/pts/2'/>
+      <target type='serial' port='0'/>
+      <alias name='serial0'/>
+    </console>
+    <input type='mouse' bus='ps2'/>
+    <input type='keyboard' bus='ps2'/>
+    <graphics type='vnc' port='5900' autoport='yes' listen='127.0.0.1'>
+      <listen type='address' address='127.0.0.1'/>
+    </graphics>
+    <memballoon model='virtio'>
+      <alias name='balloon0'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x08' function='0x0'/>
+    </memballoon>
+  </devices>
+  <seclabel type='dynamic' model='apparmor' relabel='yes'>
+    <label>libvirt-2c4c9317-c7a5-4b37-b789-386ccda7348a</label>
+    <imagelabel>libvirt-2c4c9317-c7a5-4b37-b789-386ccda7348a</imagelabel>
+  </seclabel>
+</domain>
+
diff --git a/docs/gettingstarted/writingdocs/styleguide/rawhtml.rst b/docs/gettingstarted/writingdocs/styleguide/rawhtml.rst
new file mode 100644
index 00000000000..e94eb452312
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/rawhtml.rst
@@ -0,0 +1,10 @@
+.. _rawhtml01:
+
+Raw HTML Example
+================
+
+This example shows how to include include a CSIT performance graph.
+
+.. raw:: html
+
+    <iframe src="https://docs.fd.io/csit/rls1801/report/_static/vpp/64B-1t1c-l2-sel2-ndrdisc.html" width="850" height="1000" frameborder="0">
diff --git a/docs/gettingstarted/writingdocs/styleguide/styleguide.rst b/docs/gettingstarted/writingdocs/styleguide/styleguide.rst
new file mode 100644
index 00000000000..2312ea9c425
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/styleguide.rst
@@ -0,0 +1,20 @@
+.. _styleguide01:
+
+*********
+Heading 1
+*********
+
+This is the top heading level. More levels are shown below.
+
+Heading 2
+=========
+
+Heading 3
+---------
+
+Heading 4
+^^^^^^^^^
+
+Heading 5
+"""""""""
+
diff --git a/docs/gettingstarted/writingdocs/styleguide/styleguide02.rst b/docs/gettingstarted/writingdocs/styleguide/styleguide02.rst
new file mode 100644
index 00000000000..e2d7649f585
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/styleguide02.rst
@@ -0,0 +1,83 @@
+.. _styleguide02:
+
+*************************
+Bullets, Bold and Italics
+*************************
+
+Bold text can be show with **Bold Text**, Italics with *Italic text*. Bullets like so:
+
+* Bullet 1
+* Bullet 2
+
+#. Numbered Bullet 1
+#. Numbered Bullet 2
+
+*****
+Notes
+*****
+
+A note can be used to describe something not in the normal flow of the paragragh. This
+is an example of a note.
+
+.. note::
+
+    Using **git commit** after adding your files saves a "Snapshot" of them, so it's very hard
+    to lose your work if you *commit often*.
+
+***********
+Code Blocks
+***********
+
+This paragraph describes how to do **Console Commands**. When showing VPP commands it is reccomended
+that the command be executed from the linux console as shown. The Highlighting in the final documents
+shows up nicely this way.
+
+.. code-block:: console
+
+    $ sudo bash
+    # vppctl show interface
+                  Name               Idx       State          Counter          Count     
+    TenGigabitEthernet86/0/0          1         up       rx packets               6569213
+                                                         rx bytes              9928352943
+                                                         tx packets                 50384
+                                                         tx bytes                 3329279
+    TenGigabitEthernet86/0/1          2        down      
+    VirtualEthernet0/0/0              3         up       rx packets                 50384
+                                                         rx bytes                 3329279
+                                                         tx packets               6569213
+                                                         tx bytes              9928352943
+                                                         drops                       1498
+    local0                            0        down      
+    #
+
+
+The **code-block** construct is also used for code samples. The following shows how to include a block of
+"C" code.
+
+.. code-block:: c
+
+   #include <vlib/unix/unix.h>
+   abf_policy_t *
+   abf_policy_get (u32 index)
+   {
+     return (pool_elt_at_index (abf_policy_pool, index));
+   }
+
+Diffs are generated in the final docs nicely with "::" at the end of the description like so::
+
+  diff --git a/src/vpp/vnet/main.c b/src/vpp/vnet/main.c
+  index 6e136e19..69189c93 100644
+  --- a/src/vpp/vnet/main.c
+  +++ b/src/vpp/vnet/main.c
+  @@ -18,6 +18,8 @@
+   #include <vlib/unix/unix.h>
+   #include <vnet/plugin/plugin.h>
+   #include <vnet/ethernet/ethernet.h>
+  +#include <vnet/ip/ip4_packet.h>
+  +#include <vnet/ip/format.h>
+   #include <vpp/app/version.h>
+   #include <vpp/api/vpe_msg_enum.h>
+   #include <limits.h>
+  @@ -400,6 +402,63 @@ VLIB_CLI_COMMAND (test_crash_command, static) = {
+
+   #endif
diff --git a/docs/gettingstarted/writingdocs/styleguide/styleguide02table.rst b/docs/gettingstarted/writingdocs/styleguide/styleguide02table.rst
new file mode 100644
index 00000000000..742888be760
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/styleguide02table.rst
@@ -0,0 +1,76 @@
+.. _styleguide02table:
+
+******
+Tables
+******
+
+There are two types of tables with different syntax, `Grid Tables <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables>`_, and `Simple Tables <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables>`_.
+
+Grid Tables
+___________
+
+`Grid Tables <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables>`_ are described with a visual grid made up of the characters "-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines (row separators). The equals sign ("=") may be used to separate optional header rows from the table body. The vertical bar ("|") is used for vertical lines (column separators). The plus sign ("+") is used for intersections of horizontal and vertical lines.
+
+Here is example code for a grid table in a *.rst* file:
+
+.. code-block:: console
+
+	+------------------------+------------+----------+----------+
+	| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+	| (header rows optional) |            |          |          |
+	+========================+============+==========+==========+
+	| body row 1, column 1   | column 2   | column 3 | column 4 |
+	+------------------------+------------+----------+----------+
+	| body row 2             | Cells may span columns.          |
+	+------------------------+------------+---------------------+
+	| body row 3             | Cells may  | - Table cells       |
+	+------------------------+ span rows. | - contain           |
+	| body row 4             |            | - body elements.    |
+	+------------------------+------------+---------------------+
+	
+This example code generates a grid table that looks like this:
+
++------------------------+------------+----------+----------+
+| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+| (header rows optional) |            |          |          |
++========================+============+==========+==========+
+| body row 1, column 1   | column 2   | column 3 | column 4 |
++------------------------+------------+----------+----------+
+| body row 2             | Cells may span columns.          |
++------------------------+------------+---------------------+
+| body row 3             | Cells may  | - Table cells       |
++------------------------+ span rows. | - contain           |
+| body row 4             |            | - body elements.    |
++------------------------+------------+---------------------+
+
+
+Simple Tables
+_____________
+
+`Simple tables <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables>`_ are described with horizontal borders made up of "=" and "-" characters. The equals sign ("=") is used for top and bottom table borders, and to separate optional header rows from the table body. The hyphen ("-") is used to indicate column spans in a single row by underlining the joined columns, and may optionally be used to explicitly and/or visually separate rows. 
+
+Simple tables are "simpler" to create than grid tables, but are more limited.
+
+Here is example code for a simple table in a *.rst* file.
+
+.. code-block:: console
+	
+	=====  =====  =======
+	  A      B    A and B
+	=====  =====  =======
+	False  False  False
+	True   False  False
+	False  True   False
+	True   True   True
+	=====  =====  =======
+
+This example code generates a simple table that looks like this:
+
+=====  =====  =======
+  A      B    A and B
+=====  =====  =======
+False  False  False
+True   False  False
+False  True   False
+True   True   True
+=====  =====  =======
\ No newline at end of file
diff --git a/docs/gettingstarted/writingdocs/styleguide/styleguide03.rst b/docs/gettingstarted/writingdocs/styleguide/styleguide03.rst
new file mode 100644
index 00000000000..df35643b8a2
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/styleguide03.rst
@@ -0,0 +1,32 @@
+.. _styleguide03:
+
+******************
+Labels, References
+******************
+
+A link or reference to other paragraphs within these documents can be done with
+following construct.
+
+In this example the reference points the label **showintcommand**. The label **styleguide03**
+is shown at the top of this page. A label used in this way must be above a heading or title.
+
+:ref:`showintcommand` command.
+
+**************
+External Links
+**************
+
+An external link is done with the following construct:
+
+`Sphinx Markup Constructs <http://www.sphinx-doc.org/en/stable/markup/index.html>`_
+
+******
+Images
+******
+
+Images should be placed in the directory docs/_images. They can then be referenced with
+following construct. This is the image created to show a pull request.
+
+.. figure:: /_images/examplePullReq.png
+   :scale: 35%
+   :align: center
diff --git a/docs/gettingstarted/writingdocs/styleguide/styleguide04.rst b/docs/gettingstarted/writingdocs/styleguide/styleguide04.rst
new file mode 100644
index 00000000000..1bc4210de78
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/styleguide04.rst
@@ -0,0 +1,12 @@
+.. _styleguide04:
+
+****************
+Including a file
+****************
+
+A complete file should be included with the following construct. It is recomended it be included with
+it's own .rst file describing the file included. This is an example of an xml file is included.
+
+.. toctree::
+
+  xmlexample.rst
diff --git a/docs/gettingstarted/writingdocs/styleguide/styleguide05.rst b/docs/gettingstarted/writingdocs/styleguide/styleguide05.rst
new file mode 100644
index 00000000000..7ea977358c1
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/styleguide05.rst
@@ -0,0 +1,11 @@
+.. _styleguide05:
+
+********
+Raw HTML
+********
+
+An html frame can be included with the following construct. It is recommended that references to raw html be included with it's own .rst file.
+
+.. toctree::
+
+  rawhtml.rst
diff --git a/docs/gettingstarted/writingdocs/styleguide/xmlexample.rst b/docs/gettingstarted/writingdocs/styleguide/xmlexample.rst
new file mode 100644
index 00000000000..575a639579e
--- /dev/null
+++ b/docs/gettingstarted/writingdocs/styleguide/xmlexample.rst
@@ -0,0 +1,11 @@
+.. _xmlexample:
+
+An XML File
+===========
+
+An example of an XML file.
+
+.. literalinclude:: iperf-vm.xml
+   :language: XML
+   :emphasize-lines: 42-49, 74-80
+
-- 
cgit