aboutsummaryrefslogtreecommitdiffstats
path: root/docs/gettingstarted/writingdocs/styleguide
diff options
context:
space:
mode:
authorJohn DeNisco <jdenisco@cisco.com>2018-07-26 12:45:10 -0400
committerDave Barach <openvpp@barachs.net>2018-07-26 18:34:47 +0000
commit06dcd45ff81e06bc8cf40ed487c0b2652d346a5a (patch)
tree71403f9d422c4e532b2871a66ab909bd6066b10b /docs/gettingstarted/writingdocs/styleguide
parent1d65279ffecd0f540288187b94cb1a6b84a7a0c6 (diff)
Initial commit of Sphinx docs
Change-Id: I9fca8fb98502dffc2555f9de7f507b6f006e0e77 Signed-off-by: John DeNisco <jdenisco@cisco.com>
Diffstat (limited to 'docs/gettingstarted/writingdocs/styleguide')
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/index.rst30
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/iperf-vm.xml106
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/rawhtml.rst10
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/styleguide.rst20
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/styleguide02.rst83
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/styleguide02table.rst76
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/styleguide03.rst32
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/styleguide04.rst12
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/styleguide05.rst11
-rw-r--r--docs/gettingstarted/writingdocs/styleguide/xmlexample.rst11
10 files changed, 391 insertions, 0 deletions
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
+