Adding the updated readme and docomentation

DOCUMENTATION.md

@@ -0,0 +1,184 @@
+# Comprehensive Documentation
+
+
+## Index
+
+- [Comprehensive Documentation](#comprehensive-documentation)
+  - [Index](#index)
+  - [Introduction](#introduction)
+  - [Project Structure](#project-structure)
+    - [`.github`](#github)
+    - [`Courses Folder`](#courses-folder)
+    - [`Utils Folder`](#utils-folder)
+    - [`problems.json`](#problemsjson)
+    - [`sync-course.json`](#sync-coursejson)
+  - [Getting Started](#getting-started)
+  - [Syncing Content from omegaup.com to this repository](#syncing-content-from-omegaupcom-to-this-repository)
+  - [Modifying existing Problems Content](#modifying-existing-problems-content)
+  - [Adding or removing problems to the Couse:](#adding-or-removing-problems-to-the-couse)
+
+## Introduction
+
+Welcome to the comprehensive documentation for this project. This document provides a detailed overview of the project, its structure, and how to contribute.
+
+## Project Structure
+
+The project is organized into the following main directories:
+
+### `.github`
+This directory contains GitHub-specific files, such as issue and pull request templates, as well as workflow definitions. The workflows are:
+  - **continuous-integration.yaml**: Runs continuous integration checks on pull requests.
+  - **modify-assignments.yaml**: Modifies assignments based on issue comments.
+  - **sync_content.yml**: Syncs content from a remote source.
+
+### `Courses Folder`
+
+This folder contains the omegaUp's Public Courses. The folers inside the  `Courses` folder are named by their aliases.
+Each `course-alias` folder contains a `course_settings.json` file and a list of `assignment-alias` folders them each assignment contains a list of `problem-alias` folder in them,
+now each of the `problem-alias` is the extracted zip of the actual problem which we download from omegaup.com.
+
+```
+📁 Courses/
+├── 📁 course-1-alias/
+│   ├── 📄 course_settings.json
+│   └── 📁 assignment-1-alias/
+│       └── 📁 problem-1-alias/
+│           ├── 📄 settings.json
+│           ├── 📄 settings.distrib.json
+│           └── 📁 statements/
+│               └── 📄 es.markdown
+```
+
+### `Utils Folder`
+
+This directory contains utility scripts for managing the courses. The most important scripts are:
+  - **container.py**: Manages containerized environments for running and testing code.
+  - **download_and_sync_courses.py**: Downloads and syncs course materials from a remote source.
+  - **generateresources.py**: Generates static resources for the courses.
+  - **lint**: A script for linting the course materials.
+  - **problems.py**: A script for managing problems within the courses.
+  - **runtests.py**: Runs tests for the course materials.
+  - **update_assignment_problems.py**: Updates the problems in a specific assignment.
+  - **upload.py**: Uploads course materials to a remote server.
+  - **validate_content.py**: Validates the content of the course materials.
+
+### `problems.json`
+
+This is a **autogenerated** file contains a list of all the problems in the courses. Each problem is represented by an object with a `path` key, which specifies the path to the problem's directory. This file is used by the utility scripts to manage the problems in the courses.
+
+### `sync-course.json`
+
+This file is used to request a synchronization of a course with the omegaup.com platform. To request a sync, you need to add an object to the `requests` array with your OmegaUp username, your GitHub username, and the pull request number of your sync request.
+
+
+## Getting Started
+
+To get started with this project, you will need to have the following prerequisites installed:
+
+- Python 3
+- Pip
+- Git
+
+Once you have the prerequisites installed, you can clone the repository and install the dependencies:
+
+```bash
+git clone https://github.com/omegaup/public-courses.git
+cd public-courses
+pip install -r utils/requirements.txt
+```
+
+## Syncing Content from omegaup.com to this repository
+The github actions are configured to push the latest content whenever some changes are pushed in the `sync-course` branch only
+
+**For Admin:**
+If a admin want to sync the content from omegaup.com to course github repo, they can run the following commands:
+1. Checkout to the branch `sync-course`:
+```
+git checkout sync-course
+```
+2. Reset the branch with the main branch:
+```
+git reset --hard origin/main
+```
+3. Push the changes
+```
+git push --force
+```
+This will push the changes to sync-course branch, now the github action `Sync Course Content` will run which will add a commit made by the Github Actions bot with the latest content from omegaup.com.
+
+**For Contributors:**
+If a contributor want to request syncing of content from the omegaup.com to the course repo in the github, they can raise a pr to targetting the `sync-course` branch with the changes in the `sync-course.json` file to keep a log of the sync request. Once the pr gets merged the `sync-courses` branch will have the a commit made by Github Actions bot containg the latest content from omegaup.com.
+
+## Modifying existing Problems Content
+
+**For Admin:**
+If you want to modify the content of an existing problem in the course (eg: typo fixes, test case addition etc), you can change do the respected changes in the problem folder in the course's assignment folder and push the changes to the `main` branch.
+
+**For Contributors:**
+If you want to request a change in the content of an existing problem in the course (eg: typo fixes, test case addition etc), you can raise a pull request with the changes to the `main` branch.
+
+## Adding or removing problems to the Couse:
+The github actions are configured to add/remove the problems from the course on omegaup.com only when changes are pushed to the `modify-assignments` branch.
+
+**IMPORTANT** - If you want to add a problem to the course and you want to have the problem contents to be in the repective course's assignment folder in the github repo as well then  admin permissions need to be provided for that problem for the user - `CourseBot`
+
+**For Admin:**
+If a admin wants to add/remove problem from the course they should do the following step:
+1. Checkout to the branch `modify-assignments`:
+```
+git checkout modify-assignments
+```
+1. Reset the branch with the main branch:
+```
+git reset --hard origin/main
+```
+1. Update the `adding_removing_problems.json` by adding the details of the problems, eg:
+```
+{
+    "add_problem":[
+        {
+            "course_alias": "omi-public-course",
+            "assignment_alias": "intro",
+            "problem_alias": "demo-de-objetivo",
+            "points": 100
+        }
+    ],
+    "remove_problem":[
+            "course_alias": "omi-public-course",
+            "assignment_alias": "practice",
+            "problem_alias": "Contest-Start",
+        }
+    ]
+}
+```
+4. Commit and push the changes:
+```
+git push --force
+```
+This will push the changes to `modify-assignments` branch, now the github action `Modify Course Assignments` will go through the `adding_removing_problems.json` in order to know what problems to add/remove:
+ - If a problem is added and the admin permissions are provided for the problem to the `CourseBot` user then the problem zip file will be downloaded for the problem and will be extracted and added the respective course's assignment folder.
+ - If a problem is removed then if the problem folder is present in the course's assignment folder in the github repo then it will be removed as well.
+ - In both cases a commit will be added by the Github Bot, which would do the aforesaid changes.
+
+**For Contributors:**
+If a contributor wants to request a problem to be added or removed then they can populate the `modify-assignments` accordingly, eg:
+```
+{
+    "add_problem":[
+        {
+            "course_alias": "omi-public-course",
+            "assignment_alias": "intro",
+            "problem_alias": "demo-de-objetivo",
+            "points": 100
+        }
+    ],
+    "remove_problem":[
+            "course_alias": "omi-public-course",
+            "assignment_alias": "practice",
+            "problem_alias": "Contest-Start",
+        }
+    ]
+}
+```
+and raise a pull request targeting `modify-assignments` branch. When this pull request gets merged then the Github Actions Bot will add a commit to the branch for the desired changes.
+

README.md

@@ -1,22 +1,38 @@
-# Public Courses on Omegaup
-This repository contains the course content for the public courses on Omegaup.
-
-## How to Contribute
-You can contribute to the courses by adding new content, fixing typos, or improving existing materials. To do so, please follow these steps:
-1. Fork the repository.
-2. Create a new branch for your changes.
-3. Make your changes and commit them with a clear message.
-4. Push your changes to your forked repository.
-5. Create a pull request to the main repository.
-
-## How to Sync Courses:
-If you think that a course content in this repository has ran out of sync with the omegaup.com you can raise a pull request to sync the content.
-To do this, follow these steps:
-1. Fork the repository.
-2. Create a new branch for your changes.
-3. Edit the `sync-course.json` file to include the course name and the specific content that is out of sync.
-4. Commit your changes with a clear message.
-5. Push your changes to your forked repository.
-6. Create a pull request to the main repository with target branch sync-course.
-7. When your pull request is merged a github action will run to sync the course content with omegaup.com and add commit to your pull request.
-8. Now the admins will merge this pull request to the main branch.
+# omegaUp Public Courses on GitHub
+
+This repository hosts **omegaUp’s Public Courses**, managed through GitHub to enable open collaboration.  
+Contributors can suggest improvements via **pull requests**, and GitHub Actions will validate and deploy changes to [omegaUp.com](https://omegaup.com).
+
+---
+
+## 📖 Documentation
+
+A complete guide is available in [Comprehensive Documentation](./DOCUMENTATION.md).  
+It covers setup, workflows, contribution guidelines, and detailed instructions.
+
+---
+
+## 📂 Repository Overview
+
+- `.github/` → Workflows for CI, syncing, and modifying assignments  
+- `Courses/` → Public course content (courses, assignments, problems)  
+- `utils/` → Helper scripts for syncing, validation, and uploads  
+- `problems.json` → Auto-generated list of all problems  
+- `sync-course.json` → Log of course sync requests  
+
+---
+
+## 🔑 Key Sections
+
+1. [Getting Started](./DOCUMENTATION.md#getting-started)  
+2. [Syncing Content](./DOCUMENTATION.md#syncing-content-from-omegaupcom-to-this-repository)  
+3. [Modifying Problems](./DOCUMENTATION.md#modifying-existing-problems-content)  
+4. [Adding/Removing Problems](./DOCUMENTATION.md#adding-or-removing-problems-to-the-couse)  
+5. [Contributing](./DOCUMENTATION.md#contributing)  
+
+
+---
+
+## 📜 License
+
+This project is licensed under the [License](LICENSE).