From b6c381bbcd25d7ec2c522d0d309a1a72308290b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Roman=20Dvo=C5=99=C3=A1k?= <xdvora19@fi.muni.cz>
Date: Thu, 27 Jun 2024 11:54:43 +0200
Subject: [PATCH] * fix nitpicks

* minor changes to readme.md

* update README.md
---
 README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 61 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index f90abec..3ff6c5d 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,72 @@
 # inject-docs
 
+This repository contains the documentation for the inject exercise platform.
+
+## Table of Contents
+
+- [Dependencies](#dependencies)
+- [Usage (Local Server)](#usage-local-server)
+- [Build GitLab Pages](#build-gitlab-pages)
+- [Files Pulled from Other Repositories](#files-pulled-from-other-repositories)
+- [Pipeline and Deployment](#pipeline-and-deployment)
+
 ## Dependencies
 
-- [python](https://www.python.org/downloads/) version 3.10
-- [poetry](https://python-poetry.org/docs/) version 1.8.0 and higher
+- [Python](https://www.python.org/downloads/) version 3.10
+- [Poetry](https://python-poetry.org/docs/) version 1.8.0 and higher
 
 ## Usage (local server)
 
-```
-poetry install
-poetry run ./utilities.sh
-poetry run mkdocs serve
-```
+To set up and run a local server for the documentation:
+
+1. Install dependencies:
+   ```bash
+   poetry install
+   ```
+
+2. Run the utilities script to set up the necessary environment:
+   ```bash
+   poetry run ./utilities.sh
+   ```
 
-Access http://localhost:8000
+3. Start the local MkDocs server:
+   ```bash
+   poetry run mkdocs serve
+   ```
+
+4. Access the documentation at [http://localhost:8000](http://localhost:8000). If port 8000 is taken by another service, you can change the default port using the `-a` or `--dev-addr` option:
+   ```bash
+   poetry run mkdocs serve -a <IP:PORT>
+   ```
 
 ## Build GitLab Pages
 
-https://inject.pages.fi.muni.cz/inject-docs
\ No newline at end of file
+The documentation is built and deployed to GitLab Pages. The hosted documentation is available at:
+
+[https://inject.pages.fi.muni.cz/inject-docs](https://inject.pages.fi.muni.cz/inject-docs)
+
+## Files Pulled from Other Repositories
+
+The `utilities.sh` script pulls several essential files from other repositories to ensure centralized updates. These files include:
+
+- `backend/definitions/README.md`: Documentation on the definition files structure.
+- `backend/openapi.yml`: OpenAPI documentation for the API.
+- `frontend/docker/nginx-deployment/README.md`: Documentation on the Nginx deployment setup.
+- `showcase-definition/assets/definition.zip`: A showcase definition file.
+
+Additionally, the GitLab pipeline pulls and zips the following files:
+
+- `frontend/docker/nginx-deployment`: This directory is zipped (excluding `compose-from-monorepo.yml`) and saved as `deployment-files.zip` in the `files-from-repos` directory.
+
+## Pipeline and Deployment
+
+Deployment of the documentation to GitLab Pages is managed through a CI/CD pipeline defined in the .gitlab-ci.yml file. GitLab CI/CD will automatically run the pipeline, which includes the following stages. You can also manually trigger the pipeline if needed:
+
+* Setup: Install necessary dependencies and run the utilities.sh script to set up directories and copy files.
+* Commit Zip: Optionally commit the zipped deployment files and showcase definition to the repository.
+* Build Documentation: Use MkDocs to build the site.
+* Deploy Pages: Deploy the built documentation to GitLab Pages.
+
+**Important**: Certain parts of the pipeline, including the commit and deploy stages, are only run on the `main` branch. This ensures that only finalized and approved changes are deployed to the live documentation site.
+
+The pipeline will automatically build and deploy the documentation to GitLab Pages upon successful completion of all stages.
-- 
GitLab