Add documentation for the EVerest Development Container (EVerest#1693)

Add a note to the 'Getting started in Software' how-to, linking to devcontainers

Signed-off-by: Andreas Heinrich <andreas.heinrich@rwth-aachen.de>
Signed-off-by: Christoph Burandt <christoph.burandt@pionix.de>
Signed-off-by: Piet Gömpel <37657534+Pietfried@users.noreply.github.com>
Co-authored-by: Piet Gömpel <37657534+Pietfried@users.noreply.github.com>

Author: andistorm

docs/source/explanation/devcontainer-internal/index.rst

@@ -0,0 +1,118 @@
+##############################################
+Internals of the EVerest Development Container
+##############################################
+
+This document explains the internal working of the EVerest
+development container (devcontainer) for different setup variants
+and how things are connected.
+
+For a more hands-on explanation, consider reading:
+
+- :doc:`Tutorial: Setup the EVerest Development Container </tutorials/setup-devcontainer/index>`
+- :doc:`How-to Guide: How to use a development container for EVerest development and sil testing </how-to-guides/devcontainer-usage/index>`
+
+*******************************
+The Docker Compose Project Name
+*******************************
+
+The Docker Compose project name determines how containers are
+named and grouped. By default, it uses the
+**current folder name with _devcontainer suffix**
+(consistent with VSC behavior), but can be customized.
+
+Set the environment variable ``DOCKER_COMPOSE_PROJECT_NAME``
+to your desired project name before building/starting the devcontainer.
+
+For example:
+
+.. code-block:: bash
+
+    DOCKER_COMPOSE_PROJECT_NAME=my-project ./applications/devrd/devrd Start
+
+This will name the containers with the pattern:
+
+``{project_name}-{service}-1``, where
+
+- ``{project_name}`` is the value of ``DOCKER_COMPOSE_PROJECT_NAME``
+- ``{service}`` is the service name defined in the docker-compose files
+- ``1`` is the instance number (default is 1)
+
+*********************
+Environment Variables
+*********************
+
+You can generate an ``.env`` file with auto-detected values using this command:
+
+.. code-block:: bash
+
+    ./applications/devrd/devrd env
+
+This will create a ``.devcontainer/.env`` file with the following content:
+
+.. code-block:: bash
+
+    # Auto-generated by setup script
+    ORGANIZATION_ARG=EVerest
+    REPOSITORY_HOST=github.com
+    REPOSITORY_USER=git
+    COMMIT_HASH=<..>
+    EVEREST_TOOL_BRANCH=main
+    UID=<..>
+    GID=<..>
+    HOST_WORKSPACE_FOLDER=<..>
+
+These variables are automatically mapped in the container to the following environment variables:
+
+- ``ORGANIZATION_ARG``: Maps to ``EVEREST_DEV_TOOL_DEFAULT_GIT_ORGANIZATION``
+- ``REPOSITORY_HOST``: Maps to ``EVEREST_DEV_TOOL_DEFAULT_GIT_HOST``
+- ``REPOSITORY_USER``: Maps to ``EVEREST_DEV_TOOL_DEFAULT_GIT_SSH_USER``
+- ``EVEREST_TOOL_BRANCH``: Maps to ``EVEREST_TOOL_BRANCH``
+- ``HOST_WORKSPACE_FOLDER``: The directory mapped to ``/workspace`` inside the container
+
+Use this mechanism if you have a different organization or git host or user.
+This is useful if you have forked and you are hosting your development outside github.
+
+************************
+Workspace Folder Mapping
+************************
+
+The ``/workspace`` directory inside the container can be mapped
+to any folder on your host system. The workspace folder is
+determined in the following priority order:
+
+1. **Command line option**: ``-w`` or ``--workspace`` flag
+2. **Environment variable**: ``HOST_WORKSPACE_FOLDER`` environment variable
+3. **`.env` file**: ``HOST_WORKSPACE_FOLDER`` value in ``.devcontainer/.env``
+4. **Current directory**: Falls back to the current working directory
+
+The ``.devcontainer`` directory (containing ``.env`` and Docker Compose files)
+is always located relative to where the ``devrd`` script is installed.
+This allows you to:
+
+- Run ``devrd`` from any directory in your workspace
+- Use a single ``devrd`` installation to manage multiple workspaces by changing ``HOST_WORKSPACE_FOLDER`` in the ``.env`` file
+
+One can set workspace mapping via command line:
+
+.. code-block:: bash
+
+    ./applications/devrd/devrd env -w /path/to/workspace
+
+Or edit ``.devcontainer/.env`` directly and set ``HOST_WORKSPACE_FOLDER``
+Then run from anywhere:
+
+.. code-block:: bash
+
+    cd /path/to/workspace/subfolder
+    ../applications/devrd/devrd start  # Works correctly, uses workspace from .env file
+
+***************
+Troubleshooting
+***************
+
+See the :doc:`separate troubleshooting section </tutorials/setup-devcontainer/troubleshooting>` for help
+on devcontainer-specific issues.
+
+----
+
+**Authors:** Florian Mihut, Andreas Heinrich

docs/source/explanation/index.rst

@@ -9,85 +9,92 @@ Let us have a look at the most important topics first.
 Below that, you will be presented with a categorized list of all articles.
 
 .. grid:: 1 2 2 3
-   :gutter: 2
+    :gutter: 2
 
-   .. grid-item-card:: Framework Overview
-      :link: high-level-overview
-      :link-type: doc
+    .. grid-item-card:: Framework Overview
+        :link: high-level-overview
+        :link-type: doc
 
-      Get a high-level overview of the EVerest framework.
+        Get a high-level overview of the EVerest framework.
 
-   .. grid-item-card:: Error Framework
-      :link: error-framework
-      :link-type: doc
+    .. grid-item-card:: Error Framework
+        :link: error-framework
+        :link-type: doc
 
-      How to communicate error states between modules.
+        How to communicate error states between modules.
 
-   .. grid-item-card:: EVerest Modules in Detail
-      :link: detail-module-concept
-      :link-type: doc
+    .. grid-item-card:: EVerest Modules in Detail
+        :link: detail-module-concept
+        :link-type: doc
 
-      Learn about the module concept of EVerest.
+        Learn about the module concept of EVerest.
 
-   .. grid-item-card:: Tier Module Mapping
-      :link: tier-module-mappings
-      :link-type: doc
+    .. grid-item-card:: Tier Module Mapping
+        :link: tier-module-mappings
+        :link-type: doc
 
-      EVerest's 3-tier module mapping explained.
+        EVerest's 3-tier module mapping explained.
 
-   .. grid-item-card:: Adapt EVerest
-      :link: adapt-everest/index
-      :link-type: doc
+    .. grid-item-card:: Adapt EVerest
+        :link: adapt-everest/index
+        :link-type: doc
 
-      Learn how EVerest can be adapted to your use-case.
+        Learn how EVerest can be adapted to your use-case.
 
-   .. grid-item-card:: The EVerest Dependency Manager
-      :link: dev-tools/edm
-      :link-type: doc
+    .. grid-item-card:: The EVerest Dependency Manager
+        :link: dev-tools/edm
+        :link-type: doc
 
-      Tool helping to orchestrate dependencies between the different EVerest repositories.
+        Tool helping to orchestrate dependencies between the different EVerest repositories.
 
-   .. grid-item-card:: The ev-cli Development Tool
-      :link: dev-tools/edm
-      :link-type: doc
+    .. grid-item-card:: The ev-cli Development Tool
+        :link: dev-tools/edm
+        :link-type: doc
 
-      Command line tool to generate C++ code from interface and manifest definitions.
+        Command line tool to generate C++ code from interface and manifest definitions.
 
-   .. grid-item-card:: The Plug&Charge Process in EVerest
-      :link: dev-tools/edm
-      :link-type: doc
+    .. grid-item-card:: The Plug&Charge Process in EVerest
+        :link: dev-tools/edm
+        :link-type: doc
 
-      Learn how Plug&Charge is implemented in EVerest.
+        Learn how Plug&Charge is implemented in EVerest.
 
-   .. grid-item-card:: Linux / Yocto and EVerest
-      :link: linux-yocto/index
-      :link-type: doc
+    .. grid-item-card:: Linux / Yocto and EVerest
+        :link: linux-yocto/index
+        :link-type: doc
 
-      Learn how to integrate EVerest in your embedded application via Yocto and allow for secure OTA updates.
+        Learn how to integrate EVerest in your embedded application via Yocto and allow for secure OTA updates.
 
-   .. grid-item-card:: Hardware Architecture
-      :link: hardware-architecture
-      :link-type: doc
+    .. grid-item-card:: Hardware Architecture
+        :link: hardware-architecture
+        :link-type: doc
 
-      Some ideas and guidance on the general architecture of AC or DC chargers.
+        Some ideas and guidance on the general architecture of AC or DC chargers.
 
-   .. grid-item-card:: Powermeter OCMF Handling
-      :link: powermeter-ocmf
-      :link-type: doc
+    .. grid-item-card:: Powermeter OCMF Handling
+        :link: powermeter-ocmf
+        :link-type: doc
 
-      How OCMF records are expected to be handled by modules implementing powermeters.
+        How OCMF records are expected to be handled by modules implementing powermeters.
 
-   .. grid-item-card:: A Selection of included Hardware Drivers
-      :link: hardware-drivers
-      :link-type: doc
+    .. grid-item-card:: A Selection of included Hardware Drivers
+        :link: hardware-drivers
+        :link-type: doc
 
-      Description of natively supported hardware driver modules included in EVerest.
+        Description of natively supported hardware driver modules included in EVerest.
 
-   .. grid-item-card:: Structure of the EVerest Documentation
-      :link: the-everest-documentation
-      :link-type: doc
+    .. grid-item-card:: Structure of the EVerest Documentation
+        :link: the-everest-documentation
+        :link-type: doc
 
-      How this documentation is structured.
+        How this documentation is structured.
+   
+    .. grid-item-card:: Use the EVerest Development Container
+        :link: devcontainer-internal/index
+        :link-type: doc
+
+        Internal working of the EVerest development container
+        for different setup variants and how things are connected.
 
 .. toctree::
     :hidden:
@@ -107,3 +114,4 @@ Below that, you will be presented with a categorized list of all articles.
     hardware-drivers
     the-everest-documentation
     powermeter-ocmf
+    devcontainer-internal/index