axem-solutions · janosmurai · Feb 23, 2024 · Feb 22, 2024
@@ -46,25 +46,27 @@ Development Environments for embedded software development.
 Contributors and early adopters are welcome!
 </p>
 
-## Concept
-A Development Environment is a set of tools used for a development project (e.g. build system, 
-debugger, toolchain, etc.).  The tools are separately packed into container images, which are stored 
-in registries.
+## The Concept in a Nutshell
+A set of software tools used for a specific development project is called a Development Environment.
+These tools for example can be the build system, debugger, test framework, etc...  
 
-Each Development Environment has a descriptor. A descriptor indicates which tools are 
-required in the project and the place their container images are stored. All descriptors are stored 
-in the Development Environment Catalogs. The users can browse these catalogs, and list the available 
-environments and their statuses.  
-A Development Environment can be installed from its catalog by a simple dem command, which means 
-that the required tool images get downloaded from the registries.
+The idea is to pack the tools separately into container images, which are then can be stored in 
+registries.
 
-The registries, the catalogs, and the development infrastructure form a Development Platform.
+Each Development Environment has a descriptor. A descriptor, like a blueprint, indicates which tools 
+are required in the project, and the place their container images are stored.
 
-The purpose of DEM is the easy management of this platform. The users can install available 
-Development Environments or freely create their own from the tool images available in the registries 
-or locally.
+![Dev Env descriptor](/docs/wp-content/dev_env_descriptor.png)
 
-![platform](docs/wp-content/platform.png)
+The descriptors can be stored in the Development Environment Catalogs. The users can browse these 
+catalogs, and download a copy of the Development Environment descriptor to their local catalog.
+
+![Catalogs](/docs/wp-content/dem_catalogs.png)
+
+The users can install a Development Environments from their local catalog or freely create their own 
+based on the tools available in the registries or on their local system.
+
+![Dev Env installation](/docs/wp-content/dev_env_installation.png)
 
 ## Key features
 
@@ -145,11 +147,10 @@ Now you have the Dev Env descriptor in your local catalog, but you might want to
 - Change the tool image for a given tool.
 - Set the host where the image should be placed.
 
-You can edit it the Dev Env with:
+You can edit it with:
 
     dem modify DEV_ENV_NAME
 
-
 Finally, if you are ready to use it, you can initialize it with:
 
     dem install DEV_ENV_NAME

@@ -0,0 +1,69 @@
+---
+title: The Basics
+---
+
+In this chapter we will cover the basic concepts of the Development Environment Manager (DEM).
+
+## What is a Development Environment?
+A set of software tools used for a specific development project is called a **Development
+Environment**. These tools for example can be the build system, debugger, test framework, etc...
+
+## A Container Image
+To put it simply, a container image is a set of software components alongside its dependencies, 
+which can be run in a container.
+
+## A Tool Container Image
+The idea is to build the tools from a Development Environment into their own respective images, so 
+they can run isolatedly.
+
+## Development Environment Descriptor
+Each Development Environment has a descriptor. A descriptor, like a blueprint, indicates which tools
+are required in the project, and the place their container images are stored.
+
+![Dev Env descriptor](wp-content/dev_env_descriptor.png)
+
+## Container Engine
+The container engine is responsible for running the container images. The DEM uses the Docker
+Container Engine to run the tool images.
+
+## Registry and Repository
+A registry serves as a storage for the tool images, where they can be kept without occupying space on 
+the developer's computer. This storage enables convenient sharing of images with others, ensuring 
+uniform tool usage among all collaborators on the same project.
+When an image is uploaded to a registry, it initiates the creation of a repository. This repository 
+is responsible for keeping track of the various versions of the image.
+
+!!! Note
+
+    An image **repository** stores the different versions of the same image.  
+    An image **registry** is a collection of image repositories.
+
+The DEM also uses registries in the background to store the tool images. To list the currently 
+available registries use the `dem list-reg` command. The `dem add-reg` and `dem del-reg` commands 
+can be used to add or delete registries.
+
+!!! Note
+
+    The DEM supports the [Docker Hub](https://docs.docker.com/docker-hub/) and 
+    [Docker Registry](https://docs.docker.com/registry/)
+
+    If you'd like to request support for other registry types, please create a 
+    [new descussion](https://github.com/axem-solutions/dem/discussions/categories/regsitry).
+
+## Development Environment Catalogs
+A catalog is a collection of Development Environment descriptors.  
+The DEM can handle multiple catalogs. To list the currently available ones use the `dem list-cat` 
+command.  The `dem add-cat` and `dem del-cat` commands can be used to add or delete catalogs.
+
+!!! Note
+
+    axem has its own catalog, which is available by default.
+
+The users can browse these catalogs, and download a copy of the Development Environment descriptor 
+to their local catalog.
+
+![Catalogs](wp-content/dem_catalogs.png)
+
+## Development Platform
+The registries, the catalogs, and the whole development infrastructure are part of the Development 
+Platform. 
@@ -38,7 +38,7 @@ Arguments:
 
 ## **`dem create DEV_ENV_NAME`**
 
-Create a new Development Environment.
+Create a new Development Environment descriptor and save it to the local descriptor storage (catalog).
 
 Running this command will open up an interactive UI on the command line. Follow the steps below to
 configure the new Environment.
@@ -55,6 +55,8 @@ Select the required tool image and press :material-keyboard-return:.
 
     ![image select](wp-content/image_select.png)
 
+:info: After creation, the Development Environment can be installed with the `install` command.
+
 Arguments:
 
 `DEV_ENV_NAME` Name of the Development Environment to create. [required]
@@ -65,11 +67,12 @@ Arguments:
 
 Clone a Development Environment descriptor from the catalogs. 
 
-Only the Development Environment descriptor gets cloned, the required tool images are not pulled. To
-pull the required tool images, use the `install` command.  
+Only the Development Environment descriptor will be cloned, the required tool images won't be pulled.
 If a Development Environment with the same name has been already available on the host PC, the user
 will be asked if they want to overwrite it or not.
 
+:info: After cloning, the Development Environment can be installed with the `install` command.
+
 Arguments:
 
 `DEV_ENV_NAME` Name of the Development Environment, whose descriptor to clone. [required]
@@ -139,10 +142,10 @@ Arguments:
 
 ## **`dem install DEV_ENV_NAME`**
 
-Install the selected Development Environment. DEM pull all the required containerized tools (which 
+Install the selected Development Environment. DEM pulls all the required containerized tools (which 
 are not yet available on the host PC) from the registry and install the Development Environment 
 locally. If the same Development Environment is already installed, but the installation is not 
-complete, the missing tool images are obtained from the registry.
+complete, the missing tool images get obtained from the registry.
 
 Arguments:
 
@@ -152,9 +155,9 @@ Arguments:
 
 ## **`dem uninstall DEV_ENV_NAME`**
 
-Uninstall the selected Development Environment. Set installed flag to False if it was True. Dem checks whether a tool image is
-required or not by any of the remaining installed local Development Environments. In case the tool image is
-not required anymore, the dem delete it. 
+Uninstall the selected Development Environment. Sets the installed flag to False. DEM checks whether 
+a tool image is required or not by any of the remaining installed local Development Environments. In 
+case the tool image is not required anymore, the DEM tries to delete it. 
 
 Arguments:
 
@@ -169,7 +172,7 @@ Assign a Development Environment to a project.
 If the project already has a Development Environment assigned, the user will be asked if they want to
 overwrite it or not.
 
-Projects that have a Development Environment assigned can initialized with the `init` command.
+Projects that have a Development Environment assigned, can be initialized with the `init` command.
 
 Arguments:
 
@@ -184,6 +187,9 @@ working directory will be used.
 
 Initialize a project with the assigned Development Environment.
 
+:info: After the initialization, the Development Environment can be installed with the `install` 
+command.
+
 Arguments:
 
 `PROJECT_PATH` Path of the project to initialize. If not set, the current working directory will be
@@ -252,6 +258,8 @@ Imports a Development Environment.
     The file to import only contains the Development Environment descriptor. For a successful import
     the DEM needs access to all the registries where the required images are stored.
 
+:info: After the import, the Development Environment can be installed with the `install` command.
+
 Arguments:
 
 `PATH_TO_DEV_ENV` Path of the JSON file to import. Can be an absolute path or a relative path to the 
@@ -347,30 +355,6 @@ List the available hosts from the config file.
 
 ---
 
-## **`dem install DEV_ENV_NAME`**
-
-Install the selected Development Environment. Set installed flag to True. Dem checks which tool image is
-required by the selected local Development Environments and in case the tool image is
-not installed, the dem installs it. 
-
-Arguments:
-
-`DEV_ENV_NAME` Name of the Development Environment to install. [required]
-
----
-
-## **`dem uninstall DEV_ENV_NAME`**
-
-Uninstall the selected Development Environment. Set installed flag to False if it was True. Dem checks whether a tool image is
-required or not by any of the remaining installed local Development Environments. In case the tool image is
-not required anymore, the dem delete it. 
-
-Arguments:
-
-`DEV_ENV_NAME` Name of the Development Environment to uninstall. [required]
-
----
-
 ## **`dem del-host NAME`**
 
 Delete a host from the config file.

@@ -1,10 +1,10 @@
 ---
-title: Design
+title: Design (for DEM developers)
 ---
 
 ## Architectural Overview
 
-This chapter contains the technical documentation for the design.
+This chapter contains the technical documentation of the design.
 
 The Development Environment Manager (DEM) provides an abstraction layer for the Development 
 Platform, which encompasses a collection of available resources, such as registries, catalogs,