refactor: flesh introduction

f402ce9d · Menou Lucas · 7f726ace · f402ce9d · f402ce9d
Commit f402ce9d authored 9 months ago by Menou Lucas
--- a/docs/index.md
+++ b/docs/index.md
-# Welcome to the AstroNomical Information System Documentation
+# Welcome to the ANIS documentation

 ![anis_v3_logo](img/anis_v3_logo300.png#center)

 ## Introduction

-Welcome to the AstroNomical Information System, here after called, ANIS.
+Welcome to the *AstroNomical Information System (ANIS)* user's guide.
 Here you can find all the information you need to retrieve, install, and develop with the latest version of ANIS.

+ANIS is a web generic tool aimed at facilitating and homogenizing the implementation of astronomical data of various kinds and catalogues in dedicated Information Systems.
+
 ANIS includes:

- - `anis-server`: A JSON REST API that allows an administrator to configure datasets and allows users to search into business databases.
- - `anis-client`: A web client,
+ - __anis-server__: A JSON *Representational State Transfer (REST)* API that allows an administrator to configure datasets and allows users to search into business databases.
+ - __anis-client__: A web client,
    - That allows users to carry out searches and format the results.
    - That contains a dashboard reserved for administrators only, and which allows to set up scientific projects.
- - `anis-services`: An API used by anis-client for fits file manipulation (display fits, fits-cut, etc) with [astropy](https://www.astropy.org/).
- - `anis-tasks`: A `python` program that allows to launch asynchronous
-   tasks using the [rabbitMQ](https://www.rabbitmq.com/) message broker.
+ - __anis-services__: An API used by anis-client for fits file manipulation (display fits, fits-cut, etc) with [astropy](https://www.astropy.org/).
+ - __anis-tasks__: A `python` command line interface enabling the launch of asynchronous tasks using the [rabbitMQ](https://www.rabbitmq.com/) message broker.

 You can find here the complete public repository: [https://gitlab.lam.fr/anis/anis](https://gitlab.lam.fr/anis/anis).

@@ -26,39 +27,42 @@ You can find here the complete public repository: [https://gitlab.lam.fr/anis/an
     - Users can search the latter datasets using search criteria.
 - ANIS also provides an administration dashboard to manage datasets and configure search forms.
 - ANIS provides a web interface that allows users to perform, among other things, searches into datasets.
- - Scientific projects and/or datasets can be private and reserved to a consortium.
- - Specific visualizations can be attached to a dataset (spectrum graph, light curve, etc).
- - Asynchronous actions can be launched from the web interface (archive creation for example).
+     - Users can perform asynchronous actions from the web interface such as the archive creation for example.
+ - Scientific projects and/or datasets accessible through ANIS can be private and reserved to a consortium.
+ - ANIS includes specific visualizations tool for data such as spectrum graph, light curve, etc.

 ## Requirements

-To install the local version you need the following:
+To install and develop the local version of the software you need the following tools:

- `git` command
- `Make` command
- `Docker` and `docker-compose`
+- [git](https://git-scm.com/)
+- [docker](https://www.docker.com/)
+- Eventually [make](https://www.gnu.org/software/make/manual/make.html) to
+  shorten command lines

-To follow along the documentation, you also need `curl`.
+To follow along the documentation, you also need [curl](https://curl.se/docs/manpage.html).

 ## About this software

-The software ANIS is currently being developed by [a team](index.md#authors) at the `Laboratoire d'Astrophysique de Marseille` to meet the needs of the various scientific missions in which it is engaged.
+The software ANIS is currently being developed by [a team](index.md#authors) at the *Laboratoire d'Astrophysique de Marseille (LAM)* to meet the needs of the scientific missions in which the LAM is engaged.

 ![lam_logo](img/lam_logo.jpg#center)

 ## Licence

-AstroNomical Information System is governed by the CeCILL license (Version 2.1 dated 2013-06-21) 
-under French law and abiding by the rules of distribution of free software.
+AstroNomical Information System is governed by the CeCILL license (Version 2.1 dated 2013-06-21) under French law and abiding by the rules of distribution of free software.

-You can use, modify and/or redistribute the software under the terms of the CeCILL license as circulated by CEA, CNRS and INRIA at the following URL [https://cecill.info](https://cecill.info/index.en.html).
+You can use, modify, and/or redistribute the software under the terms of the
+CeCILL license as circulated by the *Commissariat à l'énergie atomique et aux
+énergies alternatives (CEA)* , the *Centre national de la recherche scientifique (CNRS)*, and the *Institut national de recherche en informatique et en automatique (Inria)* at the following URL
+[https://cecill.info](https://cecill.info/index.en.html).

 ## Authors

 Here is the list of people involved in the development:

-* `François Agneray` : Laboratoire d'Astrophysique de Marseille (CNRS)
-* `Chrystel Moreau` : Laboratoire d'Astrophysique de Marseille (CNRS)
-* `Lucas Menou` : Laboratoire D'astrophysique de Marseille (Short Term Contract - CNRS since 2023)
-* `Divin Angapay` : Laboratoire d'Astrophysique de Marseille (Short Term Contract - CNRS 2022-2023)
-* `Tifenn Guillas` : Laboratoire d'Astrophysique de Marseille (Short Term Contract - CNRS 2018-2022)
+* _François Agneray_ : Ingénieur de recherche CNRS
+* _Chrystel Moreau_ : Ingénieur de recherche CNRS
+* _Lucas Menou_ : Ingénieur de recherche - Short Term Contract - CNRS since 2023
+* _Divin Angapay_ : Ingénieur d'études - Short Term Contract - CNRS 2022-2023
+* _Tifenn Guillas_ : Ingénieur de recherche - Short Term Contract - CNRS 2018-2022
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -2,18 +2,17 @@

 ## Introduction

-Here are the steps to follow to install the software locally on your machine.
+This page describes the steps to follow to install the software locally on your machine.
 The examples provided works on a Linux system.

-The source code of ANIS is a monorepo projects that contains a `server`, a
-`client`, some `services` and some `tasks`. The following sections details the
+The source code of ANIS is a monorepo projects that contains a __server__, a
+__client__, some __services__ and some __tasks__. The following sections details the
 steps to install the previous stack.

-## Git Repository
+## Git repository

-The ANIS source code is available on a public
-[gitlab](https://about.gitlab.com/) repository. You can retrieve the ANIS
-project by cloning the official git project.
+The ANIS source code is available on a public [gitlab](https://about.gitlab.com/) repository.
+You can retrieve the ANIS project by cloning the official git project.

 ```bash
 $ git clone git@gitlab.lam.fr:anis/anis.git
@@ -22,18 +21,18 @@ $ cd anis

 ## Docker & docker-compose

-ANIS is designed to work through [docker containers](https://www.docker.com/).
-Each part of ANIS (`server`, `client`, `services` and `tasks`) runs in four respective containers.
+ANIS works through [docker containers](https://www.docker.com/).
+Each part of ANIS, the _server_, the _client_, the _services_ and _tasks_ runs in four respective containers.

 In the development mode, ANIS provides a `docker-compose` file that allows the management of containers (start, stop, restart, logs, etc).
 You can find the `docker-compose.yml` file at the root of the project. It aims to list all the containers necessary for the operation of ANIS.

 To operate, ANIS needs, with the four preceding containers, four other containers:

- - `keycloak`: Single sign-on with identity and access management. Used in ANIS to manage user accounts and dataset rights.
- - `postgres`: Database management system used to install the configuration database and the test business database.
- - `rabbitmq`: Message-broker software used to launch asynchronous tasks.
- - `maildev`: Software used to send or receive emails in development mode.
+ - [keycloak](https://www.keycloak.org/): Authentication and access management software.
+ - [postgres](https://www.postgresql.org/): Database management system used to install the configuration database and the test business database.
+ - [rabbitmq](https://www.rabbitmq.com/): Message-broker software used to launch asynchronous tasks.
+ - [maildev](https://github.com/maildev/maildev): Software used to send or receive emails in development mode.

 ## Makefile