Merge branch '16-documentation-improvement' into 'unstable'

Improve the README.md

See merge request Neutrinet/neutrinet_cube_install!21

README.md

@@ -8,47 +8,91 @@ A script to easily install Neutrinet internetcubes
 
 # Requirements
 
-You will need the following packages installed on your system:
-```
+You will need the packages `git`, `curl`, `jq`, `unzip`, `gpg` installed on your system.  
+In addition, some parts of this script require sudo access to be executed.
+
+On Debian based distributions you can run
+```shell
 sudo apt install git curl jq unzip gpg
 ```
-In addition, some parts of this script require sudo access to be executed.
 
-# About this script
+# How to use this script
+## What the script does
 
-This script is meant to make it easier to install a Neutrinet internet cube. Download the neutrinet_cube_install.sh script, run it, and follow the instructions.
-```bash
-bash neutrinet_cube_install.sh
+The script will ask several questions needed to set up the Neutrinet cube, including usernames and passwords.  
+A file called `install.hypercube` will be created containing this information.  
+If an `install.hypercube` is already found, you'll be asked if you want to reuse these answers first.  
+If you choose to reuse the answers, the script won't ask the questions again.
+
+Questions that will be asked and stored in the `install.hypercube` file are:
+* What domain to use. If you do not have your own domain, you can get a free subdomain under `.nohost.me`, `.noho.st` or `.ynh.fr`.
+* A username for the first user on the cube
+* Your firstname and lastname. These are the firstname and lastname that will be configured on the cube. You can give any names you want, but it can't be blank.
+* A password for this user 
+* A password for the admin interface
+* Your Neutrinet VPN credentials
+* A name and password for the wifi hotspot
+
+The script will then download several resources in order to set up the image to install and configure the cube.  
+These files will be kept in a folder called `cube_resources`.  
+If you run the script with this folder already present, it will try to find the files there instead of downloading everything again.
+
+Once everything is set up, the script will ask you to insert your micro-SD card and flash the image on it.
+
+Once this is done, you can assemble your cube and let the script look for your cube on the network.  
+You can follow the progress of the configuration via `http://<cube-ip>:2468/install.html`. Make sure you have Javascript enabled for this.
+
+When the script has either finished or has failed, it will ask you if you want to remove the `cube_resources` folder and `install.hypercube` file.  
+A good reason to keep the `cube_resources` folder is if you want to do multiple installation.  
+A good reason to keep the `install.hypercube` file is if the script failed for some reason and you want to rerun it.  
+Note that the `install.hypercube` file has your passwords, so you shouldn't keep it longer than needed!
+
+It can take about two hours from downloading and running the script until the Neutrinet cube is fully installed and configured.
+
+## Downloading the script
+
+The easiest way to get the script is by cloning the whole project and navigate to it.
+```shell
+git clone https://git.domainepublic.net/Neutrinet/neutrinet_cube_install
+cd neutrinet_cube_install
 ```
-This will create a subfolder `cube_resources` containing the install-sd.sh script and the internetcube images for your board.
 
-If you are planning on installing multiple cubes, you may consider dedicating a folder on your PC/laptop for this and run
-```bash
+## Running the script
+
+After you cloned the package, you can run the script and follow the instructions
+```shell
+bash neutrinet_cube_install.sh
+```
+If you are planning on installing multiple cubes at a later time, you may consider dedicating a folder on your PC/laptop for this and run
+```shell
 bash neutrinet_cube_install.sh -p
 ```
-This will download the install-sd.sh and internetcube images for lime and lime2. Everything will be stored in the `cube_resources` subfolder.
+This will create a `cube_resources` folder and already download and prepare as much as possible.
 
 For more information you can use the -h option:
-```bash
+```shell
 bash neutrinet_cube_install.sh -h
 ```
 
-# Translations
+## Running the script using translations
 
-You can change the language of this script with the `LANGUAGE` environment variable:
+You can change the language of this script with the `LANGUAGE` environment variable. For French you can do
 ```shell
 LANGUAGE=fr bash neutrinet_cube_install.sh
 ```
 
-You can start a translation by using the template translation file `locale/neutrinet.pot`.
-For instance, you can open it with [poedit](https://poedit.net/) to start a translation.
+# Contributing
+
+## Adding translations
+
+You can start a translation by using the template translation file `locale/neutrinet.pot`.  
+You can open it with [poedit](https://poedit.net/) to start a translation.
 
 This template file can be generated with:
 ```shell
 bash --dump-po-strings neutrinet_cube_install.sh | msguniq -o locale/neutrinet.pot
 ```
 
-# Contributing
+## Bugs, features and issues
 * Bugs, feature requests and other issues can be logged on the issue tracker at https://git.domainepublic.net/Neutrinet/neutrinet_cube_install/issues
-* Merge requests should be submitted at https://git.domainepublic.net/Neutrinet/neutrinet_cube_install/
-* Merge requests should be done to the `unstable` branch
+* Merge requests should be submitted to the `unstable` branch https://git.domainepublic.net/Neutrinet/neutrinet_cube_install/