diff options
Diffstat (limited to 'docs/gettingstarted/writingdocs')
20 files changed, 1260 insertions, 0 deletions
diff --git a/docs/gettingstarted/writingdocs/buildingrst.rst b/docs/gettingstarted/writingdocs/buildingrst.rst new file mode 100644 index 00000000000..00f051c30b7 --- /dev/null +++ b/docs/gettingstarted/writingdocs/buildingrst.rst @@ -0,0 +1,236 @@ +.. _buildingrst: + +********************** +Building VPP Documents +********************** + +Overview +======== + +These instructions show how the VPP documentation sources are built. + +FD.io VPP Documentation uses `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ (rst) files, which are used by `Sphinx <http://www.sphinx-doc.org/en/master/>`_. +We will also cover how to view your build on Read the Docs in `Using Read the Docs`_. + + +To build your files, you can either `Create a Virtual Environment using virtualenv`_, which installs all the required applications for you, or you can `Install Sphinx manually`_. + +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/ + +Get the Documents +^^^^^^^^^^^^^^^^^ + +For example start with a clone of the vpp-docs. + +.. code-block:: console + + $ git clone https://gerrit.fd.io/r/vpp + $ cd vpp + + +Install the virtual environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In your vpp-docs directory, run: + +.. code-block:: console + + $ python -m pip install --user virtualenv + $ python -m virtualenv env + $ source env/bin/activate + $ pip install -r docs/etc/requirements.txt + $ cd docs + +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 +^^^^^^^^^^^^^^^^^^^^ + +Be sure you are in your vpp-docs/docs directory, since that is where Sphinx will look for your **conf.py** +file, and build the **.rst** files into an **index.html** file: + +.. code-block:: console + + $ make html + +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 + + +Install Sphinx manually +_______________________ + +Skip this step if you created a *virtualenv* in the previous step. If you dont want to create a *virtualenv*, you should install Sphinx `here <http://www.sphinx-doc.org/en/master/usage/installation.html>`_, and follow their `getting started guide <http://www.sphinx-doc.org/en/master/usage/quickstart.html>`_. + +Building these files will generate an **index.html** file, which you can then view in your browser to verify and see your file changes. + + +To *build* your files, make sure you're in your **vpp-docs/docs** directory, where your **conf.py** file is located, and run: + +.. code-block:: console + + $ make html + + +| If there are no errors during the build process, you should now have an **index.html** file in your +| **vpp-docs/docs/_build/html** directory, which you can then view in your browser. + +.. figure:: /_images/htmlBuild.png + :scale: 35% + :align: center + +Whenever you make changes to your **.rst** files that you want to see, repeat this build process. + + +Using Read the Docs +___________________ + +`Read the Docs <https://readthedocs.org/>`_ is a website that "simplifies software documentation by automating building, versioning, and hosting of your docs for you". Essentially, it accesses your Github repo to generate the **index.html** file, and then displays it on its own *Read the Docs* webpage so others can view your documentation. + +Create an account on *Read the Docs* if you haven't already. + +Go to your `dashboard <https://readthedocs.org/dashboard/>`_ , and click on "Import a Project". + +.. figure:: /_images/importReadDocs.png + :scale: 35% + :align: left + + This will bring you to a page where you can choose to import a repo from your Github account (only if you've linked your Github account to your Read the Docs account), or to import a repo manually. In this example, we'll do it manually. Click "Import Manually". + +| +| +| +| +| +| +| + + + +This will bring you to a page that asks for your repo details. Set "Name" to your forked repo name, or whatever you want. Set "Repository URL" to the URL of your forked repo (https://github.com/YOURUSERNAME/vpp-docs). "Repository type" should already be selected to "Git". Then click "Next". + + +.. figure:: /_images/importRTDManually.png + :scale: 35% + :align: left + +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| + + +This will bring you to a project page of your repo on Read the Docs. You can confirm it's the correct repo by checking on the right side of the page the Repository URL. + +Then click on "Build Version". + +.. figure:: /_images/buildVerRTD.png + :scale: 35% + :align: left + +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| + +Which takes you to another page showing your recent builds. + +Then click on "Build Version:". This should "Trigger" a build. After about a minute or so you can refresh the page and see that your build "Passed". + + +.. figure:: /_images/passedBuild.png + :scale: 35% + :align: left + + +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| + + +Now on your builds page from the previous image, you can click "View Docs" at the top-right, which will take you a *readthedocs.io* page of your generated build! + +.. figure:: /_images/rtdWebpage.png + :scale: 30% + :align: left diff --git a/docs/gettingstarted/writingdocs/gitreview.rst b/docs/gettingstarted/writingdocs/gitreview.rst new file mode 100644 index 00000000000..63916e1d752 --- /dev/null +++ b/docs/gettingstarted/writingdocs/gitreview.rst @@ -0,0 +1,72 @@ +.. _gitreview: + +*************************** +Merging FD.io VPP documents +*************************** + +This section describes how to get FD.io VPP documents reviewed and merged. + +Git Review +========== + +The VPP documents use the gerrit server and git review. + +Clone with ssh +-------------- + +To get FD.io VPP documents reviewed the VPP repository should be cloned with ssh. + +Use the following to setup you ssh key + +.. code-block:: console + + $ ssh-keygen -t rsa + $ keychain + $ cat ~/.ssh/id_rsa.pub + +Copy that key to the gerrit server. +Then clone the repo with: + +.. code-block:: console + + $ git clone ssh://gerrit.fd.io:29418/vpp + $ cd vpp + +New patch +-------------- + +To get a new patch reviewed use the following: + +.. code-block:: console + + git status + git add <filename> + git commit -s + git review + +If the patch is a draft use the following: + +.. note:: + + git review -D + + +To get back to the master: + +.. code-block:: console + + git reset --hard origin/master + git checkout master + +Existing patch +-------------- + +To modify an existing patch: + + +.. code-block:: console + + git status + git add <filename> + git commit --amend + git review diff --git a/docs/gettingstarted/writingdocs/index.rst b/docs/gettingstarted/writingdocs/index.rst new file mode 100644 index 00000000000..e1ce767e40e --- /dev/null +++ b/docs/gettingstarted/writingdocs/index.rst @@ -0,0 +1,18 @@ +.. _writingdocs: + +######################### +Writing VPP Documentation +######################### + +.. toctree:: + + buildingrst + gitreview + readthedocs + styleguide/index.rst + styleguidemd/index.rst + todo + pushingapatch + + + diff --git a/docs/gettingstarted/writingdocs/pushingapatch.rst b/docs/gettingstarted/writingdocs/pushingapatch.rst new file mode 100644 index 00000000000..d0d5ec23888 --- /dev/null +++ b/docs/gettingstarted/writingdocs/pushingapatch.rst @@ -0,0 +1,237 @@ +.. _pushingapatch: + +================= +Github Repository +================= + +**The github repository is no longer being used. The gerrit server is being used.** + +To use the gerrit repository refer to :ref:`gitreview`. + +Overview +________ + +This section will cover how to fork your own branch of the `fdioDocs/vpp-docs <https://github.com/fdioDocs/vpp-docs>`_ repository, clone that repo locally to your computer, make changes to it, and how to issue a pull request when you want your changes to be reflected on the main repo. + +.. toctree:: + +Forking your own branch +_______________________ + +In your browser, navigate to the repo you want to branch off of. In this case, the `fdioDocs/vpp-docs <https://github.com/fdioDocs/vpp-docs>`_ repo. At the top right of the page you should see this: + +.. figure:: /_images/ForkButtons.png + :alt: Figure: Repository options on Github + :scale: 50% + :align: right + +| +| +| + +Click on "Fork", and then a pop-up should appear where you should then click your Github username. Once this is done, it should automatically take you to the Github page where your new branch is located, just like in the image below. + +.. figure:: /_images/usernameFork.png + :alt: Figure: Your own branch of the main repo on Github + :scale: 35% + :align: center + + +Now your **own branch** can be **cloned** to your computer using the URL (https://github.com/YOURUSERNAME/vpp-docs) of the Github page where your branch is located. + + +Creating a local repository +___________________________ + +Now that you have your own branch of the main repository on Github, you can store it locally on your computer. In your shell, navigate to the directory where you want to store your branch/repo. Then execute: + +.. code-block:: console + + $ git clone https://github.com/YOURUSERNAME/vpp-docs + +This will create a directory on your computer named **vpp-docs**, the name of the repo. + +Now that your branch is on your computer, you can modify and build files however you wish. + +If you are not on the master branch, move to it. + +.. code-block:: console + + $ git checkout master + + +Keeping your files in sync with the main repo +_____________________________________________ + +The following talks about remote branches, but keep in mind that there are currently *two* branches, your local "master" branch (on your computer), and your remote "origin or origin/master" branch (the one you created using "Fork" on the Github website). + +You can view your *remote* repositories with: + +.. code-block:: console + + $ git remote -v + +At this point, you may only see the remote branch that you cloned from. + +.. code-block:: console + + Macintosh:docs Andrew$ git remote -v + origin https://github.com/a-olechtchouk/vpp-docs (fetch) + origin https://github.com/a-olechtchouk/vpp-docs (push) + +Now you want to create a new remote repository of the main vpp-docs repo (naming it upstream). + +.. code-block:: console + + $ git remote add upstream https://github.com/fdioDocs/vpp-docs + + +You can verify that you have added a remote repo using the previous **git remote -v** command. + +.. code-block:: console + + $ git remote -v + origin https://github.com/a-olechtchouk/vpp-docs (fetch) + origin https://github.com/a-olechtchouk/vpp-docs (push) + upstream https://github.com/fdioDocs/vpp-docs (fetch) + upstream https://github.com/fdioDocs/vpp-docs (push) + + +If there have been any changes to files in the main repo (hopefully not the same files you were working on!), you want to make sure your local branch is in sync with them. + +To do so, fetch any changes that the main repo has made, and then merge them into your local master branch using: + +.. code-block:: console + + $ git fetch upstream + $ git merge upstream/master + + +.. note:: **This is optional, so don't do these commands if you just want one local branch!!!** + + You may want to have multiple branches, where each branch has its own different features, allowing you to have multiple pull requests out at a time. To create a new local branch: + +.. code-block:: shell + + $ git checkout -b cleanup-01 + $ git branch + * cleanup-01 + master + overview + + Now you can redo the previous steps for "Keeping your files in sync with the main repo" for your newly created local branch, and then depending on which branch you want to send out a pull reqest for, proceed below. + + +Pushing to your branch +______________________ + +Now that your files are in sync, you want to add modified files, commit, and push them from *your local branch* to your *personal remote branch* (not the main fdioDocs repo). + +To check the status of your files, run: + +.. code-block:: console + + $ git status + + +In the output example below, I deleted gettingsources.rst, made changes to index.rst and pushingapatch.rst, and have created a new file called buildingrst.rst. + +.. code-block:: console + + Macintosh:docs Andrew$ git status + On branch master + Your branch is up-to-date with 'origin/master'. + Changes to be committed: + (use "git reset HEAD <file>..." to unstage) + + deleted: tasks/writingdocs/gettingsources.rst + + Changes not staged for commit: + (use "git add <file>..." to update what will be committed) + (use "git checkout -- <file>..." to discard changes in working directory) + + modified: tasks/writingdocs/index.rst + modified: tasks/writingdocs/pushingapatch.rst + + Untracked files: + (use "git add <file>..." to include in what will be committed) + + tasks/writingdocs/buildingrst.rst + + + +To add files (use **git add -A** to add all modified files): + +.. code-block:: console + + $ git add FILENAME1 FILENAME2 + +Commit and push using: + +.. code-block:: console + + $ git commit -m 'A descriptive commit message for two files.' + +Push your changes for the branch where your changes were made + +.. code-block:: console + + $ git push origin <branch name> + +Here, your personal remote branch is "origin" and your local branch is "master". + +.. 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*. + + + +Initiating a pull request (Code review) +_______________________________________ + +Once you've pushed your changes to your remote branch, go to your remote branch on Github (https://github.com/YOURUSERNAME/vpp-docs), and click on "New pull request". + +.. figure:: /_images/issuePullReq.png + :alt: Figure: Your own branch of the main repo on Github + :scale: 35% + :align: center + +This will bring you to a "Comparing changes" page. Click "Create new pull request". + +.. figure:: /_images/createNewPullReq.png + :scale: 35% + :align: left + +| +| +| + +Which will open up text fields to add information to your pull request. + +.. figure:: /_images/examplePullReq.png + :scale: 35% + :align: center + + + Then finally click "Create pull request" to complete the pull request. + +Your documents will be reviewed. To this same branch make the changes requested from the review and then push your new changes. There is no need to create another pull request. + +.. code-block:: console + + $ git commit -m 'A descriptive commit message for the new changes' + $ git push origin <branch name> + + +Additional Git commands +_______________________ + +You may find some of these Git commands useful: + +Use **git diff** to quickly show the file changes and repo differences of your commits. + +Use **git rm FILENAME** to stop tracking a file and to remove it from your remote branch and local directory. Use flag **-r** to remove folders/directories. E.g (**git rm -r oldfolder**) + + +.. _fdioDocs: https://github.com/fdioDocs/vpp-docs + diff --git a/docs/gettingstarted/writingdocs/readthedocs.rst b/docs/gettingstarted/writingdocs/readthedocs.rst new file mode 100644 index 00000000000..f97b8d918b6 --- /dev/null +++ b/docs/gettingstarted/writingdocs/readthedocs.rst @@ -0,0 +1,130 @@ +.. _readthedocs: + +******************* +Using Read the Docs +******************* + +`Read the Docs <https://readthedocs.org/>`_ is a website that "simplifies software documentation by automating building, versioning, and hosting of your docs for you". Essentially, it accesses your Github repo to generate the **index.html** file, and then displays it on its own *Read the Docs* webpage so others can view your documentation. + +Create an account on *Read the Docs* if you haven't already. + +Go to your `dashboard <https://readthedocs.org/dashboard/>`_ , and click on "Import a Project". + +.. figure:: /_images/importReadDocs.png + :scale: 35% + :align: left + + This will bring you to a page where you can choose to import a repo from your Github account (only if you've linked your Github account to your Read the Docs account), or to import a repo manually. In this example, we'll do it manually. Click "Import Manually". + +| +| +| +| +| +| +| + + + +This will bring you to a page that asks for your repo details. Set "Name" to your forked repo name, or whatever you want. Set "Repository URL" to the URL of your forked repo (https://github.com/YOURUSERNAME/vpp-docs). "Repository type" should already be selected to "Git". Then click "Next". + + +.. figure:: /_images/importRTDManually.png + :scale: 35% + :align: left + +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| + + +This will bring you to a project page of your repo on Read the Docs. You can confirm it's the correct repo by checking on the right side of the page the Repository URL. + +Then click on "Build Version". + +.. figure:: /_images/buildVerRTD.png + :scale: 35% + :align: left + +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| + +Which takes you to another page showing your recent builds. + +Then click on "Build Version:". This should "Trigger" a build. After about a minute or so you can refresh the page and see that your build "Passed". + + +.. figure:: /_images/passedBuild.png + :scale: 35% + :align: left + + +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| +| + + +Now on your builds page from the previous image, you can click "View Docs" at the top-right, which will take you a *readthedocs.io* page of your generated build! + +.. figure:: /_images/rtdWebpage.png + :scale: 30% + :align: left 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 + diff --git a/docs/gettingstarted/writingdocs/styleguidemd/index.rst b/docs/gettingstarted/writingdocs/styleguidemd/index.rst new file mode 100644 index 00000000000..5bafb4d1512 --- /dev/null +++ b/docs/gettingstarted/writingdocs/styleguidemd/index.rst @@ -0,0 +1,15 @@ +.. _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:: + + styleguide.md + styleguide02.md + styleguide03.md diff --git a/docs/gettingstarted/writingdocs/styleguidemd/styleguide.md b/docs/gettingstarted/writingdocs/styleguidemd/styleguide.md new file mode 100644 index 00000000000..31ea822ca13 --- /dev/null +++ b/docs/gettingstarted/writingdocs/styleguidemd/styleguide.md @@ -0,0 +1,13 @@ +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 new file mode 100644 index 00000000000..b297d328082 --- /dev/null +++ b/docs/gettingstarted/writingdocs/styleguidemd/styleguide02.md @@ -0,0 +1,66 @@ +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 reccomended 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 new file mode 100644 index 00000000000..462006fd6f3 --- /dev/null +++ b/docs/gettingstarted/writingdocs/styleguidemd/styleguide03.md @@ -0,0 +1,22 @@ +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. + + diff --git a/docs/gettingstarted/writingdocs/todo.rst b/docs/gettingstarted/writingdocs/todo.rst new file mode 100644 index 00000000000..6c722986c24 --- /dev/null +++ b/docs/gettingstarted/writingdocs/todo.rst @@ -0,0 +1,60 @@ +.. _todo: + +***** +To Do +***** + +This section describes pieces of these documents that need some work. + +All Sections +============ + +All the sections need to be spell checked. + +Checked for guidelines. + +:ref:`vhost` +============ + +:ref:`vhosttopo` +---------------- + +Get a better topology picture. + +:ref:`vhost02` +-------------- + +The XML file refers to an iso image, come up with a procedure to build that image. +That should work when used with a cloud image. It should also be mentioned where +to get a cloud image. + +It is mentioned that a queue size of 256 is not large enough. Come up wit a procedure +to change the queue size. + + +:ref:`users` +============ + +The getting started users guide needs an overview + +:ref:`cmdreference` +=================== + +This section should be references to the doxygen links. The doxygen links will need to be cleaned up. +This section could be a quick reference only using commands we have tested. + +:ref:`progressivevpp` +===================== + +This section needs work. It needs to be split up and tested. + +:ref:`vswitchrtr` +================= + +Needs some instructions or be removed. + +:ref:`jvppjar` +============== + +Not sure what value this provides. + |