Doc init

_modules/nuts.py

@@ -191,7 +191,7 @@ def bandwidth(dest):
 
 def dnscheck(param):
     '''
-    Retruns if a domain is resolvable on the minion
+    Returns true if a domain is resolvable on the minion
     command `nslookup` is needed
 
     RedHat/Centos: sudo yum install bind-utils
@@ -229,8 +229,6 @@ def dhcpcheck(dest):
     Pings the dhcp server and return True when a server response is recieved
     command `dhcping` is needed
 
-    RedHat/Centos: sudo yum install bind-utils
-
     CLI Example:
 
     .. code-block:: bash
@@ -343,7 +341,13 @@ def checkuser():
 
     .. code-block:: python
 
-        ????????????????????????????????????????????????
+        {
+            "result": [
+                "user01",
+                "user02"
+            ],
+            "resulttype": "multiple"
+        }
 
     :return:
     '''

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = Nuts
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/source/conf.py

@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+#
+# Nuts documentation build configuration file, created by
+# sphinx-quickstart on Mon Aug 28 19:32:21 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.viewcode',
+              'sphinx.ext.githubpages']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Nuts'
+copyright = u'2017, Urs Baumann'
+author = u'Urs Baumann'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'1.2'
+# The full version, including alpha/beta/rc tags.
+release = u'1.2.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+        'donate.html',
+    ]
+}
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Nutsdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'Nuts.tex', u'Nuts Documentation',
+     u'Urs Baumann', 'manual'),
+]
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'nuts', u'Nuts Documentation',
+     [author], 1)
+]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'Nuts', u'Nuts Documentation',
+     author, 'Nuts', 'One line description of project.',
+     'Miscellaneous'),
+]

doc/source/index.rst

@@ -0,0 +1,118 @@
+.. Nuts documentation master file, created by
+   sphinx-quickstart on Mon Aug 28 19:32:21 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+================================
+Welcome to Nuts's documentation!
+================================
+
+Nuts - Network Unit Testing System
+==================================
+.. image:: https://travis-ci.org/HSRNetwork/Nuts.svg?branch=master
+    :alt: Build status
+    :target: https://travis-ci.org/HSRNetwork/Nuts
+
+.. image:: https://img.shields.io/pypi/v/nuts.svg
+    :alt: PyPi Version
+    :target: https://pypi.python.org/pypi/nuts
+
+.. image:: https://img.shields.io/pypi/pyversions/nuts.svg
+    :alt: PyPi Python Versions
+    :target: https://pypi.python.org/pypi/nuts
+
+.. image:: https://img.shields.io/pypi/wheel/nuts.svg
+    :alt: PyPi wheel
+    :target: https://pypi.python.org/pypi/nuts
+
+.. image:: https://img.shields.io/pypi/l/nuts.svg
+    :alt: PyPi Licence
+    :target: https://pypi.python.org/pypi/nuts
+
+Nuts is a network unit testing system, that automates tests in the network similar to unit tests you might know from programming.
+The project uses SaltStack and napalm for the communication with the network devices. Normal Salt minions are used for Linux devices.
+This project is currently under heavy construction and we can't guarantee you that this code works. But we do our best.
+If you have any question, feature request or use cases please reach out to https://github.com/HSRNetwork/Nuts or join https://networktocode.slack.com/
+
+
+How do you decide a network change was successful? Hopefully you have a test protocol and can do all the necessary test
+on every touched box. When no test protocol is available you end up with jumping from device to device cli and
+do some random pings and show command. For example, verifying if you BGP sessions are up and running. After that,
+you will do maybe some pings from the client side. But are you confident you did no mistakes? Can you preempt side effects?
+It’s 4 o’clock in the morning and you must decide if you can close the maintenance window or more tests are needed.
+
+In a perfect world, the Network Engineer is sleeping well at 4 o’clock in the morning,
+network automation is doing the approved change and if the change fails, a rollback is triggered.
+On fail and success, a report is generated and the change is documented.
+The network engineer is happy, network is happy and the customers are happy.
+Engineers can do more engineering stuff and less operations.
+
+For the perfect world, you must be able do decide whether a change was successful or not.
+So, what is the definition of success? Of course, if the network is working as expected and the change has no side effects.
+If we break DHCP in the VoIP subnet after a Firewall change, the phones will lose the connectivity after the lease is timed out.
+If we not test DHCP explicit from this segment, we will not get notice about the issue before the first phone is disconnected.
+
+To avoid side effects, software developer use since decades unit test and integration test.
+Every feature gets his own tests and when someone adds a feature in the future, he can just run the test and
+when all test passed, the old features should work as expected. Depending on the test quality.
+
+So, let’s do the same in the network environment. Write some tests you can run (automatically) after a change to avoid side effects.
+Like an automated test protocol and you will not forget to test anything.
+
+Nuts supports different test involving network devices and/or Linux clients.
+
+Network Engineers write the test in a easy readable YAML file. For example to test if you receive a virtual HSRP MAC address.
+
+.. code:: yaml
+
+ - name: example_arp
+   command: arp
+   devices: cisco.csr.1000v
+   parameter: ['192.168.16.128']
+   operator: '='
+   expected: '00:0C:29:EA:D1:68'
+
+Or you can use a raspberry pi with sub interfaces to test https from a specific segment:
+
+.. code:: yaml
+
+ - name: http_access_vlan_10
+   command: webresponse
+   devices: raspberry01
+   parameter: ['https://github.com']
+   operator: '='
+   expected: True
+   setup:
+     - command: cmd.run
+       parameter: ['ip route add 10.10.0.0/16 via 192.168.50.1 dev eth0.10']
+       devices: raspberry01
+   teardown:
+     - command: cmd.run
+       parameter: ['ip route del 10.10.0.0/16 via 192.168.50.1 dev eth0.10']
+       devices: raspberry01
+
+You can validate a test file first or just start the tests and wait for the result.
+
+.. code:: bash
+
+ nuts /path/to/my/testfile.yml
+
+
+
+Documentation
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   install/index
+   tests/index
+   usecases/index
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`