Improve documentation

README.md

@@ -92,9 +92,9 @@ alt="compreface-dashboard-page" width="390px" style="padding: 0px 0px 0px 10px;"
   <!-- have to be followed by an empty line! -->
 
 <p align="center">
-<img src="https://github.com/exadel-inc/CompreFace/assets/3736126/3ae0ce68-588b-4370-8eaf-32668c96fa63"
+<img src="https://github.com/exadel-inc/CompreFace/assets/3736126/3ae0ce68-588b-4370-8eaf-32668c96fa63" 
 alt="compreface-verification-page" width=390px style="padding: 0px 10px 0px 0px;">
-<img src="https://github.com/exadel-inc/CompreFace/assets/3736126/9246702d-1c9b-4435-8098-89e0fb616b0d"
+<img src="https://github.com/exadel-inc/CompreFace/assets/3736126/9246702d-1c9b-4435-8098-89e0fb616b0d" 
 alt="compreface-detection-page" width="390px" style="padding: 0px 0px 0px 10px;">
 </p>
 <p align="center">
@@ -185,14 +185,14 @@ The system can accurately identify people even when it has only “seen” their
 2. Download the archive from our latest release: https://github.com/exadel-inc/CompreFace/releases
 3. Unzip the archive
 4. Run Docker
-5. Open Command prompt (write `cmd` in windows search bar)
-6. Open folder where you extracted zip archive (Write `cd path_of_the_folder`, press enter).
+5. Open Command prompt (Type `cmd` in windows search bar)
+6. Open folder where you extracted zip archive (Type `cd path_of_the_folder`, press enter).
 7. Run command: `docker-compose up -d`
 8. Open http://localhost:8000/login
 
 ### Getting started for contributors
 
-Follow this [link](/dev)
+Follow this [link](/dev).
 
 # CompreFace SDKs
 
@@ -204,7 +204,7 @@ Follow this [link](/dev)
 
 # Documentation
 
-More documentation is available [here](/docs)
+More documentation is available [here](/docs).
 
 # Contributing
 
@@ -220,6 +220,6 @@ We want to improve our open-source face recognition solution, so your contributi
 
 For more information, visit our [contributing](CONTRIBUTING.md) guide, or create a [discussion](https://github.com/exadel-inc/CompreFace/discussions).
 
-# License info 
+# License info
 
 CompreFace is open-source real-time facial recognition software released under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html).

dev/README.md

@@ -9,7 +9,7 @@
 
 #### Tips for Windows (use Git Bash terminal)
 
-1. Turn of the git autocrlf with command: `git config --global core.autocrlf false`
+1. Turn off the git autocrlf with command: `git config --global core.autocrlf false`
 2. Make sure all your containers are down: `docker ps`
 3. In case some containers are working, they should be stopped: `docker-compose down`
 4. Clean all local datebases and images: `docker system prune --volumes`

docs/Face-data-migration.md

@@ -35,9 +35,10 @@ enough, so please do a backup copy of the database and perform migration
 at your own risk.
 
 REST request to start migration:
-
+```shell
     curl -i -X POST \
     'http://localhost:8000/api/v1/migrate'
+```
 
 This rest endpoint is asynchronous; it starts the migration and returns
 a response immediately. Please look at logs for "Migration successfully

docs/Face-services-and-plugins.md

@@ -13,7 +13,7 @@ CompreFace supports these face services and plugins:
 
 # Services
 
-To use face service you need to create it in an application on UI. 
+To use face service you need to create it in an application on the UI. 
 The type of service depends on your application needs. 
 Each service has its own REST API context and there is no possibility to change the service type after creation. 
 Here is a short description of each of them:
@@ -23,7 +23,7 @@ Here is a short description of each of them:
 Face detection service is used to detect all faces in the image. 
 It doesn’t recognize faces, just finds them on the image.
 
-**Cases of use**
+**Use cases**
 
 The most useful cases include face plugins for face analysis:
   * gather statistics on how your store popular among different genders
@@ -57,7 +57,7 @@ Face recognition service is used for face identification. This means that you fi
 then recognize unknown faces among them. When you upload an unknown face, the service returns the most similar faces to it. 
 Also, face recognition service supports verify endpoint to check if this person from face collection is the correct one. 
 
-**Cases of use**
+**Use cases**
 
 The possible cases include:
   * when you have photos of employees and want to recognize strangers in the office
@@ -88,7 +88,7 @@ Example:
 Face verification service is used to check if this person is the correct one. 
 The service compares two faces you send to the rest endpoint and returns their similarity. 
 
-**Cases of use**
+**Use cases**
 
 The possible cases include:
   * when a customer provides you an ID or driving license and you need to verify if this is him

docs/Gathering-anonymous-statistics.md

@@ -20,16 +20,16 @@ Privacy Policy and agree to send anonymous statistics to our servers.
     name, email password, etc.).
 -   Event of application creation - we record only the fact of the
     creation of a new application. We do not gather any information
-    about the application(like name, which users have access to it,
+    about the application (like name, which users have access to it,
     etc.).
 -   Event of service creation - we record only the creation of a new
     service and its type. We do not gather any information about the
-    service(like name, etc.).
+    service (like name, etc.).
 -   The number of saved faces in Face Recognition service Collection.
     Every day we record how many faces are saved in Collection in
     ranges: 1-10, 11-50, 51-200, 201-500, 501-2000, 2001-10000,
     10001-50000, 50001-200000, 200001-1000000, 1000001+. We do not
-    gather any information about the faces(like face name, embedding,
+    gather any information about the faces (like face name, embedding,
     etc.).
 
 #### What we do NOT collect:
@@ -62,6 +62,7 @@ that this is the same installation as before.
 "2021-03-13 13:25:50.003","59638de4-5fca-11eb-848b-0242ac120002","39c1925d-a1a9-4d44-8eb3-6acf132b89f2","1-10"
 "2021-03-13 13:25:50.763","59638de4-5fca-11eb-848b-0242ac120002","794dd0ec-ac88-4552-90a8-f0bb0ddcee1e","201-500"
 ```
+
 #### How we use the data
 
 The data is used to understand the popularity of different services, how
@@ -73,5 +74,4 @@ self-promotional goals, like "CompreFace has N active users" or
 than 1 million faces".
 
 If you have any questions about the privacy policy, what data we
-collect, or how we use it, please [get in touch with
-us](mailto:compreface.support@exadel.com)
+collect, or how we use it, please [get in touch with us](mailto:compreface.support@exadel.com).

docs/How-to-Use-CompreFace.md

@@ -45,8 +45,7 @@ Each object has the following fields:
 4.  `x_min`, `x_max`, `y_min`, `y_max` are coordinates of the face in
     the image
 
-```
-
+```json
     {
       "result": [
         {
@@ -78,14 +77,14 @@ Each object has the following fields:
 This demo shows the most simple example of Face recognition service
 usage. To run a demo, open an HTML file in a browser. API key for this
 demo was created on **step 5** of [How to Use
-CompreFace](#how-to-use-compreface)
+CompreFace](#how-to-use-compreface).
 
 2.  [webcam_demo.html](./demos/webcam_demo.html)
 
 This demo shows the most simple webcam demo for Face recognition
 service. To run a demo, open an HTML file in a browser. API key for this
 demo was created on **step 5** of [How to Use
-CompreFace](#how-to-use-compreface)
+CompreFace](#how-to-use-compreface).
 
 ## Code Snippets
 

docs/Installation-options.md

@@ -1,7 +1,7 @@
 # Installation (Deployment) options
 
-Exadel CompreFace consists of several services and a database. 
-Full architecture description and scaling tips you can find [here](Architecture-and-scalability.md). 
+Exadel CompreFace consists of several services and a database.
+You can find the full architecture description and scaling tips [here](Architecture-and-scalability.md). 
 Each service is put to docker image for simpler usage, and they can be run separately. 
 However, for a better user experience, CompreFace provides three distribution options that help install CompreFace easier. 
 By default, CompreFace is delivered as a docker-compose configuration. But there are more options to install and run CompreFace. 
@@ -16,11 +16,11 @@ Each of them has its benefits and disadvantages.
 ## Docker Compose
 
 Docker-compose configuration allows simply run, configure, stop and restart CompreFace.
-To install CompreFace using docker-compose just follow instructions in [getting started](../README.md#getting-started-with-compreface)
+To install CompreFace using docker-compose just follow instructions in [getting started](../README.md#getting-started-with-compreface).
 
 ### Maintaining tips
 
-1. After you run CompreFace, wait at least 30 seconds until it starts. 
+1. After you run CompreFace, allow at least 30 seconds for it to start. 
    Do not stop it during this time, as it may corrupt database data during data migration.
 2. You can run `docker-compose ps` to see all CompreFace services. 
    There should be 5 CompreFace services: compreface-core, compreface-api, compreface-admin, compreface-ui, compreface-postgres-db. 
@@ -29,16 +29,16 @@ To install CompreFace using docker-compose just follow instructions in [getting
    You also can run `docker-compose logs -f` to see the logs of all CompreFace services.
 4. Docker-compose automatically restarts all services if they fail. It also automatically starts them after you restart your machine.
 5. If you want to stop CompreFace, run `docker-compose stop`. 
-   You can also stop each container one by one, e.g. `docker-compose stop compreface-core`.
+   You can also stop each container one by one, by running `docker-compose stop <service>`, e.g. `docker-compose stop compreface-core`.
 6. To start stopped Compreface, run `docker-compose start`. 
-   You can also start each container one by one, e.g. `docker-compose start compreface-core`.
+   You can also start each container one by one, by running `docker-compose start <service>`, e.g. `docker-compose start compreface-core`.
 7. If you want to restart CompreFace, run `docker-compose restart`. 
-   You can also restart each container one by one, e.g. `docker-compose restart compreface-core`.
+   You can also restart each container one by one, by running `docker-compose restart <service>`, e.g. `docker-compose restart compreface-core`.
 8. All the data is stored locally on your machine. It is stored in a named docker volume. 
    This guarantees that if you stop or delete CompreFace docker containers, you won’t lose the data. 
    To find the volume name, run `docker volume ls`, the name should be `<CompreFace folder>_postgres-data`, e.g. `compreface_061_postgres-data`.
 9. If you want to clear CompreFace installation, first stop it with `docker-compose stop`. 
-   Then delete the volume, e.g. `docker volume rm compreface_061_postgres-data`. Then run CompreFace again `docker-compose up -d`.
+   Then delete the volume (see tip 8 for getting volume name), e.g. `docker volume rm compreface_061_postgres-data`. Then run CompreFace again `docker-compose up -d`.
 10. To update the CompreFace version or change custom build, download new `docker-compose.yml` and `.env` files.
    Stop CompreFace with `docker-compose down`. Copy new files into the old CompreFace folder. Then run CompreFace with `docker-compose up -d`.
 
@@ -50,15 +50,15 @@ To install CompreFace using docker-compose just follow instructions in [getting
 
 2. Problem: `compreface-admin` doesn’t start and there are logs like `Waiting for changelog lock....`
 
-   Solution: clear CompreFace installation (see #Maintaining-tips)
+   Solution: clear CompreFace installation (see [Maintaining-tips](#maintaining-tips))
 
 ## Kubernetes
 
 You can find all Kubernetes scripts in CompreFace [Kubernetes repository](https://github.com/exadel-inc/compreface-kubernetes).
 
 ## Single docker container
 
-Except for other distribution options, here all services and the database are placed in one docker image. 
+Unlike other distribution options, all services and the database here are placed in one docker image. 
 The obvious advantage of this approach is that it is the simplest way to start CompreFace. 
 However, it has some limitations in maintaining and troubleshooting. 
 E.g. it’s very difficult to stop or restart services one by one. 
@@ -100,7 +100,7 @@ docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data --runt
 ### Maintaining tips
 
 1. Start CompreFace in a single docker container takes at least 45 seconds. 
-   So long start is because of manual timings that help to start services in the right order.
+   The long start is because of manual timings that help to start services in the right order.
 2. There is a possibility that the database starts too slow, then service `compreface-admin` will fail. 
    Supervisord will restart it automatically and CompreFace should start properly.
 3. To check if the run is finished, you can check the logs `docker logs CompreFace -f`. 
@@ -110,14 +110,14 @@ docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data --runt
 5. `compreface-db` in the run command is the name of the volume, all your data is stored locally in this volume. 
    This guarantees that if you stop or delete CompreFace docker containers, you won’t lose the data.  
 6. You can use environment variables from `docker-compose` version, e.g.  to set API server limit you can run:
-```commandline
-docker run -d -e "API_JAVA_OPTS=-Xmx8g" --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface`
-```
+   ```shell
+   docker run -d -e "API_JAVA_OPTS=-Xmx8g" --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 exadel/compreface`
+   ```
 7. By default, docker won’t restart CompreFace if it fails or after your restart your machine. 
    You can add this by adding `--restart=always` in run command:
-```commandline
-docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 --restart=always exadel/compreface
-```
+   ```shell
+   docker run -d --name=CompreFace -v compreface-db:/var/lib/postgresql/data -p 8000:80 --restart=always exadel/compreface
+   ```
 8. If you want to stop CompreFace, run `docker stop CompreFace`.
 9. To start stopped Compreface, run `docker start CompreFace`.
 10. If you want to restart CompreFace, run `docker restart CompreFace`.

docs/Mask-detection-plugin.md

@@ -7,11 +7,12 @@ correctly automatically. There are three possible results:
 There was no suitable free and ready-to-use model for face mask
 detection at the moment of adding this plugin, so we created our model.
 
-    Disclaimer:
-    Software developers, not medical experts, created the plugin. 
-    The plugin doesn't contain the recommendations of how to use and wear face mask correctly.
-    The accuracy of the model is not 100%.
-    Please use the plugin at your own risk.
+> [!NOTE]
+> Disclaimer:
+> Software developers, not medical experts, created the plugin. 
+> The plugin doesn't contain the recommendations of how to use and wear face mask correctly.
+> The accuracy of the model is not 100%.
+> Please use the plugin at your own risk.
 
 # Face mask detection example
 
@@ -42,5 +43,4 @@ augmentation (see augmentation.py) to achieve class balance.
 
 InceptionV3 was cut off on a mixed 7 layer to improve speed and was used
 as a backbone. The final model with 97.2 % accuracy is used by default
-and can be found
-[here](https://drive.google.com/file/d/1jm2Wd2JEZxhS8O1JjV-kfBOyOYUMxKHq/view?usp=sharing)
+and can be found [here](https://drive.google.com/file/d/1jm2Wd2JEZxhS8O1JjV-kfBOyOYUMxKHq/view?usp=sharing).

docs/User-Roles-System.md

@@ -16,19 +16,25 @@ administrator) roles to technical support employees. Then there is no
 reason to add such users to applications as they still have all
 permissions within the application.
 
+### Global owner role
+
 In CompreFace, the first user automatically receives the global owner
 role and has rights for any operation within CompreFace - managing users
 and creating and managing applications. The only restriction for the
 global owner is that such a user can't delete themselves from the
 system, so the user has to assign the global owner role to somebody else
 and then remove themselves from the system.
 
+### Global administrator role
+
 Users with the global administrator role have the same permissions as
 users with the global owner role. The only difference is that such users
 can\'t manage the user with the global owner role. We recommend reducing
 users with such a role to the minimum number required to maintain the
 system.
 
+### Global user role
+
 All new users are automatically assigned the global user role. These
 users can't create applications, can access only the applications they
 were added to, and can't manage other users. These users use CompreFace
@@ -47,6 +53,8 @@ become a member of an application team, users with a global user role
 need to be added to the application directly by the global owner, global
 administrator, or application owner.
 
+### Application owner role
+
 The user that creates an application automatically receives the
 application owner role and has rights for any operation within the
 application - managing the application and its users and creating and
@@ -55,11 +63,15 @@ restriction for the application owner is that they can't delete
 themselves from the application, so they have to assign the application
 owner role to somebody else before deleting themselves.
 
+### Application administrator role
+
 Users with the application administrator role (global user role +
 application administrator role) can create and manage [Face
 Services](Face-services-and-plugins.md) but can't manage an application
 and its users.
 
+### Application user role
+
 Users with the application user role can't manage anything in the
 application. This is the least permissive role (global user role +
 application user role), but this provides enough information to

load-tests/README.md

@@ -26,9 +26,9 @@ docker run \
 ```
 
 Any test from `tests` folder follows those steps:
-1. Apply db_init.sql to database
+1. Apply *db_init.sql* to database
 2. Run recognition test according to `scenarios` defined in the script
-3. Apply db_truncate.sql to database
+3. Apply *db_truncate.sql* to database
 
 
 ### Run command details