Next generation INGInious documentation

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master", "docv2"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install requirements
+        run: |
+          pip3 install -r docs/requirements.txt
+          sudo apt install -y doxygen
+      - name: Build site
+        run: mkdocs build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: 'site/'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3

docs/admin.md

@@ -0,0 +1 @@
+# Administration

docs/api/index.md

@@ -0,0 +1,3 @@
+# API Documentation
+
+Documentation of the INGInious source code generated with [MkDoxy](https://github.com/JakubAndrysek/MkDoxy).

docs/change.md

@@ -0,0 +1 @@
+# Changelog

docs/index.md

@@ -0,0 +1,27 @@
+# Home
+
+<div class="grid-left" markdown>
+![image](assets/logo_full.png){.index-logo width=250px}
+
+**INGInious** is an open-source intelligent grader that allows secured and automated testing of code made by students
+
+[Get started](setup.md){ .md-button .md-button--primary .index-callout }
+[Public Instance](https://inginious.org/?lang=en){ .md-button .md-button--secondary target=\_blank }
+
+</div>
+<div class="grid-right" markdown>
+![image](assets/screenshots/inginious_home.png){.index-screenshot width=500px}
+</div>
+<div class="clear"></div>
+
+## Features
+
+## Screenshots
+
+## Contributing
+
+### Features Requests
+
+### Bugs
+
+### Translation

docs/requirements.txt

@@ -0,0 +1,35 @@
+Babel==2.13.1
+certifi==2023.11.17
+charset-normalizer==3.3.2
+click==8.1.7
+colorama==0.4.6
+ghp-import==2.1.0
+idna==3.6
+importlib-metadata==7.0.0
+importlib-resources==6.1.1
+Jinja2==3.1.2
+Markdown==3.5.1
+MarkupSafe==2.1.3
+mergedeep==1.3.4
+mike==2.0.0
+mkdocs==1.5.3
+mkdocs-material==9.4.14
+mkdocs-material-extensions==1.3.1
+mkdoxy==1.1.7
+packaging==23.2
+paginate==0.5.6
+pathspec==0.11.2
+platformdirs==4.1.0
+Pygments==2.17.2
+pymdown-extensions==10.5
+pyparsing==3.1.1
+python-dateutil==2.8.2
+PyYAML==6.0.1
+pyyaml_env_tag==0.1
+regex==2023.10.3
+requests==2.31.0
+six==1.16.0
+urllib3==2.1.0
+verspec==0.1.0
+watchdog==3.0.0
+zipp==3.17.0

docs/setup.md

@@ -0,0 +1,149 @@
+# Setup
+
+## Installation
+
+There are three main ways to install INGInious:
+
+- [Using pre-build containers and a Compose file](#containerized-deployement-with-pre-build-images)
+- [Locally build containers and a Compose file](#containerized-deployment-with-locally-build-images)
+- [Bare metal, manual installation](#manual-installation)
+
+### Containerized deployement with pre-build images
+
+!!! tip
+
+    [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) are pre-requisite for this type of installation.
+
+!!! info
+
+    While [Docker](https://www.docker.com/) is mainly used in INGInious deployements, other containers engines such as [Podman](https://podman.io/) should also work.
+    If you are experimenting with another container engine, [your feedback is welcome](https://github.com/UCL-INGI/INGInious/discussions).
+
+1. Create a folder in your home directory to place your courses and exercices.
+  ```console
+  mkdir -p inginious/{tasks,backups}
+  ```
+2. Get the [Compose file](https://github.com/UCL-INGI/INGInious/blob/docker-compose.yml) from the project page.
+  ```console
+  wget https://github.com/UCL-INGI/INGInious/blob/docker-compose.yml
+  ```
+
+  OR
+
+  Copy and paste the following snippet in a file called `docker-compose.yml`.
+
+  ```yaml
+  services:
+
+    base:
+      image: ${REGISTRY}/inginious/core-base:${VERSION} # (1)
+      build:
+        dockerfile: deploy/inginious-base.containerfile
+        args:
+          - VERSION=${VERSION}
+          - REGISTRY=${REGISTRY}
+      command: /bin/true # (2)
+
+    db:
+      image: mongo:6.0.2
+      networks:
+        - inginious
+
+    backend:
+      image: ${REGISTRY}/inginious/core-backend:${VERSION}
+      depends_on:
+        - base
+      build:
+        dockerfile: deploy/backend.containerfile
+        args:
+          - VERSION=${VERSION}
+          - REGISTRY=${REGISTRY}
+      environment:
+        AGENT: "tcp://0.0.0.0:2001" # (3)
+        CLIENT: "tcp://0.0.0.0:2000" # (4)
+      networks:
+        - inginious
+
+    agent-docker:
+      image: ${REGISTRY}/inginious/core-agent_docker:${VERSION}
+      depends_on:
+        - backend
+      deploy:
+        replicas: 1 # (5)
+      build:
+        dockerfile: deploy/agent-docker.containerfile
+        args:
+          - VERSION=${VERSION}
+          - REGISTRY=${REGISTRY}
+      environment:
+        BACKEND: "tcp://backend:2001" # (6)
+      volumes: # (7)
+       - /var/run/docker.sock:/var/run/docker.sock
+       # See https://github.com/UCL-INGI/INGInious/issues/352
+       - ./tasks/:/inginious/tasks
+       - ./backups/:/inginious/backups
+       # See https://github.com/UCL-INGI/INGInious/issues/799
+       - /tmp/agent_data/:/tmp/agent_data/
+      networks:
+        - inginious
+
+    agent-mcq:
+      image: ${REGISTRY}/inginious/core-agent_mcq:${VERSION}
+      depends_on:
+        - backend
+      deploy:
+        replicas: 1 # (5)
+      build:
+        dockerfile: deploy/agent-mcq.containerfile
+        args:
+          - VERSION=${VERSION}
+          - REGISTRY=${REGISTRY}
+      environment:
+        BACKEND: "tcp://backend:2001" # (6)
+      volumes: # (7)
+       # See https://github.com/UCL-INGI/INGInious/issues/352
+       - ./tasks/:/inginious/tasks
+       - ./backups/:/inginious/backups
+       # See https://github.com/UCL-INGI/INGInious/issues/799
+       - /tmp/agent_data/:/tmp/agent_data/
+      networks:
+        - inginious
+
+    frontend:
+      image: ${REGISTRY}/inginious/core-frontend:${VERSION}
+      build:
+        dockerfile: deploy/frontend.containerfile
+        args:
+          - VERSION=${VERSION}
+          - REGISTRY=${REGISTRY}
+      depends_on:
+        - backend
+        - agent-docker
+        - agent-mcq
+      environment:
+        - INGINIOUS_WEBAPP_HOST=0.0.0.0
+      volumes: # (7)
+        - ./configuration.deploy.yaml:/inginious/configuration.yaml
+        - ./tasks/:/inginious/tasks
+        - ./backups/:/inginious/backups
+      ports:
+        - 9000:8080
+      networks:
+        - inginious
+
+  networks:
+    inginious:
+  ```
+
+  1. `REGISTRY` and `VERSION` variables control the source and the version of the core services
+      of INGInious. They must be specified when the stack is built or deployed.
+  2. Quick hack to force the build of the base core container before building the service containers.
+  3. Address and port on which the backend will listen for [`Agents`]().
+  4. Address and port on which the backend will listen for [`Clients`]().
+  5. By tuning this parameter, one can deploy multiples [`Agents`]() in the same stack.
+  6. Specify in the `BACKEND` variable the address of the backend listening for [`Agents`]().
+  7. Update this volume according to your own deployement paths.
+
+### Containerized deployement with locally build images
+
+### Manual installation

docs/teacher.md

@@ -0,0 +1 @@
+# Teaching Interface

mkdocs.yml

@@ -0,0 +1,83 @@
+site_name: INGInious
+site_url: "https://docs.inginious.org"
+repo_url: "https://github.com/UCL-INGI/INGInious"
+repo_name: "UCL-INGI/INGInious"
+
+theme:
+  name: material
+  logo: assets/header.png
+  features:
+    - search:
+        lang: en
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.indexes 
+    - toc.integrate
+    - navigation.top
+    - navigation.footer
+    - content.code.copy
+    - content.code.annotate
+
+  palette: 
+    # Palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7 
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+markdown_extensions:
+  - tables
+  - attr_list
+  - md_in_html
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+
+extra:
+  version:
+    provider: mike
+  social:
+    - icon: simple/zulip
+      link: https://inginious.zulipchat.com/
+    - icon: fontawesome/regular/message
+      link: https://github.com/UCL-INGI/INGInious/discussions
+    - icon: fontawesome/brands/github
+      link: https://github.com/UCL-INGI/INGInious
+  copyright: Copyright © 2014 - 2023 Université catholique de Louvain.
+
+plugins:
+  - search:
+  - mkdoxy:
+      projects:
+        api:
+          src-dirs: inginious
+          full-doc: True
+          doxy-cfg:
+            FILE_PATTERNS: "*.py"
+            RECURSIVE: True
+            OPTIMIZE_OUTPUT_JAVA: True
+      save-api: .mkdoxy
+
+nav:
+  - index.md
+  - setup.md
+  - admin.md
+  - teacher.md
+  - API Documentation:
+    - api/index.md
+    - Links: api/links.md
+  - change.md