From a8c20e5a30926f2f64f95b1109dc942a24c29954 Mon Sep 17 00:00:00 2001
From: Nico Schottelius <nico@nico-notebook.schottelius.org>
Date: Sat, 7 Dec 2019 12:01:59 +0100
Subject: [PATCH] ++doc cleanup

---
 ucloud/docs/source/index.rst                  |  7 +-
 ucloud/docs/source/introduction.rst           | 94 +++++++++++++++++++
 .../docs/source/introduction/howitworks.rst   |  4 +
 ucloud/docs/source/usage/usage-for-admins.rst | 11 ++-
 .../usage-for-users.rst => user-guide.rst}    |  4 +-
 5 files changed, 112 insertions(+), 8 deletions(-)
 create mode 100644 ucloud/docs/source/introduction.rst
 rename ucloud/docs/source/{usage/usage-for-users.rst => user-guide.rst} (98%)

diff --git a/ucloud/docs/source/index.rst b/ucloud/docs/source/index.rst
index 1f0530d..74427b5 100644
--- a/ucloud/docs/source/index.rst
+++ b/ucloud/docs/source/index.rst
@@ -10,12 +10,13 @@ Welcome to ucloud's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   introduction/whatis
-   introduction/howitworks
+   introduction
+   users-guide
+
    installation/alpine
    installation/archlinux
    usage/usage-for-admins
-   usage/usage-for-users
+
    usage/how-to-create-an-os-image-for-ucloud
 
 
diff --git a/ucloud/docs/source/introduction.rst b/ucloud/docs/source/introduction.rst
new file mode 100644
index 0000000..eba2020
--- /dev/null
+++ b/ucloud/docs/source/introduction.rst
@@ -0,0 +1,94 @@
+Introduction
+============
+
+ucloud is a modern, IPv6 first virtual machine management system.
+It is an alternative to `OpenNebula <https://opennebula.org/>`_,
+`OpenStack <https://www.openstack.org/>`_ or
+`Cloudstack <https://cloudstack.apache.org/>`_.
+
+ucloud is the first cloud management system that puts IPv6
+first. ucloud also has an integral ordering process that we missed in
+existing solutions.
+
+The ucloud documentation is separated into various sections for the
+different use cases:
+
+* :ref:`The user guide <user-guide>` describes how to use an existing
+  ucloud installation
+* There are :ref:`setup instructions <setup-install>` which describe on how to setup a new
+  ucloud instance
+* :ref:`The admin guide <admin-guide>` describe on how to
+  administrate ucloud
+
+
+Architecture
+------------
+
+
+
+suuuuuuubsub
+^^^^^^^^^^^^
+
+and following a
+
+para
+""""
+
+para2?
+
+para2!
+""""""
+mo moo!
+
+Introduction
+
+What is ucloud?
+~~~~~~~~~~~~~~~
+
+
+
+Tech Stack
+----------
+* Python 3 as main language.
+* Flask for APIs.
+* JSON for specifications.
+* QEMU (+ kvm acceleration) as hypervisor.
+* etcd for key/value storage (specifically all metadata e.g Virtual Machine Specifications, Networks Specifications, Images Specifications etc.).
+* CEPH for image storage.
+* uotp for user authentication.
+* netbox for IPAM.
+* radvd for Router Advertisement.
+
+
+Components
+----------
+* API
+* Scheduler
+* Host
+* File Scanner
+* Image Scanner
+* Metadata Server
+* VM Init Scripts (dubbed as ucloud-init)How does ucloud work?
+=====================
+
+ucloud is separeted into 3 systems:
+
+1. The client side for using ucloud
+2. The server side
+3. The supporting infrastructure (databases, virtualisation, etc.)
+
+
+Depending on your use case, select one of the following guides to
+continue:
+
+* I want to use
+* I want to operate/run ucloud as a service
+
+
+Architecture
+------------
+Description of the ucloud architecture
+
+
+Authentication
+~~~~~~~~~~~~~~
diff --git a/ucloud/docs/source/introduction/howitworks.rst b/ucloud/docs/source/introduction/howitworks.rst
index 9b66e94..e3278f9 100644
--- a/ucloud/docs/source/introduction/howitworks.rst
+++ b/ucloud/docs/source/introduction/howitworks.rst
@@ -18,3 +18,7 @@ continue:
 Architecture
 ------------
 Description of the ucloud architecture
+
+
+Authentication
+~~~~~~~~~~~~~~
diff --git a/ucloud/docs/source/usage/usage-for-admins.rst b/ucloud/docs/source/usage/usage-for-admins.rst
index 44298cc..ec6597d 100644
--- a/ucloud/docs/source/usage/usage-for-admins.rst
+++ b/ucloud/docs/source/usage/usage-for-admins.rst
@@ -1,3 +1,6 @@
+.. _admin-guide:
+
+
 Usage Guide For Administrators
 ==============================
 
@@ -11,11 +14,11 @@ Start API
 Host Creation
 -------------
 
-Currently, we don't have any host (that runs virtual machines). 
+Currently, we don't have any host (that runs virtual machines).
 So, we need to create it by executing the following command
 
 .. code-block:: sh
-    
+
     ucloud-cli host create --hostname ungleich.ch --cpu 32 --ram '32GB' --os-ssd '32GB'
 
 You should see something like the following
@@ -140,11 +143,11 @@ Now, ucloud have received our request to create an image from file. We have to r
 
     ucloud imagescanner
 
-To make sure, that our image is create run :code:`ucloud-cli image list --public`. You would get 
+To make sure, that our image is create run :code:`ucloud-cli image list --public`. You would get
 output something like the following
 
 .. code-block:: json
-    
+
     {
         "images": [
             {
diff --git a/ucloud/docs/source/usage/usage-for-users.rst b/ucloud/docs/source/user-guide.rst
similarity index 98%
rename from ucloud/docs/source/usage/usage-for-users.rst
rename to ucloud/docs/source/user-guide.rst
index 1c59408..f2ea9b2 100644
--- a/ucloud/docs/source/usage/usage-for-users.rst
+++ b/ucloud/docs/source/user-guide.rst
@@ -1,3 +1,5 @@
+.. _user-guide:
+
 Usage Guide For End Users
 =========================
 
@@ -116,4 +118,4 @@ Migrate VM
 .. option:: --destination
 
    The name of destination host. You can find a list of host
-   using :ref:`get-list-of-hosts`
\ No newline at end of file
+   using :ref:`get-list-of-hosts`