diff options
Diffstat (limited to 'docs/gettingstarted/writingdocs')
16 files changed, 0 insertions, 633 deletions
diff --git a/docs/gettingstarted/writingdocs/buildingrst.rst b/docs/gettingstarted/writingdocs/buildingrst.rst deleted file mode 100644 index 474257d35d0..00000000000 --- a/docs/gettingstarted/writingdocs/buildingrst.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. _buildingrst: - -************************** -Creating VPP Documents -************************** - -These instructions show how the VPP documentation sources are built. - -The VPP Documents are written using `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ (rst), -or markdown (md). These files are then built using the Sphinx build system `Sphinx <http://www.sphinx-doc.org/en/master/>`_. - -Get the VPP sources -===================== - -Start with a clone of the vpp repository. - -.. code-block:: console - - $ git clone https://gerrit.fd.io/r/vpp - $ cd vpp - - -Install the Necessary Packages -=============================== - -Before building the docs there are some packages that are needed. To install -these packages on ubuntu execute the following. - -.. code-block:: console - - $ sudo apt-get install python3-all python3-setuptools python3-pip - - -Create a Virtual Environment using virtualenv -=============================================== - -For more information on how to use the Python virtual environment check out -`Installing packages using pip and virtualenv`_. - -.. _`Installing packages using pip and virtualenv`: https://packaging.python.org/guides/installing-using-pip-and-virtualenv/ - -In the vpp root directory on your system, run: - -.. code-block:: console - - $ make docs-venv - -Which installs all the required applications into it's own, isolated, virtual environment, so as to not -interfere with other builds that may use different versions of software. - -Build the html files -====================== - -Build the html **index.html** file: - -.. code-block:: console - - $ make docs - -Clean the environment -====================== - -Delete all the generated files with the following: - -.. code-block:: console - - $ make docs-clean - -View the results -================= - -| If there are no errors during the build process, you should now have an **index.html** file in your -| **vpp/docs/_build/html** directory, which you can then view in your browser. - -.. figure:: /_images/htmlBuild.png - :alt: Figure: My directory containing the index.html file - :scale: 35% - :align: center - -Whenever you make changes to your **.rst** files that you want to see, repeat this build process. - -.. note:: - - To exit from the virtual environment execute: - -.. code-block:: console - - $ deactivate - -Getting your documents reviewed and merged -========================================== - -VPP documents are reviewed and merged like and other source code. Refer to :ref:`gitreview` -to get your changes reviewed and merged. diff --git a/docs/gettingstarted/writingdocs/index.rst b/docs/gettingstarted/writingdocs/index.rst deleted file mode 100644 index 45a746df826..00000000000 --- a/docs/gettingstarted/writingdocs/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _writingdocs: - -######################### -Writing Documents -######################### - -This section covers the following topics: - -* Building VPP Documents -* Merging FD.io VPP documents and performing a Git review -* reStructured Text Style Guide that describes different format styles -* Markdown Style Guide that describes different format styles - - -.. toctree:: - :maxdepth: 3 - - buildingrst - styleguide/index.rst - styleguidemd/index.rst diff --git a/docs/gettingstarted/writingdocs/styleguide/index.rst b/docs/gettingstarted/writingdocs/styleguide/index.rst deleted file mode 100644 index 240b3a26b19..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _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 multiple 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:: - :maxdepth: 2 - - 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 deleted file mode 100644 index be354c5f977..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/iperf-vm.xml +++ /dev/null @@ -1,106 +0,0 @@ -<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 deleted file mode 100644 index e94eb452312..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/rawhtml.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _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 deleted file mode 100644 index 2312ea9c425..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/styleguide.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _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 deleted file mode 100644 index af92c93c316..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/styleguide02.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. _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 paragraph. 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 recommended -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 deleted file mode 100644 index 742888be760..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/styleguide02table.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. _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 deleted file mode 100644 index df35643b8a2..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/styleguide03.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _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 deleted file mode 100644 index 7dcea37d9d3..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/styleguide04.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _styleguide04: - -**************** -Including a file -**************** - -A complete file should be included with the following construct. It is recommended 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 deleted file mode 100644 index 7ea977358c1..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/styleguide05.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _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 deleted file mode 100644 index 575a639579e..00000000000 --- a/docs/gettingstarted/writingdocs/styleguide/xmlexample.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _xmlexample: - -An XML File -=========== - -An example of an XML file. - -.. literalinclude:: iperf-vm.xml - :language: XML - :emphasize-lines: 42-49, 74-80 - diff --git a/docs/gettingstarted/writingdocs/styleguidemd/index.rst b/docs/gettingstarted/writingdocs/styleguidemd/index.rst deleted file mode 100644 index f9dfbeb2dbb..00000000000 --- a/docs/gettingstarted/writingdocs/styleguidemd/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _styleguidemd: - -#################### -Markdown Style Guide -#################### - -Most of these documents are written using :ref:`styleguide` (rst), but pages can also be -written in Markdown. This chapter describes some constructs used to write these documents. -For a more detailed description of Markdown refer to `Markdown Wikipedia <https://en.wikipedia.org/wiki/Markdown>`_ - -.. toctree:: - :maxdepth: 2 - - styleguide.md - styleguide02.md - styleguide03.md diff --git a/docs/gettingstarted/writingdocs/styleguidemd/styleguide.md b/docs/gettingstarted/writingdocs/styleguidemd/styleguide.md deleted file mode 100644 index 31ea822ca13..00000000000 --- a/docs/gettingstarted/writingdocs/styleguidemd/styleguide.md +++ /dev/null @@ -1,13 +0,0 @@ -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/styleguidemd/styleguide02.md b/docs/gettingstarted/writingdocs/styleguidemd/styleguide02.md deleted file mode 100644 index 5582d7224c9..00000000000 --- a/docs/gettingstarted/writingdocs/styleguidemd/styleguide02.md +++ /dev/null @@ -1,66 +0,0 @@ -Bullets, Bold and Italics -========================= - -Bold text can be show with **Bold Text**, Italics with *Italic text*. -Bullets like so: - -- Bullet 1 -- Bullet 2 - -Code Blocks -=========== - -This paragraph describes how to do **Console Commands**. When showing -VPP commands it is recommended that the command be executed from the -linux console as shown. The Highlighting in the final documents shows up -nicely this way. - -``` 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. - -``` 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/styleguidemd/styleguide03.md b/docs/gettingstarted/writingdocs/styleguidemd/styleguide03.md deleted file mode 100644 index 4c66dc4de33..00000000000 --- a/docs/gettingstarted/writingdocs/styleguidemd/styleguide03.md +++ /dev/null @@ -1,32 +0,0 @@ -Labels, References -================== - -A link or reference to other paragraphs within these documents can be -done with following construct. - -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. - - - -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 | |