doc: big refac of documentation to move the content of the READMEs into the doc

README.md

 # Batmen
 
-Batmen is a plugin to the scientific simulator [Batsim]. It allows simulating users of large-scale distributed systems. Batmen is originally a fork of [batsched].
+Batmen is a plugin to the scientific simulator [Batsim].
+It allows simulating users of large-scale distributed systems. 
+Batmen is originally a fork of [batsched].
 
 ## How does it work?
 
@@ -28,94 +30,12 @@ For now, we have developed three types of users.
 - *replay users* (class `ReplayUser`): replaying a workload trace given as input
 - *feedback users* (class `FeedbackUser`): taking feedback on the status of previous jobs into account when submitting the next one 
 
-### Available schedulers
-Dynamic submission is supported by all the schedulers inheriting from the class `DynScheduler` i.e., all the schedulers located in the folder `src/scheds`. Some of them support multicore machines while others only support monocore machines. 
 
-- monocore schedulers:
-  - *fcfs*: jobs scheduled in their order of arrival ("first come first served")
-  - *easy-bf*: job scheduled in fcfs order, with possibility to execute ("backfill") small jobs that were submitted after if they don't postpone the starting time of the next job
-- multicore schedulers:
-  - *bin_packing*: the scheduler packs the jobs on the least number of multicore machines. Each job runs on only one host but can take several cores
-  - *bin_packing_energy*: same as *bin_packing*, but saves power by switching off the machines as soon as they are idle and powering them on again when needed
-  - *multicore_filler*: for test purposes. Schedules only one job at a time on only one multicore host.
 
-For guidance on how to add a new dynamic scheduler, refer to [this readme](src/scheds/readme.md).
 
 
-## Install
-With [Nix] package manager. At the root of the project:
 
-```bash
-nix-shell -A batmen # enter a Nix environment with all dependencies managed
-meson build # generate a build directory
-ninja -C build # compile the project into the build directory
-```
 
-Manually:
-TBD...
-
-## Run a small instance
-Follow the steps to install Batmen. The executable is at the location `build/batmen`. We suppose that you also have [Batsim] installed on your machine (follow the installation guide [here](https://batsim.readthedocs.io/en/latest/installation.html#installation)).
-
-To run a simulation, we will need **two terminals**:
-- one (Batmen) to simulate the users and the scheduler, and 
-- one (Batsim) to simulate the underlying infrastructure
-
-Create the output directory:
-
-```bash
-mkdir -p out/first_simu
-```
-
-Launch Batmen with 
-- the scheduler FCFS
-- one simulated user (described in the user description file `test/schedconf/routine_greedy_simple.json`) 
-
-```bash
-build/batmen -v fcfs \
-    --variant_options_filepath test/schedconf/routine_greedy_simple.json
-```
-
-Launch Batsim with
-- the platform file `test/platforms/monocore/2machines.xml`
-- an empty workload file `test/workloads/static/empty.json` (jobs are submitted dynamically by the simulated user)
-- the output directory
-- all the options required for Batmen to work properly (see their description in [Batsim CLI](https://batsim.readthedocs.io/en/latest/cli.html))  
-
-```bash
-path/to/batsim -p test/platforms/monocore/2machines.xml \
-    -w test/workloads/static/empty.json \
-    -e out/first_simu/ \
-    --energy --enable-compute-sharing \
-    --enable-dynamic-jobs --acknowledge-dynamic-jobs \
-    --enable-profile-reuse
-```
-
-After the execution, you should see the [Batsim outputs](https://batsim.readthedocs.io/en/latest/tuto-result-analysis/tuto.html) in the output directory.
-
-## Run the tests
-Batmen has a set of integration tests, located in the `test` directory. To run all the tests:
-
-```bash
-nix-shell -A test --command "pytest"
-```
-
-For more information about the tests, read the [test README](test/README.md)
-
-## Build the documentation
-Batmen documentation is hosted on readthedocs: [Batmen doc].
-It is automatically built and updated whenever there is a push on Batmen's `master` branch.
-
-To build the doc manually, we provide a dedicated nix shell.
-From Batmen root directory:
-
-```shell
-cd docs/
-nix-shell -A doc
-make html
-```
-
-The doc is generated inside the folder `docs/_build` and can be viewed on the browser by opening the file `docs/_build/html/index.html`. 
 
 [Nix]: https://nixos.org/nix/
 [Batsim]: https://batsim.org/

docs/dev/documentation.md

+## Build the documentation
+The present documentation is located in the folder `docs` and hosted on [readthedocs](https://batmen.readthedocs.io/en/latest/).
+It is automatically built and updated whenever there is a push on Batmen's `master` branch.
+
+To build the doc manually, we provide a dedicated nix shell.
+From Batmen root directory:
+
+```shell
+cd docs/
+nix-shell -A doc
+make html
+```
+
+The doc is generated inside the folder `docs/_build` and can be viewed on the browser by opening the file `docs/_build/html/index.html`. 
\ No newline at end of file

src/scheds/readme.md → docs/dev/scheduler.md

-# Steps to create a new dynamic scheduler
+# Create a new dynamic scheduler
 
 For now, if someone wants to create a new dynamic scheduler (or transform a static scheduler into dynamic), here is what one should do:
 

test/README.md → docs/dev/tests.md

-# Batmen tests
+# Automatic tests
 
 ## Run the tests
 We use [Nix] to enter an environment with all the dependencies.
+You can choose between two provided environments:
+- `test`: you need to compile Batmen yourself (see [](../user/installation.md)). It is useful in development phases.
+- `test_rebuild`: recompile Batmen before entering the environment.
 
-### `batmen` manually compiled
-This will run the test suite with the version of `batmen` located in the folder `build/`
+**Batmen manually compiled**:
+This will run the whole test suite with the version of `batmen` located in the folder `build/`.
+At the root of the project:
 
-``` bash
-nix-shell ../default.nix -A test
+```shell
+nix-shell -A test
 pytest
 ```
 
-### Recompile automatically
+**Recompile automatically:**
 If you want Nix to recompile `batmen` before entering the environment:
 
-``` bash
-nix-shell ../default.nix -A test_rebuild
+```shell
+nix-shell -A test_rebuild
 pytest
 ```
 
-### Browse the test outputs
+## Browse the test outputs
 Instead of reading the (long) outputs from the terminal, you can open `test-out/test_report.html` in a browser to see the test results.
 
-### Run an individual test
+## Run an individual test
 `pytest -k EXPRESSION` only runs the tests matching the given substring expression.
 
 For example, `pytest -k user` will only run the tests whose name contain "user".
@@ -30,14 +34,14 @@ For example, `pytest -k user` will only run the tests whose name contain "user".
 ## How does the testing work?
 pytest interprets all the functions starting with `test_` as tests. For one of these functions: 
 
-0. nix-shell puts you into an environment where batsched, batsim, robin, redis, etc. are available (code in [default.nix])
-1. pytest generates combinations of test input (code in [conftest.py])
+0. nix-shell puts you into an environment where batsched, batsim, robin, redis, etc. are available (code in `default.nix`)
+1. pytest generates combinations of test input (code in `test/conftest.py`)
 2. for each combination of inputs:
    1. pytest generates a [robin] input file
    2. pytest generates batsim and batmen input files if needed
    3. pytest executes [robin] or [robintest] on the generated file
 
-Finally, we have special tests (in the file [test_zexpected_output.py](./test_zexpected_output.py)) verifying that the output of the previous tests correspond to the expected output. 
+Finally, we have special tests (in the file `test/test_zexpected_output.py`) verifying that the outputs of the previous tests correspond to the expected outputs. 
 
 ## Debugging a failed test
 You can manually rerun a test with robin:
@@ -53,16 +57,14 @@ You can also run batsim and batsched in different terminals:
 ```
 
 ## Extra dependency
-Some tests use a tool from the library `batmen-tools` developped separately. To do update it to the latest version:
+Some tests use a tool from the library `batmen-tools` developped separately.
+To do update it to the latest version:
 
 ```bash
 cd batmen/test
 curl -O https://gitlab.irit.fr/sepia-pub/mael/batmen-tools/-/raw/main/distance_batsim_output.py
 ```
 
-[default.nix]: ../default.nix
-[conftest.py]: ./conftest.py
-[test_runner.py]: ./test_runner.py
 [robin]: https://framagit.org/batsim/batexpe
 [robintest]: https://framagit.org/batsim/batexpe
 [Nix]: https://nixos.org/nix/
\ No newline at end of file

docs/index.rst

@@ -7,16 +7,18 @@ Welcome to Batmen's documentation!
 ==================================
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
+   :caption: User manual:
 
-   user_categories.md
+   user/installation.md
+   user/first_simu.md
+   user/user_categories.md
+   user/schedulers.md
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Developer manual:
 
-
-Indices and tables
-==================
-
+   dev/tests.md
+   dev/documentation.md
+   dev/scheduler.md
\ No newline at end of file
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/user/first_simu.md

+# Run your first simulation
+
+Follow the [steps to install Batmen](./installation.md).
+The executable is at the location `build/batmen`.
+We suppose that you also have [Batsim] installed on your machine (follow the installation guide [here](https://batsim.readthedocs.io/en/latest/installation.html#installation)).
+
+To run a simulation, we will need **two terminals**:
+- one (Batmen) to simulate the users and the scheduler, and 
+- one (Batsim) to simulate the underlying infrastructure
+
+Create the output directory:
+
+```bash
+mkdir -p out/first_simu
+```
+
+Launch Batmen with 
+- the scheduler FCFS
+- one simulated user (described in the user description file `test/schedconf/routine_greedy_simple.json`) 
+
+```bash
+build/batmen -v fcfs \
+    --variant_options_filepath test/schedconf/routine_greedy_simple.json
+```
+
+Launch Batsim with
+- the platform file `test/platforms/monocore/2machines.xml`
+- an empty workload file `test/workloads/static/empty.json` (jobs are submitted dynamically by the simulated user)
+- the output directory
+- all the options required for Batmen to work properly (see their description in [Batsim CLI](https://batsim.readthedocs.io/en/latest/cli.html))  
+
+```bash
+path/to/batsim -p test/platforms/monocore/2machines.xml \
+    -w test/workloads/static/empty.json \
+    -e out/first_simu/ \
+    --energy --enable-compute-sharing \
+    --enable-dynamic-jobs --acknowledge-dynamic-jobs \
+    --enable-profile-reuse
+```
+
+After the execution, you should see the [Batsim outputs](https://batsim.readthedocs.io/en/latest/tuto-result-analysis/tuto.html) in the output directory.
\ No newline at end of file

docs/user/installation.md

+# Installation
+## With Nix (recommanded)
+For portability and reproducibility purposes, all the dependencies needed to compile Batmen are managed with [Nix] package manager.
+If you don't Nix on your machine, you can install it by following [their documentation](https://nixos.org/download.html).
+
+Once you have Nix installed, go to the root of the project:
+
+```bash
+nix-shell -A batmen # enter a Nix environment with all dependencies managed
+meson build # generate a build directory
+ninja -C build # compile the project into the build directory
+```
+
+## Manually
+TBD...
+
+
+
+[Nix]: https://nixos.org/nix/
\ No newline at end of file

docs/user/schedulers.md

+# Available schedulers
+
+Dynamic submission is supported by all the schedulers inheriting from the class `DynScheduler`
+i.e., all the schedulers located in the folder `src/scheds`.
+Some of them support multicore machines while others only support monocore machines. 
+
+- monocore schedulers:
+  - *fcfs*: jobs scheduled in their order of arrival ("first come first served")
+  - *easy-bf*: job scheduled in fcfs order, with possibility to execute ("backfill") small jobs that were submitted after if they don't postpone the starting time of the next job
+- multicore schedulers:
+  - *bin_packing*: the scheduler packs the jobs on the least number of multicore machines. Each job runs on only one host but can take several cores
+  - *bin_packing_energy*: same as *bin_packing*, but saves power by switching off the machines as soon as they are idle and powering them on again when needed
+  - *multicore_filler*: for test purposes. Schedules only one job at a time on only one multicore host.
+
+For guidance on how to add a new dynamic scheduler, refer to the [dedicated documentation](../dev/scheduler.md).
\ No newline at end of file