From 73d9fb0618daf2e9fa37e5fdecb23867d7ffd214 Mon Sep 17 00:00:00 2001
From: Bo Maryniuk <bo@maryniuk.net>
Date: Sun, 15 Dec 2024 18:54:33 +0100
Subject: [PATCH] Add more information on Python modules and their purposes

---
 docs/moddev/overview.rst | 27 +++++++++++++++++++++++----
 docs/moddev/pymod.rst    |  9 +++++++++
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/docs/moddev/overview.rst b/docs/moddev/overview.rst
index 0b67414..11b2860 100644
--- a/docs/moddev/overview.rst
+++ b/docs/moddev/overview.rst
@@ -21,19 +21,38 @@ concerns:
 - Unpredictable environments can require different runtime constraints
 - It must be as simple as possible to extend SysInspect with own custom modules, enabling unequal programming skill levels
 
+There are two kind of purposes to call the modules:
+
+- System integration assertion
+- Applying a system state
+
+One can use either of these purposes or mix them together.
+
+Native Modules
+--------------
+
 Modules for SysInspect are essentially a standalone programs on their own, communicating
 via protocol in JSON format. Data exchange channel is done via STDIN/STDOUT. One can develop them
 in any language or scripts, as long as a Module is supporting defined communication protocol.
 This approach enables everyone to be as flexible and free as possible, adapting to any unpredictable
 environment and allowing to choose any technology one might like to.
 
-Python!?
-========
+Python Modules
+--------------
+
+.. important::
+
+    What!? Python? *Without* any extra kind of runtime??..
 
 Yes!
 
-Since version 0.2.0, SysInspect brings own Python runtime, specification 3.12. However,
-this runtime comes with a "frozen" standard library and does not support native modules. This means:
+Since version 0.2.0, SysInspect brings its own embedded Python runtime, specification 3.12. However,
+this runtime comes with the limitations. It contains a "frozen" standard library and does not support
+native modules. This means:
 
 - Anything which is written in Python supposed to work
 - Anything which is native (C or C++) will not work and will never be supported
+
+On the other hand, the entire Minion with the whole Python runtime and its standard
+"included batteries" costs just 29 Mb on the disk and is shipped just as one single static
+binary (``musl``).
diff --git a/docs/moddev/pymod.rst b/docs/moddev/pymod.rst
index 4810131..53b71b7 100644
--- a/docs/moddev/pymod.rst
+++ b/docs/moddev/pymod.rst
@@ -78,6 +78,15 @@ the CPU brand of the Minion:
 
         return str(r)
 
+Hacking
+-------
+
+In order to call own Python module and work on it, the easiest way is to just define an
+action in an own model and start calling it locally, using ``sysinspect`` utility:
+
+.. code-block:: shell
+
+    sysinspect -m <path/to/the/model> -e <entity> -s <state>
 
 Ansible Integration
 ===================