Inventory rework

docs/_data_templates/configuration-parameters.j2

@@ -1,29 +1,29 @@
-The configuration parameters will be set by the :doc:`Nornir.core.configuration.Config </ref/api/configuration>` class.
+{% macro document_section(section, schema) %}
+{{ section }}
+{{ "-" * section|length }}
 
-{% for k, v in params|dictsort %}
-----------
+{% for k, v in schema["properties"].items() -%}
 
-{{ k }}
-----------------------------------
+``{{ k }}``
+{{ "_" * (k|length + 4) }}
 
+.. list-table::
+   :widths: 15 85
 
-.. raw:: html
+   * - **Description**
+     - {{ v["description"] }}
+   * - **Type**
+     - ``{{ v["type"] }}``
+   * - **Default**
+     - {{ "``{}``".format(v["default"]) if v["default"] else "" }}
+   * - **Required**
+     - ``{{ v["required"] }}``
+   * - **Environment Variable**
+     - ``{{ "NORNIR_{}_{}".format(section, k).upper() }}``
 
-	<table border="1" class="docutils">
-		<th>Environment variable</th>
-		<th>Type</th>
-		<th>Default</th>
-			<tr>
-			{% if v['type'] in ('str', 'int', 'bool') %}
-				<td>{{ v['env'] or 'BRIGADE_' + k|upper }}</td>
-			{% else %}
-				<td>N/A</td>
-			{% endif %}
-				<td>{{ v['type'] }}</td>
-				<td>{{ v['default_doc'] or v['default'] }}</td>
-			</tr>
-	</table>
-
-{{ v['description'] }}
+{% endfor %}
+{%- endmacro %}
 
+{% for k, v in schema["properties"].items() if k not in ["user_defined"] %}
+{{ document_section(k, v) }}
 {% endfor %}

docs/conf.py

@@ -20,16 +20,15 @@
 import os
 import sys
 
-from jinja2 import Environment
-from jinja2 import FileSystemLoader
+from jinja2 import Environment, FileSystemLoader
 
 sys.path.insert(0, os.path.abspath("../"))
 
+from nornir.core.deserializer.configuration import Config  # noqa
 
-from nornir.core.configuration import CONF  # noqa
 
 # -- General configuration ------------------------------------------------
-BASEPATH = os.path.dirname(__file__)
+BASEPATH = os.path.abspath(os.path.dirname(__file__))
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
@@ -54,7 +53,7 @@
 
 # General information about the project.
 project = "nornir"
-copyright = "2017, David Barroso"
+copyright = "2018, David Barroso"
 author = "David Barroso"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -173,30 +172,26 @@
 ]
 
 
+def skip_slots(app, what, name, obj, skip, options):
+    if obj.__class__.__name__ == "member_descriptor":
+        return True
+    return None
+
+
 def build_configuration_parameters(app):
     """Create documentation for configuration parameters."""
-
     env = Environment(loader=FileSystemLoader("{0}/_data_templates".format(BASEPATH)))
     template_file = env.get_template("configuration-parameters.j2")
     data = {}
-    data["params"] = CONF
+    data["schema"] = Config.schema()
     rendered_template = template_file.render(**data)
     output_dir = "{0}/configuration/generated".format(BASEPATH)
     with open("{}/parameters.rst".format(output_dir), "w") as f:
         f.write(rendered_template)
 
 
-def skip_slots(app, what, name, obj, skip, options):
-    if obj.__class__.__name__ == "member_descriptor":
-        return True
-    return None
-
-
 def setup(app):
     """Map methods to states of the documentation build."""
     app.connect("builder-inited", build_configuration_parameters)
     app.connect("autodoc-skip-member", skip_slots)
     app.add_stylesheet("css/custom.css")
-
-
-build_configuration_parameters(None)

docs/configuration/index.rst

@@ -1,10 +1,25 @@
 Configuration
 =============
 
-Each configuration parameter are applied in the following order:
+The configuration is comprised of a set of sections and parameters for those sections. You can set the configuration programmatically using nornir by passing a dictionary of options for each section, by using a YAML file, by setting the corresponding environment variables or by a combination of the three. The order of preference from less to more preferred is "configuration file" -> "env variable" -> "code".
 
-1. Environment variable
-2. Parameter in configuration file / object
-3. Default value
+An example using ``InitNornir`` would be::
+
+    nr = InitNornir(
+        core={"num_workers": 20},
+        logging={"file": "mylogs", "level": "debug"}
+    )
+
+A similar example using a ``yaml`` file:
+
+.. include:: ../howto/advanced_filtering/config.yaml
+   :code: yaml
+
+Next, you can find each section and their corresponding options.
 
 .. include:: generated/parameters.rst
+
+user_defined
+------------
+
+You can set any ``<k, v>`` pair you want here and you will have it available under your configuration object, i.e. ``nr.config.user_defined.my_app_option``.

docs/howto/advanced_filtering.ipynb

@@ -15,7 +15,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from nornir.core import InitNornir\n",
+    "from nornir import InitNornir\n",
     "from nornir.core.filter import F\n",
     "\n",
     "nr = InitNornir(config_file=\"advanced_filtering/config.yaml\")"
@@ -32,76 +32,82 @@
      "text": [
       "---\r\n",
       "cat:\r\n",
-      "    domestic: true\r\n",
-      "    diet: omnivore\r\n",
       "    groups:\r\n",
       "        - terrestrial\r\n",
       "        - mammal\r\n",
-      "    additional_data:\r\n",
-      "        lifespan: 17\r\n",
-      "        famous_members:\r\n",
-      "            - garfield\r\n",
-      "            - felix\r\n",
-      "            - grumpy\r\n",
+      "    data:\r\n",
+      "        domestic: true\r\n",
+      "        diet: omnivore\r\n",
+      "        additional_data:\r\n",
+      "            lifespan: 17\r\n",
+      "            famous_members:\r\n",
+      "                - garfield\r\n",
+      "                - felix\r\n",
+      "                - grumpy\r\n",
       "\r\n",
       "bat:\r\n",
-      "    domestic: false\r\n",
-      "    fly: true\r\n",
-      "    diet: carnivore\r\n",
       "    groups:\r\n",
       "        - terrestrial\r\n",
       "        - mammal\r\n",
-      "    additional_data:\r\n",
-      "        lifespan: 15\r\n",
-      "        famous_members:\r\n",
-      "            - batman\r\n",
-      "            - count chocula\r\n",
-      "            - nosferatu\r\n",
+      "    data:\r\n",
+      "        domestic: false\r\n",
+      "        fly: true\r\n",
+      "        diet: carnivore\r\n",
+      "        additional_data:\r\n",
+      "            lifespan: 15\r\n",
+      "            famous_members:\r\n",
+      "                - batman\r\n",
+      "                - count chocula\r\n",
+      "                - nosferatu\r\n",
       "\r\n",
       "eagle:\r\n",
-      "    domestic: false\r\n",
-      "    diet: carnivore\r\n",
       "    groups:\r\n",
       "        - terrestrial\r\n",
       "        - bird\r\n",
-      "    additional_data:\r\n",
-      "        lifespan: 50\r\n",
-      "        famous_members:\r\n",
-      "            - thorondor\r\n",
-      "            - sam\r\n",
+      "    data:\r\n",
+      "        domestic: false\r\n",
+      "        diet: carnivore\r\n",
+      "        additional_data:\r\n",
+      "            lifespan: 50\r\n",
+      "            famous_members:\r\n",
+      "                - thorondor\r\n",
+      "                - sam\r\n",
       "\r\n",
       "canary:\r\n",
-      "    domestic: true\r\n",
-      "    diet: herbivore\r\n",
       "    groups:\r\n",
       "        - terrestrial\r\n",
       "        - bird\r\n",
-      "    additional_data:\r\n",
-      "        lifespan: 15\r\n",
-      "        famous_members:\r\n",
-      "            - tweetie\r\n",
+      "    data:\r\n",
+      "        domestic: true\r\n",
+      "        diet: herbivore\r\n",
+      "        additional_data:\r\n",
+      "            lifespan: 15\r\n",
+      "            famous_members:\r\n",
+      "                - tweetie\r\n",
       "\r\n",
       "caterpillaer:\r\n",
-      "    domestic: false\r\n",
-      "    diet: herbivore\r\n",
       "    groups:\r\n",
       "        - terrestrial\r\n",
       "        - invertebrate\r\n",
-      "    additional_data:\r\n",
-      "        lifespan: 1\r\n",
-      "        famous_members:\r\n",
-      "            - Hookah-Smoking\r\n",
+      "    data:\r\n",
+      "        domestic: false\r\n",
+      "        diet: herbivore\r\n",
+      "        additional_data:\r\n",
+      "            lifespan: 1\r\n",
+      "            famous_members:\r\n",
+      "                - Hookah-Smoking\r\n",
       "\r\n",
       "octopus:\r\n",
-      "    domestic: false\r\n",
-      "    diet: carnivore\r\n",
       "    groups:\r\n",
       "        - marine\r\n",
       "        - invertebrate\r\n",
-      "    additional_data:\r\n",
-      "        lifespan: 1\r\n",
-      "        famous_members:\r\n",
-      "            - sharktopus\r\n"
+      "    data:\r\n",
+      "        domestic: false\r\n",
+      "        diet: carnivore\r\n",
+      "        additional_data:\r\n",
+      "            lifespan: 1\r\n",
+      "            famous_members:\r\n",
+      "                - sharktopus\r\n"
      ]
     }
    ],
@@ -119,18 +125,20 @@
      "output_type": "stream",
      "text": [
       "---\r\n",
-      "defaults: {}\r\n",
       "mammal:\r\n",
-      "    reproduction: birth\r\n",
-      "    fly: false\r\n",
+      "    data:\r\n",
+      "        reproduction: birth\r\n",
+      "        fly: false\r\n",
       "\r\n",
       "bird:\r\n",
-      "    reproduction: eggs\r\n",
-      "    fly: true\r\n",
+      "    data:\r\n",
+      "        reproduction: eggs\r\n",
+      "        fly: true\r\n",
       "\r\n",
       "invertebrate:\r\n",
-      "    reproduction: mitosis\r\n",
-      "    fly: false\r\n",
+      "    data:\r\n",
+      "        reproduction: mitosis\r\n",
+      "        fly: false\r\n",
       "\r\n",
       "terrestrial: {}\r\n",
       "marine: {}\r\n"

docs/howto/advanced_filtering/config.yaml

@@ -1,6 +1,9 @@
 ---
-inventory: nornir.plugins.inventory.simple.SimpleInventory
-SimpleInventory:
-    host_file: "advanced_filtering/inventory/hosts.yaml"
-    group_file: "advanced_filtering/inventory/groups.yaml"
+core:
+    num_workers: 20
+inventory:
+    plugin: nornir.plugins.inventory.simple.SimpleInventory
+    options:
+        host_file: "advanced_filtering/inventory/hosts.yaml"
+        group_file: "advanced_filtering/inventory/groups.yaml"
 

docs/howto/advanced_filtering/inventory/groups.yaml

@@ -1,16 +1,18 @@
 ---
-defaults: {}
 mammal:
-    reproduction: birth
-    fly: false
+    data:
+        reproduction: birth
+        fly: false
 
 bird:
-    reproduction: eggs
-    fly: true
+    data:
+        reproduction: eggs
+        fly: true
 
 invertebrate:
-    reproduction: mitosis
-    fly: false
+    data:
+        reproduction: mitosis
+        fly: false
 
 terrestrial: {}
 marine: {}