README improvements

Various clarifications and reformulations based on my experience using
the README to build and run Gargantext. In particular:
- Information related to development has been given its own section
- Docker Compose has been added to the list of prerequisites
- Information pertaining to using Stack has been moved to an annex file
- The content to be copypasted into a `cabal.project.local` file has been moved
  out of the README into a separate file `cabal.project.local_toCopy`

Those may not be the best decisions, I am happy to discuss them if
needed

README.md

@@ -7,12 +7,10 @@
 
 #### Table of Contents
 1. [About the project](#about)
-2. [Installation](#install)
-3. [Initialization](#init)
-4. [Launch & develop GarganText](#launch)
-5. [Uses cases](#use-cases)
-6. [GraphQL](#graphql)
-7. [PostgreSQL](#postgresql)
+2. [Installation and development](#install)
+3. [Uses cases](#use-cases)
+4. [GraphQL](#graphql)
+5. [PostgreSQL](#postgresql)
 
 ## About the project <a name="about"></a>
 
@@ -23,220 +21,138 @@ This software is free (as "Libre" in French) software, developed by the CNRS Com
 GarganText Project: this repo builds the backend for the frontend server built by [backend](https://gitlab.iscpif.fr/gargantext/haskell-gargantext).
 
 
-## Installation <a name="install"></a>
+## Installation and development <a name="install"></a>
 
 Disclaimer: since this project is still in development, this document remains in progress. Please report and improve this documentation if you encounter any issues.
 
-#### Prerequisites
+### Prerequisites
 
-- Install:
-  - [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
-  - [curl](https://everything.curl.dev/index.html)
-- Clone the project.
-  ```shell
-  git clone https://gitlab.iscpif.fr/gargantext/haskell-gargantext.git
-  cd haskell-gargantext
-  ```
-### Installation
+You must have the following installed:
 
-This project can be built with either Stack or Cabal. We keep up-to-date the `cabal.project` (which allows us
-to build with `cabal` by default) but we support `stack` thanks to thanks to
-[cabal2stack](https://github.com/iconnect/cabal2stack), which allows us to generate a valid `stack.yaml` from
-a `cabal.project`. Due to the fact gargantext requires a particular set of system dependencies (C++ libraries,
-toolchains, etc) we use [nix](https://nixos.org/) to setup an environment with all the required system
-dependencies, in a sandboxed and isolated fashion.
+- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+- [Curl](https://everything.curl.dev/index.html)
+- [Nix](https://nixos.org/download/)
+- [Docker Compose](https://docs.docker.com/compose/install/)
 
-#### Install Nix 
+### Building
 
-As said, Gargantext requires [Nix](https://github.com/NixOS/nix) to provide system dependencies (for example, C libraries), but its use is limited to that. In order to install [Nix](https://nixos.org/download.html):
+#### Cloning the project
 
+Clone this project in a directory of your choice, and enter the directory. Also, clone the frontend:
 ```shell
-sh <(curl -L https://nixos.org/nix/install) --daemon
+git clone https://gitlab.iscpif.fr/gargantext/haskell-gargantext.git
+cd haskell-gargantext
+git clone https://gitlab.iscpif.fr/gargantext/purescript-gargantext
 ```
 
-Verify the installation is complete with
-```shell
-nix-env --version
-nix-env (Nix) 2.19.2
-```
-
-**Important:** Before building the project with either `stack` or `cabal` you need to be in the correct Nix shell, which will fetch all the required system dependencies. To do so, just type **inside your haskell-gargantext folder**:
+#### Entering a Nix shell
 
+Enter a Nix shell. This will take a long time the first time you run it:
 ```shell
 nix-shell
 ```
 
-This will take a bit of time as it has to download/build the dependencies, but this will be needed only the first time.
-
-### Build: choose cabal (new) or stack (old)
-
-#### With Cabal (recommanded)
-
-##### Turning off optimization flags
-
-Create a `cabal.project.local` file (don't commit it to git!):
-```
-package gargantext
-    ghc-options: -fwrite-ide-info -hiedir=".stack-work/hiedb" -O0
-
-package gargantext-admin
-    ghc-options: -O0
-
-package gargantext-cli
-    ghc-options: -O0
-
-package gargantext-db-obfuscation
-    ghc-options: -O0
-
-package gargantext-import
-    ghc-options: -O0
-
-package gargantext-init
-    ghc-options: -O0
-
-package gargantext-invitations
-    ghc-options: -O0
+You can exit a Nix shell at any point with `exit`.
 
-package gargantext-phylo
-    ghc-options: -O0
+In what follows, many commands need to be executed from within the Nix shell. To make that clear, those will be prefixed with `n$`.
 
-package gargantext-server
-    ghc-options: -O0
-
-package gargantext-upgrade
-    ghc-options: -O0
-
-package gargantext-graph
-    ghc-options: -O0
-
-package hmatrix
-    ghc-options: -O0
-
-package sparse-linear
-    ghc-options: -O0
-```
-
-##### Building
-
-First, into `nix-shell`:
+If for some reason you do not want to enter a Nix shell, you can still run a command from outside:
 ```shell
-cabal update
-cabal install
+nix-shell --run "my command"
 ```
+is equivalent to running `my command` from within a Nix shell.
 
-Alternatively, if you want to run the command "from the outside", in your current shell:
+#### Disable optimization flags
 
-```
-nix-shell --run "cabal update"
-nix-shell --run "cabal install"
+Make a file `cabal.project.local` that will tell Cabal to turn off optimizations:
+```shell
+cp cabal.project.local_toModify cabal.project.local
 ```
 
-#### With Stack
+#### Build the backend
 
-Install [Stack (or Haskell Tool Stack)](https://docs.haskellstack.org/en/stable/):
+*Note: This project can be built with either stack or cabal. We keep the `cabal.project` up-to-date, which allows us to build with cabal by default but we support stack thanks to thanks to `cabal2stack`, which allows us to generate a valid `stack.yaml` from a `cabal.project`. Due to the fact gargantext requires a particular set of system dependencies (C++ libraries, toolchains, etc) we use nix to setup an environment with all the required system dependencies, in a sandboxed and isolated fashion.*
 
-```shell
-curl -sSL https://get.haskellstack.org/ | sh
-```
+*This documentation shows how to build with cabal. For information related to stack, see `docs/using_stack.md`.*
 
-Verify the installation is complete with
+From within the Nix shell, run:
 ```shell
-stack --version
-Version 2.9.1
+n$ cabal update
+n$ cabal install
 ```
 
-NOTE: Default build (with optimizations) requires large amounts of RAM (16GB at least). To avoid heavy compilation times and swapping out your machine, it is recommended to `stack build` with the `--fast` flag, i.e.:
+#### Build the frontend
 
+`cd` into the frontend directory and build:
 ```shell
-stack build --fast
+cd purescript-gargantext
+./install
+cd ..
 ```
 
+### Initializing
 
-#### Keeping the stack.yaml updated with the cabal.project
-
-(Section for Developers using stack only)
-
-Once you have a valid version of `stack`, building requires generating a valid `stack.yaml`.
-This can be obtained by installing `cabal2stack`:
+#### Configure database and NLP software bricks
 
 ```shell
-git clone https://github.com/iconnect/cabal2stack.git
-cd cabal2stack
+cd devops/docker
+docker compose up
 ```
 
-Then, depending on what build system you are using, either build with `cabal install --overwrite-policy=always` or `stack install`.
+The initialization schema should be loaded automatically from `devops/postgres/schema.sql`.
 
-And finally:
+#### Create configuration file
 
 ```shell
-cabal2stack --system-ghc --allow-newer --resolver lts-21.17 --resolver-file devops/stack/lts-21.17.yaml -o stack.yaml
-stack build
+cp gargantext.ini_toModify gargantext.ini
 ```
 
-The good news is that you don't have to do all of this manually; during development, after modifying the
-`cabal.project`, it's enough to do:
+> `.gitignore` excludes this file, so you don't need to worry about committing it by mistake, and you can change the passwords in `gargantext.ini` safely.
+
+#### Create master user
 
+From within the Nix shell:
 ```shell
-./bin/update-project-dependencies
+n$ gargantext-cli init --ini-path gargantext.ini
 ```
 
-## Initialization <a name="init"></a>
+The master user's name is automatically set to `gargantua`, but you will be prompted for their password and email address.
 
-#### 1. Docker-compose will configure your database and some NLP bricks (such as CoreNLP):
-
-First install docker-compose on your system and then:
-``` sh
-docker compose up
-```
-Initialization schema should be loaded automatically (from `devops/postgres/schema.sql`).
+### Launching and developing Gargantext <a name="launch"></a>
 
-##### (Optional) If using stack, then install:
-``` sh
-stack install
-```
+Once the project is setup, the following (except the backend build if you are working on the frontend, and vice versa) is what you will need to run to update after you have edited the source code.
 
-#### 2. Copy the configuration file:
-``` sh
-cp gargantext.ini_toModify gargantext.ini
-```
-> Do not worry, `.gitignore` avoids adding this file to the repository by mistake, then you can change the passwords in gargantext.ini safely.
+If you are working on the backend, you might want to use the `./start` script: it does all of that, except the frontend build.
 
-#### 3. A user have to be created first as instance:
+#### Building the backend
 
-In your nix-shell
-``` sh
-gargantext-cli init --ini-path "gargantext.ini"
+```shell
+./bin/install
 ```
-Now, `user1` is created with password `1resu`
-
-#### 4. Clone FRONTEND repository:
 
-From the Backend root folder (haskell-gargantext):
+#### Building the frontend
 
 ```shell
-git clone https://gitlab.iscpif.fr/gargantext/purescript-gargantext.git
-cd purescript-gargantext
+cd purescript-gargantext/
 ./install
+cd ..
 ```
-&nbsp;
 
-## Launch & develop GarganText <a name="launch"></a>
-
->  **Note:** here, the method with Cabal is used as default
+#### Running the Docker images
 
+If docker is not already running:
+```shell
+cd devops/docker
+docker compose up
+```
 
-From the Backend root folder (haskell-gargantext):
+#### Launching the Gargantext server
 
-``` shell
-./start
-# The start script runs following commands:
-# - `./bin/install` to update and build the project
-# - `docker compose up` to run the Docker for postgresql from devops/docker folder
-# - `cabal run gargantext-server -- --ini gargantext.ini --run Prod` to run other services through `nix-shell`
+From inside a Nix shell:
+```shell
+n$ cabal run gargantext-server -- --ini gargantext.ini --run Prod
 ```
 
-For frontend development and compilation, see the [Frontend Readme.md](https://gitlab.iscpif.fr/gargantext/purescript-gargantext#dev)
-
 ### Running tests
 
 From nix shell:
@@ -388,7 +304,3 @@ Maybe you need to restore the gargantua password
 ALTER ROLE gargantua PASSWORD 'yourPasswordIn_gargantext.ini'
 ```
 Maybe you need to change the port to 5433 for database connection in your gargantext.ini file.
-
-
-
-

cabal.project.local_toCopy

+package gargantext
+    ghc-options: -fwrite-ide-info -hiedir=".stack-work/hiedb" -O0
+
+package gargantext-admin
+    ghc-options: -O0
+
+package gargantext-cli
+    ghc-options: -O0
+
+package gargantext-db-obfuscation
+    ghc-options: -O0
+
+package gargantext-import
+    ghc-options: -O0
+
+package gargantext-init
+    ghc-options: -O0
+
+package gargantext-invitations
+    ghc-options: -O0
+
+package gargantext-phylo
+    ghc-options: -O0
+
+package gargantext-server
+    ghc-options: -O0
+
+package gargantext-upgrade
+    ghc-options: -O0
+
+package gargantext-graph
+    ghc-options: -O0
+
+package hmatrix
+    ghc-options: -O0
+
+package sparse-linear
+    ghc-options: -O0
+

docs/using_stack.md

+# Building Gargantext using the Stack tool
+
+Those are the instructions for developers who wish to build Gargantext using stack instead of cabal.
+
+## Prerequisites
+
+You need [Stack](https://docs.haskellstack.org/en/stable/) (obviously). You can install it with:
+```shell
+curl -sSL https://get.haskellstack.org/ | sh
+```
+
+Check that the installation is complete with:
+```shell
+stack --version
+Version 2.9.1
+```
+
+## Building and setting up
+
+To build with stack, follow the instructions in `README.md`, with the following changes:
+
+- Replace the `cabal update` and `cabal install` commands with (still from within a Nix shell!):
+```shell
+stack build --fast
+```
+
+*Note: The default build (with optimizations) requires large amounts of RAM (16GB at least). The (recommended) `--fast` flag is here to avoid heavy compilation times and swapping out your machine; just omit it if you want to build with optimizations.*
+
+- After you have run the `docker compose up` command, install with
+```shell
+stack install
+```
+
+## Keeping the stack.yaml updated with the cabal.project
+
+Once you have a valid version of stack, building requires generating a valid `stack.yaml`. This can be obtained by installing `cabal2stack`:
+```shell
+git clone https://github.com/iconnect/cabal2stack.git
+cd cabal2stack
+```
+
+Then, depending on what build system you are using, either build with `cabal install --overwrite-policy=always` or `stack install`.
+And finally:
+```shell
+cabal2stack --system-ghc --allow-newer --resolver lts-21.17 --resolver-file devops/stack/lts-21.17.yaml -o stack.yaml
+stack build
+```
+
+The good news is you don't have to do all of this manually; during development, after modifying `cabal.project`, it's enough to run:
+```shell
+./bin/update-project-dependencies
+```