Updated docs as best as possible for nornir 3 (#562)

nornir-automation · Jun 18, 2020 · 6ec0bc9 · 6ec0bc9
1 parent d47f2a9
commit 6ec0bc9
Show file tree

Hide file tree

Showing 98 changed files with 2,406 additions and 3,611 deletions.
diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
@@ -80,6 +80,7 @@ jobs:
 
       - name: Run nbval
         run: make nbval
+        if: platform != 'windows-latest'
 
   release:
     name: Releasing to pypi

diff --git a/Makefile b/Makefile
@@ -22,7 +22,7 @@ black:
 sphinx:
 	# TODO REPLACE with: sphinx-build -n -E -q -N -b dummy -d docs/_build/doctrees docs asd
 	# poetry run sphinx-build -W -b html -d docs/_build/doctrees docs docs/_build/html
-	echo "WARNING: sphinx needs to be added here before release!!!"
+	echo "WARNING: sphinx needs to be added here!!!"
 
 .PHONY: pylama
 pylama:
@@ -34,15 +34,18 @@ mypy:
 
 .PHONY: nbval
 nbval:
-	# poetry run pytest --nbval --sanitize-with docs/nbval_sanitize.cfg \
-	#     docs/howto \
-	#     docs/tutorials/intro/initializing_nornir.ipynb \
-	#     docs/tutorials/intro/inventory.ipynb
-	echo "WARNING: nbval needs to be added here before release!!!"
+	poetry run pytest --nbval --sanitize-with docs/nbval_sanitize.cfg \
+		docs/tutorial/ \
+		docs/howto/
 
 .PHONY: tests
 tests: black pylama mypy nbval pytest sphinx
 
 .PHONY: docker-tests
 docker-tests: docker
 	docker run --name nornir-tests --rm $(NAME):latest make tests
+
+.PHONY: docs
+docs:
+	./docs/build_api.sh
+	make -C docs clean html
diff --git a/docs/_data_templates/configuration-parameters.j2 b/docs/_data_templates/configuration-parameters.j2
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -0,0 +1,11 @@
+API Documentation
+=================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   *
+   nornir/*
+   nornir/*/*
+   nornir/*/*/*
diff --git a/docs/api/nornir.__init__.rst b/docs/api/nornir.__init__.rst
@@ -0,0 +1,6 @@
+nornir/__init__.py
+=========================================
+
+.. automodule:: nornir/__init__.py
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir.init_nornir.rst b/docs/api/nornir.init_nornir.rst
@@ -0,0 +1,6 @@
+nornir/init_nornir.py
+=========================================
+
+.. automodule:: nornir/init_nornir.py
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/__init__.rst b/docs/api/nornir/__init__.rst
@@ -0,0 +1,6 @@
+nornir.__init__
+=========================================
+
+.. automodule:: nornir.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/__init__.rst b/docs/api/nornir/core/__init__.rst
@@ -0,0 +1,6 @@
+nornir.core.__init__
+=========================================
+
+.. automodule:: nornir.core.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/configuration.rst b/docs/api/nornir/core/configuration.rst
@@ -0,0 +1,6 @@
+nornir.core.configuration
+=========================================
+
+.. automodule:: nornir.core.configuration
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/connections.rst b/docs/api/nornir/core/connections.rst
@@ -0,0 +1,6 @@
+nornir.core.connections
+=========================================
+
+.. automodule:: nornir.core.connections
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/exceptions.rst b/docs/api/nornir/core/exceptions.rst
@@ -0,0 +1,6 @@
+nornir.core.exceptions
+=========================================
+
+.. automodule:: nornir.core.exceptions
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/filter.rst b/docs/api/nornir/core/filter.rst
@@ -0,0 +1,6 @@
+nornir.core.filter
+=========================================
+
+.. automodule:: nornir.core.filter
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/helpers/__init__.rst b/docs/api/nornir/core/helpers/__init__.rst
@@ -0,0 +1,6 @@
+nornir.core.helpers.__init__
+=========================================
+
+.. automodule:: nornir.core.helpers.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/helpers/jinja_helper.rst b/docs/api/nornir/core/helpers/jinja_helper.rst
@@ -0,0 +1,6 @@
+nornir.core.helpers.jinja_helper
+=========================================
+
+.. automodule:: nornir.core.helpers.jinja_helper
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/inventory.rst b/docs/api/nornir/core/inventory.rst
@@ -0,0 +1,6 @@
+nornir.core.inventory
+=========================================
+
+.. automodule:: nornir.core.inventory
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/plugins/__init__.rst b/docs/api/nornir/core/plugins/__init__.rst
@@ -0,0 +1,6 @@
+nornir.core.plugins.__init__
+=========================================
+
+.. automodule:: nornir.core.plugins.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/plugins/inventory.rst b/docs/api/nornir/core/plugins/inventory.rst
@@ -0,0 +1,6 @@
+nornir.core.plugins.inventory
+=========================================
+
+.. automodule:: nornir.core.plugins.inventory
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/plugins/register.rst b/docs/api/nornir/core/plugins/register.rst
@@ -0,0 +1,6 @@
+nornir.core.plugins.register
+=========================================
+
+.. automodule:: nornir.core.plugins.register
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/plugins/runners.rst b/docs/api/nornir/core/plugins/runners.rst
@@ -0,0 +1,6 @@
+nornir.core.plugins.runners
+=========================================
+
+.. automodule:: nornir.core.plugins.runners
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/processor.rst b/docs/api/nornir/core/processor.rst
@@ -0,0 +1,6 @@
+nornir.core.processor
+=========================================
+
+.. automodule:: nornir.core.processor
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/state.rst b/docs/api/nornir/core/state.rst
@@ -0,0 +1,6 @@
+nornir.core.state
+=========================================
+
+.. automodule:: nornir.core.state
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/core/task.rst b/docs/api/nornir/core/task.rst
@@ -0,0 +1,6 @@
+nornir.core.task
+=========================================
+
+.. automodule:: nornir.core.task
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/init_nornir.rst b/docs/api/nornir/init_nornir.rst
@@ -0,0 +1,6 @@
+nornir.init_nornir
+=========================================
+
+.. automodule:: nornir.init_nornir
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/plugins/__init__.rst b/docs/api/nornir/plugins/__init__.rst
@@ -0,0 +1,6 @@
+nornir.plugins.__init__
+=========================================
+
+.. automodule:: nornir.plugins.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/plugins/connections/__init__.rst b/docs/api/nornir/plugins/connections/__init__.rst
@@ -0,0 +1,6 @@
+nornir.plugins.connections.__init__
+=========================================
+
+.. automodule:: nornir.plugins.connections.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/plugins/functions/__init__.rst b/docs/api/nornir/plugins/functions/__init__.rst
@@ -0,0 +1,6 @@
+nornir.plugins.functions.__init__
+=========================================
+
+.. automodule:: nornir.plugins.functions.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/plugins/inventory/__init__.rst b/docs/api/nornir/plugins/inventory/__init__.rst
@@ -0,0 +1,6 @@
+nornir.plugins.inventory.__init__
+=========================================
+
+.. automodule:: nornir.plugins.inventory.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/plugins/inventory/simple.rst b/docs/api/nornir/plugins/inventory/simple.rst
@@ -0,0 +1,6 @@
+nornir.plugins.inventory.simple
+=========================================
+
+.. automodule:: nornir.plugins.inventory.simple
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/plugins/processors/__init__.rst b/docs/api/nornir/plugins/processors/__init__.rst
@@ -0,0 +1,6 @@
+nornir.plugins.processors.__init__
+=========================================
+
+.. automodule:: nornir.plugins.processors.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/plugins/runners/__init__.rst b/docs/api/nornir/plugins/runners/__init__.rst
@@ -0,0 +1,6 @@
+nornir.plugins.runners.__init__
+=========================================
+
+.. automodule:: nornir.plugins.runners.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/api/nornir/plugins/tasks/__init__.rst b/docs/api/nornir/plugins/tasks/__init__.rst
@@ -0,0 +1,6 @@
+nornir.plugins.tasks.__init__
+=========================================
+
+.. automodule:: nornir.plugins.tasks.__init__
+  :members:
+  :undoc-members:
diff --git a/docs/build_api.sh b/docs/build_api.sh
@@ -0,0 +1,19 @@
+#!/bin/sh
+DST=docs/api/
+
+rm -rf $DST/nornir
+
+for f in `find nornir -name "*.py"`; do
+    DIR=$DST/`dirname $f`
+    FILE=$DST/`echo $f | sed "s/\.py$/.rst/"`
+    IMPORT=`echo $f | sed "s/\.py$//" | sed "s/\//./g"`
+    mkdir -p $DIR
+    cat <<EOF > $FILE
+$IMPORT
+=========================================
+
+.. automodule:: $IMPORT
+  :members:
+  :undoc-members:
+EOF
+done
diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst
diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst
@@ -0,0 +1 @@
+.. include:: ../../CHANGELOG.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -19,14 +19,14 @@
 #
 import os
 import sys
-
-from jinja2 import Environment, FileSystemLoader
+from typing import Dict
 
 from nornir import __version__
 
+from sphinx.application import Sphinx
+
 sys.path.insert(0, os.path.abspath("../"))
 
-from nornir.core.deserializer.configuration import Config  # noqa
 
 # -- General configuration ------------------------------------------------
 BASEPATH = os.path.abspath(os.path.dirname(__file__))
@@ -54,7 +54,7 @@
 
 # General information about the project.
 project = "nornir"
-copyright = "2019, David Barroso"
+copyright = "2020, David Barroso"
 author = "David Barroso"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -124,7 +124,7 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_elements = {
+latex_elements: Dict[str, str] = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
@@ -174,26 +174,6 @@
 issues_github_path = "nornir-automation/nornir"
 
 
-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["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 setup(app):
+def setup(app: Sphinx) -> None:
     """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")
diff --git a/docs/configuration/generated/.placeholder b/docs/configuration/generated/.placeholder
diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst
@@ -23,7 +23,7 @@ Logging
 
 Next, you can find each section and their corresponding options.
 
-.. include:: generated/parameters.rst
+.. include:: parameters.rst
 
 user_defined
 ------------