From 07d55944df879f664527cfb02a6f5e28893b3c18 Mon Sep 17 00:00:00 2001
From: Furkat Gofurov <furkat.gofurov@suse.com>
Date: Tue, 9 Apr 2024 15:12:47 +0300
Subject: [PATCH] Improvements to book

Signed-off-by: Furkat Gofurov <furkat.gofurov@suse.com>
---
 docs/book/README.md                           | 23 +++++++++++++++++++
 docs/book/src/00_introduction.md              |  8 +++----
 docs/book/src/04_developer/00.md              |  2 +-
 .../04_developer/01_version_migration/00.md   |  5 ++++
 .../01_v1alpha1-to-v1alpha2.md}               |  2 +-
 5 files changed, 34 insertions(+), 6 deletions(-)
 create mode 100644 docs/book/README.md
 create mode 100644 docs/book/src/04_developer/01_version_migration/00.md
 rename docs/book/src/04_developer/{03_v1alpha1-to-v1alpha2.md => 01_version_migration/01_v1alpha1-to-v1alpha2.md} (96%)

diff --git a/docs/book/README.md b/docs/book/README.md
new file mode 100644
index 000000000..ba1b3d883
--- /dev/null
+++ b/docs/book/README.md
@@ -0,0 +1,23 @@
+# Preview book changes locally
+
+It is easy to preview your local changes to the book before submitting a PR:
+
+1. Build the local copy of the book from the `docs/book` path:
+
+    ```shell
+    make build
+    ```
+
+1. To preview the book contents run:
+
+    ```shell
+    make serve
+    ```
+
+This should serve the book at [localhost:3000](http://localhost:3000/). You can keep running `make serve` and continue making doc changes. mdBook will detect your changes, render them and refresh your browser page automatically.
+
+1. Clean mdBook auto-generated content from `docs/book/book` path once you have finished local preview:
+
+    ```shell
+    make clean
+    ```
\ No newline at end of file
diff --git a/docs/book/src/00_introduction.md b/docs/book/src/00_introduction.md
index d38024a67..c16163dd7 100644
--- a/docs/book/src/00_introduction.md
+++ b/docs/book/src/00_introduction.md
@@ -14,8 +14,8 @@ This operator leverages a declarative API and extends the capabilities of the `c
 
 ## Getting started
 
-* [Quick Start](./user/quick-start.md)
-* [Concepts](./user/concepts.md)
-* [Developer guide](./developer/guide.md)
-* [Contributing](./CONTRIBUTING.md)
+* [Quick Start](./01_user/02_quick-start.md)
+* [Concepts](./01_user/01_concepts.md)
+* [Developer guide](./04_developer/02_guide.md)
+* [Contributing](./05_reference/04_contributing.md)
 
diff --git a/docs/book/src/04_developer/00.md b/docs/book/src/04_developer/00.md
index d144dff56..99c0d5b1d 100644
--- a/docs/book/src/04_developer/00.md
+++ b/docs/book/src/04_developer/00.md
@@ -3,4 +3,4 @@
 This section contains regular developer tasks, such as:
 - Release
 - Development guide
-- Migration guide
\ No newline at end of file
+- Version migration
\ No newline at end of file
diff --git a/docs/book/src/04_developer/01_version_migration/00.md b/docs/book/src/04_developer/01_version_migration/00.md
new file mode 100644
index 000000000..8cdf38823
--- /dev/null
+++ b/docs/book/src/04_developer/01_version_migration/00.md
@@ -0,0 +1,5 @@
+# Version migration
+
+This section provides an overview of relevant changes between versions of Cluster API Operator and their direct successors.
+
+- [v1alpha1 to v1alpha2](./01_v1alpha1-to-v1alpha2.md)
\ No newline at end of file
diff --git a/docs/book/src/04_developer/03_v1alpha1-to-v1alpha2.md b/docs/book/src/04_developer/01_version_migration/01_v1alpha1-to-v1alpha2.md
similarity index 96%
rename from docs/book/src/04_developer/03_v1alpha1-to-v1alpha2.md
rename to docs/book/src/04_developer/01_version_migration/01_v1alpha1-to-v1alpha2.md
index a167109d6..2ca551eab 100644
--- a/docs/book/src/04_developer/03_v1alpha1-to-v1alpha2.md
+++ b/docs/book/src/04_developer/01_version_migration/01_v1alpha1-to-v1alpha2.md
@@ -1,4 +1,4 @@
-# Cluster API Operator v1alpha1 API compared to v1alpha2 API
+# Cluster API Operator v1alpha1 compared to v1alpha2
 
 This document provides an overview over relevant changes between Cluster API Operator API v1alpha1 and v1alpha2 for consumers of our Go API.