Merge pull request #275 from webtech-network/getting-started-workflow-docs

docs: make getting started a real grading workflow

Author: ArthurCRodrigues

README.md

@@ -154,7 +154,7 @@ The **SandboxManager** provides secure, isolated execution environments:
 - **Automatic Lifecycle**: TTL management, health checks, and cleanup
 - **Resource Control**: Memory limits, timeouts, and isolation
 
-#### Template System
+#### Template Library
 
 Templates provide test functions for different assignment contexts:
 

docs/core/template-system.md docs/core/template-library.mddocs/core/template-system.md renamed to docs/core/template-library.md

@@ -1,4 +1,4 @@
-# Template System
+# Template Library
 
 ## What it is
 

docs/getting-started/mkdocs-local-development.md

@@ -1,40 +1,117 @@
-# Local Docs Development (MkDocs)
+# Run Your First Grading Workflow
 
-This project uses **MkDocs Material** to publish the documentation website.
+This quickstart walks you through one complete grading cycle:
 
-## Run locally
+1. start the API
+2. create a grading configuration
+3. submit student code
+4. fetch the graded result
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- Python available on your machine
+- Project dependencies installed (`pip install -r requirements.txt`)
+
+## 1) Start Autograder
 
 ```bash
-pip install -r requirements-docs.txt
-mkdocs serve
+make start-autograder
 ```
 
-Open `http://127.0.0.1:8000` to preview changes with live reload.
+When ready, the API is available at `http://localhost:8080`.
+
+You can check health:
 
-## Build locally
+```bash
+curl http://localhost:8080/api/v1/health
+```
+
+## 2) Create a grading configuration
 
 ```bash
-mkdocs build --strict
+curl -X POST http://localhost:8080/api/v1/configs \
+  -H "Content-Type: application/json" \
+  -d '{
+    "external_assignment_id": "demo-assignment-1",
+    "template_name": "input_output",
+    "criteria_config": {
+      "base": {
+        "weight": 100,
+        "subjects": [
+          {
+            "subject_name": "Functionality",
+            "weight": 100,
+            "tests": [
+              {
+                "name": "expect_output",
+                "weight": 100,
+                "parameters": {
+                  "inputs": ["Alice"],
+                  "expected_output": "Hello, Alice!",
+                  "program_command": "python3 main.py"
+                }
+              }
+            ]
+          }
+        ]
+      }
+    },
+    "languages": ["python"],
+    "setup_config": {
+      "required_files": ["main.py"],
+      "setup_commands": []
+    },
+    "include_feedback": true,
+    "feedback_config": {
+      "general": {
+        "report_title": "Evaluation Report",
+        "show_score": true,
+        "show_passed_tests": false,
+        "add_report_summary": true
+      }
+    }
+  }'
 ```
 
-`--strict` turns warnings into errors, which helps catch broken navigation or links before opening a PR.
+## 3) Submit a student solution
+
+```bash
+curl -X POST http://localhost:8080/api/v1/submissions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "external_assignment_id": "demo-assignment-1",
+    "external_user_id": "student-1",
+    "username": "student_1",
+    "language": "python",
+    "files": [
+      {
+        "filename": "main.py",
+        "content": "name = input().strip()\nprint(f\"Hello, {name}!\")"
+      }
+    ]
+  }'
+```
+
+Copy the returned `id` from the response. That is your `submission_id`.
+
+## 4) Poll for the result
+
+```bash
+curl http://localhost:8080/api/v1/submissions/<submission_id>
+```
 
-## Where to edit
+When grading finishes, response status becomes `completed`, and you will get:
 
-- Main landing page: `docs/index.md`
-- Core concept pages: `docs/core/`
-- Pipeline deep dives: `docs/pipeline/`
-- Architecture references: `docs/architecture/`
-- Roadmaps: `docs/roadmaps/`
+- `final_score`
+- `feedback`
+- `result_tree`
+- `focus`
 
-## Documentation standards
+## What you just exercised
 
-Every new technical page should follow this teaching pattern:
+You ran the full core flow:
 
-1. **What it is**
-2. **Why it matters**
-3. **How it works**
-4. **Concrete example**
-5. **Common mistakes**
+`LOAD_TEMPLATE -> BUILD_TREE -> SANDBOX -> PRE_FLIGHT -> GRADE -> FOCUS -> FEEDBACK`
 
-For rubric quality guidance, use [Educational Criteria Design](../guides/criteria-tree-educational-standards.md).
+To understand each stage in depth, continue with [Pipeline Architecture](../core/pipeline-architecture.md).

docs/guides/docs-site-development.md

@@ -0,0 +1,32 @@
+# Docs Site Development (MkDocs)
+
+This project uses **MkDocs Material** to publish the documentation website.
+
+## Run locally
+
+```bash
+pip install -r requirements-docs.txt
+mkdocs serve
+```
+
+Open `http://127.0.0.1:8000` to preview changes with live reload.
+
+## Build locally
+
+```bash
+mkdocs build --strict
+```
+
+`--strict` turns warnings into errors, which helps catch broken navigation or links before opening a PR.
+
+## Documentation standards
+
+Every new technical page should follow this teaching pattern:
+
+1. **What it is**
+2. **Why it matters**
+3. **How it works**
+4. **Concrete example**
+5. **Common mistakes**
+
+For rubric quality guidance, use [Educational Criteria Design](criteria-tree-educational-standards.md).

docs/index.md

@@ -7,7 +7,7 @@ This documentation is organized to be both practical for first-time users and de
 1. [Pipeline Architecture](core/pipeline-architecture.md)
 2. [Criteria Tree](core/criteria-tree.md)
 3. [Sandbox Management](core/sandbox-management.md)
-4. [Template System](core/template-system.md)
+4. [Template Library](core/template-library.md)
 5. [Feedback Generation](core/feedback-generation.md)
 
 ## Learning Paths
@@ -27,7 +27,7 @@ This documentation is organized to be both practical for first-time users and de
 
 ### Template author
 
-- [Template System](core/template-system.md)
+- [Template Library](core/template-library.md)
 - [Input/Output Template](template-library/input_output.md)
 - [API Testing Template](template-library/api_testing.md)
 - [Web Development Template](template-library/web_dev.md)

docs/roadmaps/FEATURE_ROADMAP.md

@@ -93,7 +93,7 @@ How this integrates with the existing grading template strategy (whether it beco
 
 #### Open Challenges
 
-- **Integration with the template system.** How static analysis tests fit into the existing grading template strategy needs further discussion — whether as a new template type, an extension to existing templates, or a separate layer that can be composed with any template.
+- **Integration with the Template Library.** How static analysis tests fit into the existing grading template strategy needs further discussion — whether as a new template type, an extension to existing templates, or a separate layer that can be composed with any template.
 - **Balancing language-agnostic and language-specific checks.** The hybrid approach needs a clear structure so that educators can configure both general and language-specific checks without the system becoming overly complex.
 
 ---

mkdocs.yml

@@ -38,12 +38,13 @@ markdown_extensions:
 nav:
   - Home: index.md
   - Getting Started:
-      - Local Docs Development: getting-started/mkdocs-local-development.md
+      - Run Your First Grading Workflow: getting-started/mkdocs-local-development.md
+      - Development Guide: guides/development.md
   - Core Concepts:
       - Pipeline Architecture: core/pipeline-architecture.md
       - Criteria Tree: core/criteria-tree.md
       - Sandbox Management: core/sandbox-management.md
-      - Template System: core/template-system.md
+      - Template Library: core/template-library.md
       - Feedback Generation: core/feedback-generation.md
       - Educational Criteria Design: guides/criteria-tree-educational-standards.md
   - API:
@@ -77,6 +78,7 @@ nav:
       - Localization: features/localization.md
   - Guides:
       - Development Guide: guides/development.md
+      - Docs Site Development: guides/docs-site-development.md
       - Criteria Configuration Examples: guides/criteria_configuration_examples.md
       - GitHub Module: guides/github_module.md
   - Roadmaps: