Docs final (#132)

* add link to brg-tools * fix docstring * fix typo * rearrange docs * fix generated docs for configuration section * fix path * fix paths
nornir-automation · May 3, 2018 · 0998485 · 0998485
1 parent 6a667c7
commit 0998485
Show file tree

Hide file tree

Showing 33 changed files with 44 additions and 83 deletions.
diff --git a/.gitignore b/.gitignore
@@ -64,7 +64,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/ref/configuration/generated/*.rst
+docs/configuration/generated/*.rst
 
 # PyBuilder
 target/
@@ -105,4 +105,4 @@ output/
 .vscode
 
 # Generated when testing
-nsot-docker.sqlite3
+nsot-docker.sqlite3
diff --git a/README.md b/README.md
@@ -24,6 +24,11 @@ Documentation
 
 Read the [Brigade documentation](https://brigade.readthedocs.io/) online or review it's [code here](https://github.com/brigade-automation/brigade/tree/develop/docs)
 
+Examples
+========
+
+You can find some examples and already made tools [here](https://github.com/brigade-automation/brg-tools/)
+
 
 Bugs & New features
 ===================

diff --git a/brigade/plugins/functions/text/__init__.py b/brigade/plugins/functions/text/__init__.py
@@ -63,8 +63,7 @@ def print_result(
         result (:obj:`brigade.core.task.Result`): from a previous task
         vars (list of str): Which attributes you want to print
         failed (``bool``): if ``True`` assume the task failed
-        task_id (``int``): if we have a :obj:`brigade.core.task.MultiResult` print
-            only task in this position
+        severity_level (int): Print only errors with this severity level or higher
 
     Returns:
         :obj:`brigade.core.task.Result`:

diff --git a/docs/conf.py b/docs/conf.py
@@ -181,7 +181,7 @@ def build_configuration_parameters(app):
     data = {}
     data["params"] = CONF
     rendered_template = template_file.render(**data)
-    output_dir = "{0}/ref/configuration/generated".format(BASEPATH)
+    output_dir = "{0}/configuration/generated".format(BASEPATH)
     with open("{}/parameters.rst".format(output_dir), "w") as f:
         f.write(rendered_template)
 

diff --git a/.../ref/configuration/generated/.placeholder → docs/configuration/generated/.placeholder b/.../ref/configuration/generated/.placeholder → docs/configuration/generated/.placeholder
diff --git a/docs/ref/configuration/index.rst → docs/configuration/index.rst b/docs/ref/configuration/index.rst → docs/configuration/index.rst
@@ -1,10 +1,10 @@
-Brigade Configuration
-=====================
+Configuration
+=============
 
 Each configuration parameter are applied in the following order:
 
 1. Environment variable
 2. Parameter in configuration file / object
 3. Default value
 
-.. include:: generated/parameters.rst
+.. include:: generated/parameters.rst
diff --git a/docs/howto/writing_a_connection_task.rst b/docs/howto/writing_a_connection_task.rst
@@ -1,7 +1,7 @@
 Writing a connection task
 #########################
 
-Connection tasks are tasks that establish a connection with a device to provide some sort of reusable mechanism to interact with it. You can find some examples of connections tasks in the :doc:`../ref/tasks/connections` section.
+Connection tasks are tasks that establish a connection with a device to provide some sort of reusable mechanism to interact with it. You can find some examples of connections tasks in the :doc:`../plugins/tasks/connections` section.
 
 Writing a connection task is no different from writing a regular task. The only difference is that the task will have to establish the connection and assign it to the device.
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -30,64 +30,22 @@ Is something missing from the documentation? Please open an issue and `tell us w
 A first glance
 ==============
 
-Here is an example on how to quickly build a cli tool leveraging on Brigade and click::
+Here is an example on how to quickly build a runbook leveraging Brigade to retrieve information from the network::
 
-    from brigade.core import Brigade
-    from brigade.plugins import tasks
-    from brigade.plugins.inventory.simple import SimpleInventory
+    from brigade.core import InitBrigade
+    from brigade.plugins.functions.text import print_result
+    from brigade.plugins.tasks.networking import napalm_get
 
-    import click
+    brg = InitBrigade(
+        config_file="brigade.yaml", dry_run=True, num_workers=20
+    )
 
+    results = brg.run(
+        task=napalm_get, getters=["facts", "interfaces"]
+    )
+    print_result(results)
 
-    def get_facts(task, facts):
-        r = tasks.napalm_get_facts(task, facts)
-        print(task.host.name)
-        print("============")
-        print(r["result"])
-        print()
-
-
-    @click.command()
-    @click.argument('site')
-    @click.argument('role')
-    @click.argument('facts')
-    def main(site, role, facts):
-        brigade = Brigade(
-            inventory=SimpleInventory("hosts.yaml", "groups.yaml"),
-            dry_run=True,
-        )
-
-        filtered = brigade.filter(site=site, role=role)
-        filtered.run(task=get_facts,
-                     facts=facts)
-
-
-    if __name__ == "__main__":
-        main()
-
-That you can use like:
-
-* give me general information from all my leafs in bma::
-
-    $ ./get_facts_role.py bma leaf get_facts
-    switch00.bma
-    ============
-    {'hostname': 'switch00.bma', 'fqdn': 'switch00.bma.bma.acme.com', 'vendor': 'Arista', 'model': 'vEOS', 'serial_number': '', 'os_version': '4.17.5M-4414219.4175M', 'uptime': 80747, 'interface_list': ['Ethernet1', 'Ethernet2', 'Management1']}
-    
-    switch01.bma
-    ============
-    {'vendor': 'Juniper', 'model': 'FIREFLY-PERIMETER', 'serial_number': 'a7defdc362ff', 'os_version': '12.1X47-D20.7', 'hostname': 'switch01.bma', 'fqdn': 'switch01.bma.bma.acme.com', 'uptime': 80644, 'interface_list': ['ge-0/0/0', 'gr-0/0/0', 'ip-0/0/0', 'lsq-0/0/0', 'lt-0/0/0', 'mt-0/0/0', 'sp-0/0/0', 'ge-0/0/1', 'ge-0/0/2', '.local.', 'dsc', 'gre', 'ipip', 'irb', 'lo0', 'lsi', 'mtun', 'pimd', 'pime', 'pp0', 'ppd0', 'ppe0', 'st0', 'tap', 'vlan']}
-
-* give me interface information from all my leafs in cmh::
-
-    $ ./get_facts_role.py cmh leaf interfaces
-    switch00.cmh
-    ============
-    {'Ethernet2': {'is_up': False, 'is_enabled': False, 'description': 'Another interface in bma', 'last_flapped': 1511034159.0400283, 'speed': 0, 'mac_address': '08:00:27:AB:42:B6'}, 'Management1': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': 1511033376.7964902, 'speed': 1000, 'mac_address': '08:00:27:47:87:83'}, 'Ethernet1': {'is_up': True, 'is_enabled': True, 'description': 'An Interface in bma', 'last_flapped': 1511033362.0303102, 'speed': 0, 'mac_address': '08:00:27:2D:F4:5A'}}
-    
-    switch01.cmh
-    ============
-    {'ge-0/0/0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': 80603.0, 'mac_address': '08:00:27:AA:8C:76', 'speed': 1000}, 'gr-0/0/0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': 800}, 'ip-0/0/0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': 800}, 'lsq-0/0/0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': 80604.0, 'mac_address': 'None', 'speed': -1}, 'lt-0/0/0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': '02:96:14:8C:76:B3', 'speed': 800}, 'mt-0/0/0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': 800}, 'sp-0/0/0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': 80604.0, 'mac_address': 'Unspecified', 'speed': 800}, 'ge-0/0/1': {'is_up': True, 'is_enabled': True, 'description': 'An Interface in bma', 'last_flapped': 80604.0, 'mac_address': '08:00:27:FB:F0:FC', 'speed': 1000}, 'ge-0/0/2': {'is_up': False, 'is_enabled': False, 'description': 'Another interface in bma', 'last_flapped': 79892.0, 'mac_address': '08:00:27:32:60:54', 'speed': 1000}, '.local.': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'Unspecified', 'speed': -1}, 'dsc': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'Unspecified', 'speed': -1}, 'gre': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': -1}, 'ipip': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': -1}, 'irb': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': '4C:96:14:8C:76:B0', 'speed': -1}, 'lo0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'Unspecified', 'speed': -1}, 'lsi': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'Unspecified', 'speed': -1}, 'mtun': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': -1}, 'pimd': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': -1}, 'pime': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': -1}, 'pp0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'Unspecified', 'speed': -1}, 'ppd0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': 800}, 'ppe0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': 800}, 'st0': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'None', 'speed': -1}, 'tap': {'is_up': True, 'is_enabled': True, 'description': '', 'last_flapped': -1.0, 'mac_address': 'Unspecified', 'speed': -1}, 'vlan': {'is_up': False, 'is_enabled': True, 'description': '', 'last_flapped': 80614.0, 'mac_address': '00:00:00:00:00:00', 'speed': 1000}}
+You can find this and other examples `here <https://github.com/brigade-automation/brg-tools/>`_.
 
 Contents
 ========
@@ -98,6 +56,8 @@ Contents
    Home <self>
    Tutorials <tutorials/intro/index>
    Howto <howto/index>
+   configuration/index
+   plugins/index
    ref/index
    Contribute <contributing/index>
 

diff --git a/docs/ref/functions/index.rst → docs/plugins/functions/index.rst b/docs/ref/functions/index.rst → docs/plugins/functions/index.rst
diff --git a/docs/ref/functions/text.rst → docs/plugins/functions/text.rst b/docs/ref/functions/text.rst → docs/plugins/functions/text.rst
diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
@@ -0,0 +1,11 @@
+Plugins
+=======
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Plugins
+
+   tasks/index
+   functions/index
+   inventory/index
+
diff --git a/docs/ref/inventory/ansible.rst → docs/plugins/inventory/ansible.rst b/docs/ref/inventory/ansible.rst → docs/plugins/inventory/ansible.rst
diff --git a/docs/ref/inventory/index.rst → docs/plugins/inventory/index.rst b/docs/ref/inventory/index.rst → docs/plugins/inventory/index.rst
diff --git a/docs/ref/inventory/nsot.rst → docs/plugins/inventory/nsot.rst b/docs/ref/inventory/nsot.rst → docs/plugins/inventory/nsot.rst
diff --git a/docs/ref/inventory/simple.rst → docs/plugins/inventory/simple.rst b/docs/ref/inventory/simple.rst → docs/plugins/inventory/simple.rst
diff --git a/docs/ref/tasks/apis.rst → docs/plugins/tasks/apis.rst b/docs/ref/tasks/apis.rst → docs/plugins/tasks/apis.rst
diff --git a/docs/ref/tasks/commands.rst → docs/plugins/tasks/commands.rst b/docs/ref/tasks/commands.rst → docs/plugins/tasks/commands.rst
diff --git a/docs/ref/tasks/connections.rst → docs/plugins/tasks/connections.rst b/docs/ref/tasks/connections.rst → docs/plugins/tasks/connections.rst
diff --git a/docs/ref/tasks/data.rst → docs/plugins/tasks/data.rst b/docs/ref/tasks/data.rst → docs/plugins/tasks/data.rst
diff --git a/docs/ref/tasks/files.rst → docs/plugins/tasks/files.rst b/docs/ref/tasks/files.rst → docs/plugins/tasks/files.rst
diff --git a/docs/ref/tasks/index.rst → docs/plugins/tasks/index.rst b/docs/ref/tasks/index.rst → docs/plugins/tasks/index.rst
diff --git a/docs/ref/tasks/networking.rst → docs/plugins/tasks/networking.rst b/docs/ref/tasks/networking.rst → docs/plugins/tasks/networking.rst
diff --git a/docs/ref/tasks/text.rst → docs/plugins/tasks/text.rst b/docs/ref/tasks/text.rst → docs/plugins/tasks/text.rst
diff --git a/docs/ref/api/configuration.rst b/docs/ref/api/configuration.rst
@@ -6,4 +6,4 @@ Configuration
    :members:
    :undoc-members:
 
-The attributes for the Config object will be the Brigade configuration parameters. For a list of available parameters see :doc:`Brigade configuration parameters </ref/configuration/index>`
+The attributes for the Config object will be the Brigade configuration parameters. For a list of available parameters see :doc:`Brigade configuration parameters </configuration/index>`
diff --git a/docs/ref/index.rst b/docs/ref/index.rst
@@ -12,17 +12,3 @@ Reference Guides
    :caption: Brigade API
 
    API <api/index>
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Configuration
-
-   configuration/index
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Plugins
-
-   tasks/index
-   functions/index
-   inventory/index
diff --git a/docs/ref/internals/_static/execution_model.graffle b/docs/ref/internals/_static/execution_model.graffle
diff --git a/docs/ref/internals/_static/execution_model_1.png b/docs/ref/internals/_static/execution_model_1.png
diff --git a/docs/ref/internals/_static/execution_model_2.png b/docs/ref/internals/_static/execution_model_2.png
diff --git a/docs/tutorials/intro/executing_tasks.ipynb b/docs/tutorials/intro/executing_tasks.ipynb
@@ -18,7 +18,7 @@
     "\n",
     "Now that you know how to initialize brigade and work with the inventory let's see how we can leverage it to run tasks on groups of hosts.\n",
     "\n",
-    "Brigade ships a bunch of tasks you can use directly without having to code them yourself. You can check them out [here](../../ref/tasks/index.rst).\n",
+    "Brigade ships a bunch of tasks you can use directly without having to code them yourself. You can check them out [here](../../plugins/tasks/index.rst).\n",
     "\n",
     "Let's start by executing the `ls -la /tmp` command on all the device in `cmh` of type `host`:\n"
    ]

diff --git a/docs/tutorials/intro/grouping_tasks.ipynb b/docs/tutorials/intro/grouping_tasks.ipynb
@@ -8,7 +8,7 @@
     "\n",
     "In this section we are going to see how we can group tasks. Grouping tasks might be useful for various reasons, for instance, for reusability purposes (as seen in a previous section) or even just for readability purposes. \n",
     "\n",
-    "We will also see very briefly how to use the functions [functions.text.print_title](../../ref/functions/text.rst#brigade.plugins.functions.text.print_title) and [functions.text.print_result](../../ref/functions/text.rst#brigade.plugins.functions.text.print_result) to make things look pretty.\n",
+    "We will also see very briefly how to use the functions [functions.text.print_title](../../plugins/functions/text.rst#brigade.plugins.functions.text.print_title) and [functions.text.print_result](../../plugins/functions/text.rst#brigade.plugins.functions.text.print_result) to make things look pretty.\n",
     "\n",
     "As an objective in this tutorial we are going to be configuring the hostname and domain name of our network devices.\n",
     "\n",

diff --git a/docs/tutorials/intro/initializing_brigade.ipynb b/docs/tutorials/intro/initializing_brigade.ipynb
@@ -22,7 +22,7 @@
     "\n",
     "With `InitBrigade` you can initialize brigade with a configuration file, with code or with a combination of both.\n",
     "\n",
-    "Let's start with [a configuration file](../../ref/configuration/index.rst):"
+    "Let's start with [a configuration file](../../configuration/index.rst):"
    ]
   },
   {

diff --git a/docs/tutorials/intro/inventory.ipynb b/docs/tutorials/intro/inventory.ipynb
@@ -20,7 +20,7 @@
     "\n",
     "The Inventory is arguably the most important piece of brigade. Let's see how it works. To begin with the [inventory](../../ref/api/inventory.rst#brigade.core.inventory.Inventory) is comprised of [hosts](../../ref/api/inventory.rst#brigade.core.inventory.Host) and [groups](../../ref/api/inventory.rst#brigade.core.inventory.Group).\n",
     "\n",
-    "In this tutorial we are using the [SimpleInventory](../../ref/inventory/simple.rst#brigade.plugins.inventory.simple.SimpleInventory) plugin. This inventory plugin stores all the relevant data in two files. Let's start by checking them:"
+    "In this tutorial we are using the [SimpleInventory](../../plugins/inventory/simple.rst#brigade.plugins.inventory.simple.SimpleInventory) plugin. This inventory plugin stores all the relevant data in two files. Let's start by checking them:"
    ]
   },
   {

diff --git a/docs/tutorials/intro/task_results.ipynb b/docs/tutorials/intro/task_results.ipynb
@@ -66,7 +66,7 @@
    "source": [
     "## The easy way\n",
     "\n",
-    "Most of the time you will just want to provide some feedback on what's going on. For that you can use [print_result](../../ref/functions/text.rst#brigade.plugins.functions.text.print_result) function:"
+    "Most of the time you will just want to provide some feedback on what's going on. For that you can use [print_result](../../plugins/functions/text.rst#brigade.plugins.functions.text.print_result) function:"
    ]
   },
   {
-Original file line number
+Diff line change
@@ Expand Up / @@ -22,7 +22,7 @@ @@
         "\n",
         "With `InitBrigade` you can initialize brigade with a configuration file, with code or with a combination of both.\n",
         "\n",
-        "Let's start with [a configuration file](../../ref/configuration/index.rst):"
+        "Let's start with [a configuration file](../../configuration/index.rst):"
        ]
       },
       {
@@ Expand Down @@