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
## Dependencies
-[python](https://www.python.org/downloads/) version 3.10
-[Python](https://www.python.org/downloads/) version 3.10
-[poetry](https://python-poetry.org/docs/) version 1.8.0 and higher
-[Poetry](https://python-poetry.org/docs/) version 1.8.0 and higher
## Usage (local server)
## Usage (local server)
```
To set up and run a local server for the documentation:
poetry install
poetry run ./utilities.sh
1. Install dependencies:
poetry run mkdocs serve
```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
## Build GitLab Pages
https://inject.pages.fi.muni.cz/inject-docs
The documentation is built and deployed to GitLab Pages. The hosted documentation is available at:
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.
