docs: new structure of docs (#2737)

Author: csviri

docs/content/en/blog/_index.md

@@ -1,6 +1,6 @@
 ---
 title: Blog
-menu: {main: {weight: 30}}
+menu: {main: {weight: 2}}
 ---
 
 This is the **blog** section. It has two categories: News and Releases.

docs/content/en/blog/news/_index.md

@@ -1,4 +1,4 @@
 ---
 title: Posts
-weight: 20
+weight: 220
 ---

docs/content/en/blog/releases/_index.md

@@ -1,4 +1,4 @@
 ---
 title: Releases
-weight: 20
+weight: 230
 ---

docs/content/en/community/_index.md

@@ -1,6 +1,6 @@
 ---
 title: Community
-menu: {main: {weight: 40}}
+menu: {main: {weight: 3}}
 ---
 
 <!--add blocks of content here to add more sections to the community page -->

docs/content/en/docs/_index.md

@@ -1,8 +1,8 @@
 ---
 title: Documentation
 linkTitle: Docs
-menu: {main: {weight: 20}}
-weight: 20
+menu: {main: {weight: 1}}
+weight: 1
 ---
 
 

docs/content/en/docs/contributing/_index.md

@@ -1,6 +1,6 @@
 ---
 title: Contributing To Java Operator SDK
-weight: 100
+weight: 110
 ---
 
 First of all, we'd like to thank you for considering contributing to the project! We really

docs/content/en/docs/documentation/_index.md

@@ -0,0 +1,4 @@
+---
+title: Documentation
+weight: 40
+---

docs/content/en/docs/architecture/_index.md renamed to docs/content/en/docs/documentation/architecture.md

@@ -1,9 +1,8 @@
 ---
 title: Architecture and Internals
-weight: 90
+weight: 85
 ---
 
-
 This document gives an overview of the internal structure and components of Java Operator SDK core,
 in order to make it easier for developers to understand and contribute to it. This document is
 not intended to be a comprehensive reference, rather an introduction to the core concepts and we

docs/content/en/docs/configuration/_index.md renamed to docs/content/en/docs/documentation/configuration.md

@@ -1,11 +1,8 @@
 ---
-title: Configuring JOSDK 
-layout: docs
-permalink: /docs/configuration
+title: Configurations
+weight: 55
 ---
 
-# Configuration options
-
 The Java Operator SDK (JOSDK) provides several abstractions that work great out of the 
 box. However, while we strive to cover the most common cases with the default behavior, we also 
 recognize that that default behavior is not always what any given user might want for their 
@@ -52,6 +49,68 @@ operator.register(reconciler, configOverrider ->
         configOverrider.withFinalizer("my-nifty-operator/finalizer").withLabelSelector("foo=bar"));
 ```
 
+## Dynamically Changing Target Namespaces
+
+A controller can be configured to watch a specific set of namespaces in addition of the
+namespace in which it is currently deployed or the whole cluster. The framework supports
+dynamically changing the list of these namespaces while the operator is running.
+When a reconciler is registered, an instance of
+[`RegisteredController`](https://github.com/java-operator-sdk/java-operator-sdk/blob/ec37025a15046d8f409c77616110024bf32c3416/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/RegisteredController.java#L5)
+is returned, providing access to the methods allowing users to change watched namespaces as the
+operator is running.
+
+A typical scenario would probably involve extracting the list of target namespaces from a
+`ConfigMap` or some other input but this part is out of the scope of the framework since this is
+use-case specific. For example, reacting to changes to a `ConfigMap` would probably involve
+registering an associated `Informer` and then calling the `changeNamespaces` method on
+`RegisteredController`.
+
+```java
+
+public static void main(String[] args) {
+    KubernetesClient client = new DefaultKubernetesClient();
+    Operator operator = new Operator(client);
+    RegisteredController registeredController = operator.register(new WebPageReconciler(client));
+    operator.installShutdownHook();
+    operator.start();
+
+    // call registeredController further while operator is running
+}
+
+```
+
+If watched namespaces change for a controller, it might be desirable to propagate these changes to
+`InformerEventSources` associated with the controller. In order to express this,
+`InformerEventSource` implementations interested in following such changes need to be
+configured appropriately so that the `followControllerNamespaceChanges` method returns `true`:
+
+```java
+
+@ControllerConfiguration
+public class MyReconciler implements Reconciler<TestCustomResource> {
+
+   @Override
+   public Map<String, EventSource> prepareEventSources(
+      EventSourceContext<ChangeNamespaceTestCustomResource> context) {
+
+    InformerEventSource<ConfigMap, TestCustomResource> configMapES =
+        new InformerEventSource<>(InformerEventSourceConfiguration.from(ConfigMap.class, TestCustomResource.class)
+            .withNamespacesInheritedFromController(context)
+            .build(), context);
+
+    return EventSourceUtils.nameEventSources(configMapES);
+  }
+
+}
+```
+
+As seen in the above code snippet, the informer will have the initial namespaces inherited from
+controller, but also will adjust the target namespaces if it changes for the controller.
+
+See also
+the [integration test](https://github.com/operator-framework/java-operator-sdk/tree/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/changenamespace)
+for this feature.
+
 ## DependentResource-level configuration
 
 `DependentResource` implementations can implement the `DependentResourceConfigurator` interface 
@@ -61,7 +120,7 @@ provides specific support for the `KubernetesDependentResource`, which can be co
 `KubernetesDependentResourceConfig` instance, which is then passed to the `configureWith` method 
 implementation.
 
-TODO: still subject to change / uniformization
+TODO
 
 ## EventSource-level configuration
 

docs/content/en/docs/documentation/dependent-resource-and-workflows/_index.md

@@ -0,0 +1,9 @@
+---
+title: Dependent resources and workflows
+weight: 70
+---
+
+Dependent resources and workflows are features sometimes referenced as higher
+level abstractions. These two related concepts provides an abstraction
+over reconciliation of a single resource (Dependent resource) and the 
+orchestration of such resources (Workflows).