Fix doc refs

nornir-automation · Jun 27, 2024 · 11fd621 · 11fd621
1 parent 500dbe1
commit 11fd621
Show file tree

Hide file tree

Showing 11 changed files with 16 additions and 29 deletions.
diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
@@ -43,7 +43,7 @@ jobs:
       - name: Run sphinx
         run: |
           sudo apt-get install pandoc
-          make docs
+          make docs SPHINXOPTS="-W"
 
   pytest:
     name: Testing on Python ${{ matrix.python-version }} (${{ matrix.platform}})

diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -5,7 +5,6 @@ API Documentation
    :glob:
    :maxdepth: 1
 
-   *
    nornir/*
    nornir/*/*
    nornir/*/*/*
diff --git a/docs/api/nornir.__init__.rst b/docs/api/nornir.__init__.rst
diff --git a/docs/api/nornir.init_nornir.rst b/docs/api/nornir.init_nornir.rst
diff --git a/docs/howto/handling_connections.ipynb b/docs/howto/handling_connections.ipynb
@@ -64,7 +64,7 @@
     "## Manually\n",
     "\n",
     "In some circumstances, you may want to manage connections manually. To do so you can use \n",
-    "[open_connection](../ref/api/inventory.rst#nornir.core.inventory.Host.open_connection), [close_connection](../ref/api/inventory.rst#nornir.core.inventory.Host.close_connection), [close_connections](../ref/api/inventory.rst#nornir.core.inventory.Host.close_connections) and [Nornir.close_connections](../ref/api/nornir.rst#nornir.core.Nornir.close_connections). For instance:"
+    "[open_connection](../api/nornir/core/inventory.rst#nornir.core.inventory.Host.open_connection), [close_connection](../api/nornir/core/inventory.rst#nornir.core.inventory.Host.close_connection), [close_connections](../api/nornir/core/inventory.rst#nornir.core.inventory.Host.close_connections) and [Nornir.close_connections](../api/nornir/core/__init__.rst#nornir.core.__init__.Nornir.close_connections). For instance:"
    ]
   },
   {
@@ -119,7 +119,7 @@
    "source": [
     "## Specifying connection parameters\n",
     "\n",
-    "When using the [open_connection](../ref/api/inventory.rst#nornir.core.inventory.Host.open_connection) you can specify any parameters you want. If you don't, or if you let nornir open the connection automatically, nornir will read those parameters from the inventory. You can specify standard attributes at the object level if you want to reuse them across different connections or you can override them for each connection. For example:"
+    "When using the [open_connection](../api/nornir/core/inventory.rst#nornir.core.inventory.Host.open_connection) you can specify any parameters you want. If you don't, or if you let nornir open the connection automatically, nornir will read those parameters from the inventory. You can specify standard attributes at the object level if you want to reuse them across different connections or you can override them for each connection. For example:"
    ]
   },
   {

diff --git a/docs/tutorial/failed_tasks.ipynb b/docs/tutorial/failed_tasks.ipynb
@@ -378,7 +378,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To achieve this `nornir` keeps a set of failed hosts in it's shared [data](../../ref/api/nornir.rst#nornir.core.state.GlobalState) object:"
+    "To achieve this `nornir` keeps a set of failed hosts in it's shared [data](../api/nornir/core/state.rst#nornir.core.state.GlobalState) object:"
    ]
   },
   {
@@ -405,7 +405,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you want to mark some hosts as succeeded and make them back eligible for future tasks you can do it individually per host with the function [recover_host](../../ref/api/nornir.rst#nornir.core.state.GlobalState.recover_host) or reset the list completely with [reset_failed_hosts](../../ref/api/nornir.rst#nornir.core.state.GlobalState.reset_failed_hosts):"
+    "If you want to mark some hosts as succeeded and make them back eligible for future tasks you can do it individually per host with the function [recover_host](../api/nornir/core/state.rst#nornir.core.state.GlobalState.recover_host) or reset the list completely with [reset_failed_hosts](../api/nornir/core/state.rst#nornir.core.state.GlobalState.reset_failed_hosts):"
    ]
   },
   {

diff --git a/docs/tutorial/initializing_nornir.ipynb b/docs/tutorial/initializing_nornir.ipynb
@@ -18,7 +18,7 @@
    "source": [
     "# Initializing Nornir\n",
     "\n",
-    "Easiest way of initializing nornir is with the function [InitNornir](../api/nornir/__init__.html#nornir.__init__.InitNornir).\n",
+    "Easiest way of initializing nornir is with the function [InitNornir](../api/nornir/__init__.rst#nornir.__init__.InitNornir).\n",
     "\n",
     "With `InitNornir` you can initialize nornir with a configuration file, with code or with a combination of both.\n",
     "\n",
@@ -143,7 +143,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now to create the [nornir](../../ref/api/nornir.rst#nornir) object:"
+    "Now to create the [nornir](../api/nornir/core/__init__.rst#nornir.core.__init__.Nornir) object:"
    ]
   },
   {

diff --git a/docs/tutorial/inventory.ipynb b/docs/tutorial/inventory.ipynb
@@ -18,9 +18,9 @@
    "source": [
     "## Inventory\n",
     "\n",
-    "The Inventory is arguably the most important piece of nornir. Let's see how it works. To begin with the [inventory](../api/nornir/core/inventory.html#module-nornir.core.inventory) is comprised of [hosts](../api/nornir/core/inventory.html#nornir.core.inventory.Hosts),  [groups](../api/nornir/core/inventory.html#nornir.core.inventory.Groups) and [defaults](../api/nornir/core/inventory.html#nornir.core.inventory.Defaults).\n",
+    "The Inventory is arguably the most important piece of nornir. Let's see how it works. To begin with the [inventory](../api/nornir/core/inventory.rst#module-nornir.core.inventory) is comprised of [hosts](../api/nornir/core/inventory.rst#nornir.core.inventory.Hosts),  [groups](../api/nornir/core/inventory.rst#nornir.core.inventory.Groups) and [defaults](../api/nornir/core/inventory.rst#nornir.core.inventory.Defaults).\n",
     "\n",
-    "In this tutorial we are using the [SimpleInventory](../api/nornir/plugins/inventory/simple.html#nornir.plugins.inventory.simple.SimpleInventory) plugin. This inventory plugin stores all the relevant data in three files. Let’s start by checking them:"
+    "In this tutorial we are using the [SimpleInventory](../api/nornir/plugins/inventory/simple.rst#nornir.plugins.inventory.simple.SimpleInventory) plugin. This inventory plugin stores all the relevant data in three files. Let’s start by checking them:"
    ]
   },
   {
@@ -592,7 +592,7 @@
    "source": [
     "### Accessing the inventory\n",
     "\n",
-    "You can access the [inventory](../api/nornir/core/inventory.html#module-nornir.core.inventory) with the `inventory` attribute:"
+    "You can access the [inventory](../api/nornir/core/inventory.rst#module-nornir.core.inventory) with the `inventory` attribute:"
    ]
   },
   {
@@ -1190,7 +1190,7 @@
     "\n",
     "##### Filter functions\n",
     "\n",
-    "The ``filter_func`` parameter let's you run your own code to filter the hosts. The function signature is as simple as ``my_func(host)`` where host is an object of type [Host](../api/nornir/core/inventory.html#nornir.core.inventory.Host) and it has to return either ``True`` or ``False`` to indicate if you want to host or not."
+    "The ``filter_func`` parameter let's you run your own code to filter the hosts. The function signature is as simple as ``my_func(host)`` where host is an object of type [Host](../api/nornir/core/inventory.rst#nornir.core.inventory.Host) and it has to return either ``True`` or ``False`` to indicate if you want to host or not."
    ]
   },
   {

diff --git a/docs/tutorial/processors.ipynb b/docs/tutorial/processors.ipynb
@@ -6,7 +6,7 @@
    "source": [
     "# Processors\n",
     "\n",
-    "Processors are plugins that can execute code on certain events. For more information on those events check the [class documentation](../../ref/api/processors.rst).\n",
+    "Processors are plugins that can execute code on certain events. For more information on those events check the [class documentation](../api/nornir/core/processor.rst).\n",
     "\n",
     "You can see processors as an alternative way of dealing with the results of a task, however, it has a few advantages:\n",
     "\n",

diff --git a/docs/tutorial/task_results.ipynb b/docs/tutorial/task_results.ipynb
@@ -267,7 +267,7 @@
     "\n",
     "## The programmatic way\n",
     "\n",
-    "We have hinted at how to deal with result objects already, but let's elaborate on that. To begin with, task groups will return an [AggregatedResult](../api/nornir/core/task.html#nornir.core.task.AggregatedResult). This object is a dict-like object you can use to iterate over or access hosts directly:"
+    "We have hinted at how to deal with result objects already, but let's elaborate on that. To begin with, task groups will return an [AggregatedResult](../api/nornir/core/task.rst#nornir.core.task.AggregatedResult). This object is a dict-like object you can use to iterate over or access hosts directly:"
    ]
   },
   {
@@ -334,7 +334,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You probably noticed that inside each key in [AggregatedResult](../api/nornir/core/task.html#nornir.core.task.AggregatedResult) there is a [MultiResult](../api/nornir/core/task.html#nornir.core.task.MultiResult) object. This object is a list-like object you can use to iterate over or access any [Result](../api/nornir/core/task.html#nornir.core.task.Result) you want:"
+    "You probably noticed that inside each key in [AggregatedResult](../api/nornir/core/task.rst#nornir.core.task.AggregatedResult) there is a [MultiResult](../api/nornir/core/task.rst#nornir.core.task.MultiResult) object. This object is a list-like object you can use to iterate over or access any [Result](../api/nornir/core/task.rst#nornir.core.task.Result) you want:"
    ]
   },
   {

diff --git a/docs/tutorial/tasks.ipynb b/docs/tutorial/tasks.ipynb
@@ -23,7 +23,7 @@
     "\n",
     "Now that you know how to initialize nornir and work with the inventory let's see how we can leverage it to run tasks on groups of hosts.\n",
     "\n",
-    "A task is a reusable piece of code that implements some functionality for a single host. In python terms it is a function that takes a [Task](../api/nornir/core/task.html#nornir.core.task.Task) as first paramater and returns a [Result](../api/nornir/core/task.html#nornir.core.task.Result).\n",
+    "A task is a reusable piece of code that implements some functionality for a single host. In python terms it is a function that takes a [Task](../api/nornir/core/task.rst#nornir.core.task.Task) as first paramater and returns a [Result](../api/nornir/core/task.rst#nornir.core.task.Result).\n",
     "\n",
     "For instance:"
    ]
@@ -47,7 +47,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To execute a task you can use the [run](../api/nornir/core/__init__.html#nornir.core.__init__.Nornir.run) method:"
+    "To execute a task you can use the [run](../api/nornir/core/__init__.rst#nornir.core.__init__.Nornir.run) method:"
    ]
   },
   {