diff options
Diffstat (limited to 'docs/gettingstarted/writingdocs/styleguide')
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 + |