doc update

Develop.md

@@ -8,10 +8,10 @@
 
 ## Basic development
 
-Generate `nicobot/version.py` & install Python dependencies (for both building and running) with :
+Install Python dependencies (for both building and running) and generate `nicobot/version.py` with :
 
-    python3 setup.py build
     pip3 install -r requirements-build.txt -r requirements-runtime.txt
+    python3 setup.py build
 
 To run unit tests :
 
@@ -147,6 +147,25 @@ It emphasizes *FROM* and *COPY* relations between the images (base and stages).
 [The open issues labelled with *docker*](https://github.com/nicolabs/nicobot/labels/docker) should reference the reasons for missing arch / configuration.
 
 
+### Docker image structure
+
+Here are the main application files and directories from within the images :
+
+    📦 /
+     ┣ 📂 root/
+     ┃ ┗ 📂 .local/
+     ┃   ┣ 📂 bin/  - - - - - - - - - - - - - -> shortcuts
+     ┃   ┃ ┣ 📜 askbot
+     ┃   ┃ ┣ 📜 transbot
+     ┃   ┃ ┗ 📜 ...
+     ┃   ┣ 📂 lib/pythonX.X/site-packages/  - -> Python packages (nicobot & dependencies)
+     ┃   ┗ 📂 share/signal-cli/ - - - - - - - -> signal-cli configuration files
+     ┗ 📂 usr/src/app/  - - - - - - - - - - - -> app's working directory, default configuration files, ...
+       ┣ 📂 .omemo/ - - - - - - - - - - - - - -> OMEMO keys (XMPP)
+       ┣ 📜 docker-entrypoint.sh
+       ┣ 📜 i18n.en.yml
+       ┗ 📜 ...
+
 
 ## Versioning
 
@@ -157,10 +176,12 @@ There were several options among which the following one has been retained :
 1. Running `setup.py` creates / updates the version inside the `version.py` file
 2. The scripts then load this module at runtime
 
-Since the `version.py` file is not saved into the project, `setup.py` must be run before the version can be queried. In exchange :
+Since the `version.py` file is not saved into the project, `setup.py build` must be run before the version can be queried. In exchange :
 - it does not require _setuptools_ nor _git_ at runtime
 - it frees us from having the `.git` directory around at runtime ; this is especially useful to make the docker images smaller
 
+Tip : `python3 setup.py --version` will print the guessed version.
+
 
 
 ## Building signal-cli

README.md

@@ -103,10 +103,10 @@ The container is invoked this way :
 
     docker ... [--signal-register <device name>] [--qrcode-options <qr options] <bot name> [<bot arguments>]
 
-- `--signal-register` will display a QR code in the console : scan it with the Signal app on the device to link the bot with (it will simply do the *signal-cli link* command inside the container ; read more about this later in this document). If this option is not given and the _signal_ backend is used, it will use the `.local/share/signal-cli` directory from the container (you _have_ to mount it) or fail. This option takes a custom device name as its argument.
+- `--signal-register` is Signal-specific. It will display a QR code in the console : scan it with the Signal app on the device to link the bot with (it will simply do the *signal-cli link* command inside the container ; read more about this later in this document). If this option is not given and the _signal_ backend is used, it will use the `.local/share/signal-cli` directory from the container (you _have_ to mount it) or fail. This option takes a custom device name as its argument.
-- `--qrcode-options` takes as argument a string of options to pass to the QR code generation command (see [python-qrcode](https://github.com/lincolnloop/python-qrcode)).
+- `--qrcode-options` is Signal-specific. It takes as argument a string of options to pass to the QR code generation command (see [python-qrcode](https://github.com/lincolnloop/python-qrcode)).
 - `<bot name>` is either `transbot` or `askbot`
-- `<bot arguments>` is the list of arguments to pass to the bot (see bots' usage) 
+- `<bot arguments>` is the list of arguments to pass to the bot (see bots' usage)
 
 If any doubt, just invoke the image without argument to print the inline help statement.
 
@@ -153,7 +153,16 @@ Sample configuration can be found in `tests/askbot-sample-conf`.
 
 
 
-#### Example
+#### Examples
+
+##### Simple example (with Jabber)
+
+    askbot -b jabber -U mybot@myserver.im -r me@myserver.im --jabber-password 'Myb0tp@SSword' -m "Hello You !" -p bye 'bye'
+
+Will say 'Hello You !' to me@myserver.im, and for a message containing 'bye' to quit.
+If the recipient handles it, the communication will be end-to-end encrypted with OMEMO.
+
+##### More complex example (and with Signal)
 
     askbot -m "Do you like me ?" -p yes '(?i)\b(yes|ok)\b' -p no '(?i)\bno\b' -p cancel '(?i)\b(cancel|abort)\b' --max-count 3 -b signal -U '+33123456789' --recipient '+34987654321'