containers · jukkar · Jun 26, 2023 · Jun 22, 2023 · Jun 22, 2023 · Jun 21, 2023
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,12 @@
+# Welcome to NRI Plugins documentation
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+introduction.md
+resource-policy/index.rst
+contributing.md
+Project GitHub repository <https://github.com/containers/nri-plugins>
+```
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/introduction.md b/docs/introduction.md
@@ -2,5 +2,5 @@
 
 The NRI plugins is a collection of NRI (Node Resource Interface) based plugins
 to manage various aspects of pod and container life cycle.
-For example the [resource policy plugins](resource_policies) can be used to modify
+For example the [resource policy plugins](resource-policy/policy/index.md) can be used to modify
 the container resource allocation depending on available system resources.
diff --git a/docs/resource-policy/node-agent.md → docs/resource-policy/configuration.md b/docs/resource-policy/node-agent.md → docs/resource-policy/configuration.md
@@ -23,5 +23,5 @@ the node group label.
 There is a
 [sample ConfigMap spec](/sample-configs/nri-resource-policy-configmap.example.yaml)
 that contains a node-specific, a group-specific, and a default ConfigMap
-example. See [any available policy-specific documentation](policy/index.rst)
+example. See [any available policy-specific documentation](policy/index.md)
 for more information on the policy configurations.
diff --git a/docs/resource-policy/configuration.rst b/docs/resource-policy/configuration.rst
diff --git a/docs/resource-policy/developers-guide/index.md b/docs/resource-policy/developers-guide/index.md
@@ -0,0 +1,10 @@
+# Developer's Guide
+
+```{toctree}
+---
+maxdepth: 1
+---
+architecture.md
+testing.rst
+cpu-allocator.md
+```
diff --git a/docs/resource-policy/developers-guide/index.rst b/docs/resource-policy/developers-guide/index.rst
diff --git a/docs/resource-policy/developers-guide/testing.md b/docs/resource-policy/developers-guide/testing.md
@@ -0,0 +1,9 @@
+# Testing
+
+```{toctree}
+---
+maxdepth: 1
+---
+unit-test.md
+e2e-test.md
+```
diff --git a/docs/resource-policy/developers-guide/testing.rst b/docs/resource-policy/developers-guide/testing.rst
diff --git a/docs/resource-policy/index.md b/docs/resource-policy/index.md
@@ -0,0 +1,14 @@
+# Resource Policy Plugins
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+introduction.md
+installation.md
+setup.md
+configuration.md
+policy/index.md
+developers-guide/index.rst
+```
diff --git a/docs/resource-policy/index.rst b/docs/resource-policy/index.rst
diff --git a/docs/resource-policy/policy/index.rst → docs/resource-policy/policy/index.md b/docs/resource-policy/policy/index.rst → docs/resource-policy/policy/index.md
@@ -1,7 +1,4 @@
-.. _resource_policies:
-
-Policies
-########
+# Policies
 
 Currently there are two resource policies:
 
@@ -11,8 +8,10 @@ policy that allocates resources evenly in order to avoid the "noisy neighbor" pr
 The Balloons resource policy allows user to allocate workloads to resources in a more
 user controlled way.
 
-.. toctree::
-   :maxdepth: 1
-
-   topology-aware.md
-   balloons.md
+```{toctree}
+---
+maxdepth: 1
+---
+topology-aware.md
+balloons.md
+```
diff --git a/docs/resource-policy/policy/topology-aware.md b/docs/resource-policy/policy/topology-aware.md
@@ -130,11 +130,11 @@ policy:
 
 ## Configuring the Policy
 
-The policy has a number of configuration options which affect its default behavior.
-These options can be supplied as part of the
-[dynamic configuration](../setup.md#using-nri-resource-policy-agent-and-a-configmap)
-received via the [`node agent`](../node-agent.md), or in a fallback or forced
-configuration file. These configuration options are
+The policy has a number of configuration options which affect its default
+behavior. These options can be supplied as part of the
+[dynamic configuration](../setup.md#dynamic-configuration-with-configmaps)
+or in a fallback or forced configuration file. These configuration options
+are
 
   - `PinCPU`
     * whether to pin workloads to assigned pool CPU sets

diff --git a/docs/resource-policy/setup.md b/docs/resource-policy/setup.md
@@ -15,20 +15,18 @@ You can edit it as needed.
 
 ## Setting up NRI Resource Policy
 
-### Using NRI Resource Policy Agent and a ConfigMap
-
-The [NRI Resource Policy Node Agent][agent] can monitor and fetch configuration
-from the ConfigMap and pass it on to NRI Resource Policy plugin.
-By default, it automatically tries to use the agent to acquire configuration,
-unless you override this by forcing a static local configuration using
-the `--force-config <config-file>` option.
-When using the agent, it is also possible to provide an initial fallback for
-configuration using the `--fallback-config <config-file>`. This file is
-used before the very first configuration is successfully acquired from the
-agent.
+### Dynamic configuration with ConfigMaps
 
-See the [Node Agent][agent] about how to set up and configure the agent.
+The resource policies plugins support[dynamic configuration][configuration]
+using ConfigMaps. Plugins watch changes in the ConfigMap and reconfigure
+themselves on any update.  Tt is possible to provide an initial fallback for
+configuration using the `--fallback-config <config-file>` flag. This file is
+used before the very first configuration is successfully acquired from the
+ConfigMap.
 
+Dynamic configuration can be disabled with a static local configuration using
+the `--force-config <config-file>` flag.  See the [Node Agent][agent] about
+how to set up and configure the agent.
 
 ## Logging and debugging
 
@@ -58,4 +56,4 @@ the environment but off in the configuration, it will be turned off
 eventually.
 
 <!-- Links -->
-[agent]: node-agent.md
+[configuration]: configuration.md