From d586de6f16be180c7c5a1b3f4852aca649e4c4c0 Mon Sep 17 00:00:00 2001
From: Luigi Pertoldi <luigi.pertoldi@protonmail.com>
Date: Sun, 29 Dec 2024 13:20:14 +0100
Subject: [PATCH] Update documentation

---
 docs/developer.md | 31 +++++++++++++++++++++++++++++++
 docs/index.md     |  8 +++++---
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/docs/developer.md b/docs/developer.md
index e45558df..4cfc42ab 100644
--- a/docs/developer.md
+++ b/docs/developer.md
@@ -17,6 +17,33 @@ your GitHub username):
 $ git clone git@github.com:yourusername/remage.git
 ```
 
+## That `remage` executable...
+
+To enhance _remage_'s capabilities without requiring complex C++ code, we
+implemented a Python wrapper. This wrapper handles input preprocessing, invokes
+the `remage-cpp` executable, and performs output postprocessing. While this
+approach slightly complicates the build system, it significantly reduces the
+amount of code to write and maintain.
+
+The C++ code resides in the `src` directory, with the `remage-cpp` executable
+built from `src/remage.cc`. The Python code is organized as a package under the
+`python` directory, where the `cli.py` module provides the _remage_ command-line
+interface.
+
+At build time, CMake compiles `remage-cpp` and installs the Python package in
+the build area. The Python package and its dependencies (see `pyproject.toml`)
+are installed into a virtual environment, ensuring an isolated environment with
+all required dependencies. The Python wrapper is configured to use the
+`remage-cpp` executable from the build area.
+
+This setup is replicated during installation, targeting the install prefix. A
+key advantage of this approach is enabling the use of the _remage_ executable in
+unit tests, which run on _remage_ from the build area.
+
+Information about the C++ part of _remage_ is forwarded to the Python wrapper
+via the `cmake/cpp_config.py.in` file, which is configured by CMake at build
+time and moved into the package source folder.
+
 ## Installing dependencies
 
 ```{include} _dependencies.md
@@ -35,6 +62,10 @@ $ cmake -DCMAKE_INSTALL_PREFIX=<optional prefix> ..
 $ make install
 ```
 
+```{tip}
+A list of available Make targets can be printed by running `make help`.
+```
+
 ## Code style
 
 A set of [pre-commit](https://pre-commit.com) hooks is configured to make sure
diff --git a/docs/index.md b/docs/index.md
index f97adb51..6b6b5e8b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,9 +6,11 @@ _remage_ is a modern C++ simulation framework for germanium experiments.
 
 The installation process is documented in {doc}`install`.
 
-:::{warning} A proper user guide is not available yet. In the meanwhile, users
-can have a look at the {doc}`tutorial` or the provided
-[examples](https://github.com/legend-exp/remage/tree/main/examples). :::
+```{warning}
+ A proper user guide is not available yet. In the meanwhile, users can have a
+look at the {doc}`tutorial` or the provided
+[examples](https://github.com/legend-exp/remage/tree/main/examples).
+```
 
 In the simplest application, the user can simulate in an existing GDML geometry
 through the `remage` executable: