Development: Improve LocalVC and SSH documentation

docs/index.rst

@@ -37,6 +37,7 @@ All these exercises are supposed to be run either live in the lecture with insta
    user/grading
    user/courses/customizable
    user/markdown-support
+   user/integrated-code-lifecycle
    user/exports
    user/mobile-applications
    user/lti

docs/user/exercises/programming.rst

@@ -225,18 +225,3 @@ Integrated Code Lifecycle
 -------------------------
 
 The following sections describe programming exercise features that are part of the integrated code lifecycle system.
-
-Repository View
-^^^^^^^^^^^^^^^
-
-.. include:: programming-integrated-code-lifecycle-repository-view.inc
-
-Build Agent View
-^^^^^^^^^^^^^^^^
-
-.. include:: programming-integrated-code-lifecycle-build-agent-view.inc
-
-Build Overview View
-^^^^^^^^^^^^^^^^^^^
-
-.. include:: programming-integrated-code-lifecycle-build-queue-view.inc

docs/user/icl/general.rst

@@ -0,0 +1,10 @@
+.. _icl-general-information:
+
+General Information
+===================
+
+Artemis offers the Integrated Code Lifecycle (ICL):
+
+- :ref:`Local Version Control<local-vc>`:         Use the Local Version Control to interact with the repositories of programming exercises.
+- :ref:`SSH<basic SSH introduction>`:             Use SSH to perform Git operations on repositories.
+- :ref:`Local Continuous Integration<local-ci>`:  Exercise submissions are built and tested by the Local CI system.

docs/user/exercises/programming-integrated-code-lifecycle-build-agent-view.inc → docs/user/icl/local-ci-build-agent-view.inc

@@ -5,7 +5,7 @@ The build agent view consists of two parts: the *Build Agent Summary View* and t
 The **Build Agent Summary View** shows a list of all build agents in the system, along with their status (idle and running), maximum number of concurrent builds, and running builds.
 The running builds can be canceled individually by clicking the red cancellation button next to the build. An Administrator can also cancel all running builds on a build agent by clicking the '*Cancel All*' button.
 
-.. figure:: programming/build-agent-summary.png
+.. figure:: local-ci/build-agent-summary.png
    :alt: Build Agent Summary View
    :align: center
 
@@ -20,7 +20,7 @@ the submission time, start time, end time, the duration of the build job, the co
 The administrator can click on the participation ID to navigate to the participation's submission page.
 The administrator can also click on the commit hash to navigate to the commits details page and the course ID to navigate to the course management page.
 
-.. figure:: programming/build-agent-details.png
+.. figure:: local-ci/build-agent-details.png
    :alt: Build Agent Details
    :align: center
 

docs/user/exercises/programming-integrated-code-lifecycle-build-queue-view.inc → docs/user/icl/local-ci-build-queue-view.inc

@@ -1,7 +1,7 @@
 Artemis provides a build overview view that displays all queued, running, and finished build jobs. Access to the system-wide build overview is
 exclusively available to **Administrators** through the *System Administration* menu.
 
-.. figure:: programming/buildQueueSystemAdministration.png
+.. figure:: local-ci/buildQueueSystemAdministration.png
    :alt: Build Overview System Administration
    :align: center
 
@@ -10,7 +10,7 @@ exclusively available to **Administrators** through the *System Administration*
 **Instructors** can access the build overview for a specific course through the *Build Overview* button located in *Course Management*.
 This view displays only the queued, running, and finished build jobs associated with the selected course.
 
-.. figure:: programming/buildQueueCourseManagement.png
+.. figure:: local-ci/buildQueueCourseManagement.png
    :alt: Build Overview Course Management
    :align: center
 
@@ -27,7 +27,7 @@ Jobs are dynamically added to and removed from the queue in real-time.
 Users have the ability to cancel any job in progress. The table provides the following information:
 
 
-.. figure:: programming/running-build-jobs.png
+.. figure:: local-ci/running-build-jobs.png
    :alt: Running Build Jobs
    :align: center
 
@@ -43,7 +43,7 @@ Users also have the option to cancel any job that is queued.
 The table below displays the following information:
 
 
-.. figure:: programming/queued-build-jobs.png
+.. figure:: local-ci/queued-build-jobs.png
    :alt: Queued Build Jobs
    :align: center
 
@@ -59,7 +59,7 @@ Instructors can also access build logs with detailed information about the build
 The table provides the following information:
 
 
-.. figure:: programming/finished-build-jobs.png
+.. figure:: local-ci/finished-build-jobs.png
    :alt: Finished Build Jobs
    :align: center
 

docs/user/icl/local-continuous-integration.rst

@@ -0,0 +1,27 @@
+.. _local-ci:
+
+Continuous Integration
+======================
+
+Continuous Integration (CI) is a software development practice where developers frequently merge their code changes into a shared repository. Each change is automatically built and tested, which helps to:
+
+- Detect and address integration issues early
+- Ensure code quality and consistency
+- Streamline the development process
+
+Artemis Local CI is our implementation of these CI principles, tailored to support the Artemis learning platform.
+It provides tools and views to help users build and test in programming exercises effectively.
+
+This document will introduce you to the key components of Artemis Local CI: the Build Agent View and the Build Overview View.
+These tools will assist you throughout your development workflow on the Artemis platform.
+
+Build Agent View
+^^^^^^^^^^^^^^^^
+
+.. include:: local-ci-build-agent-view.inc
+
+
+Build Overview View
+^^^^^^^^^^^^^^^^^^^
+
+.. include:: local-ci-build-queue-view.inc

docs/user/icl/local-vc-authentication.inc

@@ -0,0 +1,61 @@
+Cloning a repository
+^^^^^^^^^^^^^^^^^^^^
+
+You can use Sourcetree, Git from the terminal, or any client you like to clone your Git repository.
+These instructions show you how to clone your repository using Git from the terminal.
+
+From the exercise view, click the code button to display the Clone dialog.
+Copy the clone URL (either the SSH format or the HTTPS, with or without token).
+If you are using the SSH protocol, ensure your public key is stored in your Artemis account settings and loaded on the local system to which you are cloning.
+From a terminal window, change to the local directory where you want to clone your repository.
+
+Paste the command you copied from Bitbucket, for example:
+
+Clone over HTTPS:
+
+.. code-block:: bash
+
+   git clone https://[email protected]/course/documentation-tests.git
+
+
+Clone over HTTPS with access token:
+
+.. code-block:: bash
+
+   git clone https://username:<ACCESS-TOKEN>@artemis.cit.tum.de/course/documentation-tests.git
+
+
+Clone over SSH:
+
+.. code-block:: bash
+
+   git clone ssh://[email protected]/course/documentation-tests.git
+
+
+If the clone was successful, a new sub-directory appears on your local drive.
+This directory has the same name as the repository that you cloned.
+The clone contains the files and metadata that Git requires to maintain the changes you make to the source files.
+
+HTTPS access tokens
+^^^^^^^^^^^^^^^^^^^
+
+Instructors can create HTTP access tokens for repository access in Artemis.
+They are created in the account settings and are used in place of passwords for Git over HTTPS.
+For every student's exercise, Artemis automatically generates an access token, only associated with the repository of this particular exercise.
+You can use
+
+
+
+Token Creation
+""""""""""""""
+
+1. Go to Profile > Settings > VCS token.
+2. Create a new token
+
+Using SSH keys to secure Git operations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Artemis provides a simple way for users to connect securely to repositories, using SSH to perform Git operations.
+Next is a :ref:`small and basic introduction to SSH<basic SSH introduction>`, and if you already know it, :ref:`here is a guide on how to create SSH keys<create ssh key>`.
+If you already have an SSH key, :ref:`add it to your Artemis account here<create ssh key>`.
+

docs/user/exercises/programming-integrated-code-lifecycle-repository-view.inc → docs/user/icl/local-vc-repository-view.inc

@@ -3,13 +3,13 @@ These changes are stored in a repository. A repository is a collection of files
 How to navigate through the repository and view the code is explained in the following sections. This guide is divided into two parts: one for students and one for instructors.
 It is demonstrated using course programming exercises, but the same principles apply to exams as well.
 
-For Students
-""""""""""""
+Access Repositories as Student
+""""""""""""""""""""""""""""""
 
 As a student, you can use the repository to view your course submissions.
 To access your submissions, you need to navigate to the exercise, press the '*Code*' button, and click on |open-repository-button|.
 
-.. figure:: programming/open-repository-student.png
+.. figure:: local-vc/open-repository-student.png
    :alt: Opening the repository in the student view
    :align: center
 
@@ -22,7 +22,7 @@ To the right side of the screen, above the problem statement, you can see the re
 the '*Code*' button to clone the repository to your local machine and see the full commit history by pressing the '*Open Commit History*' button. Finally, you can
 download the repository as a ZIP file by pressing the '*Download Repository*' button.
 
-.. figure:: programming/current-repository-content-view.png
+.. figure:: local-vc/current-repository-content-view.png
    :alt: Current Repository Content
    :align: center
 
@@ -33,7 +33,7 @@ You can see the commit message, the author of the commit, the date of the commit
 If you created a submission with multiple commits, you can see all of them here but only the last commit has the result of the submission.
 Lastly, you can also view the code of the commit by pressing on the commit hash.
 
-.. figure:: programming/commit-history-view.png
+.. figure:: local-vc/commit-history-view.png
    :alt: Commit History View
    :align: center
 
@@ -44,20 +44,20 @@ You can see the changes in the code, the files that have been added, the files t
 Green color indicates the lines that have been added and red color indicates the lines that have been deleted.
 You can also see the commit message, the author of the commit, the date of the commit and the commit hash.
 
-.. figure:: programming/commit-diff-view.png
+.. figure:: local-vc/commit-diff-view.png
    :alt: Commit Diff View
    :align: center
 
    Commit Diff View
 
-For Instructors
-"""""""""""""""
+Access Repositories as Instructor
+"""""""""""""""""""""""""""""""""
 
 As an instructor, you can use the repository to view the submissions of your students. For this purpose, you need to navigate to the exercise participations page.
 Here you can see all the students’ participations for the exercise and navigate to the repository of a student by pressing the '*Code*' button and clicking on |open-repository-button|.
 This will show the repository of the student just like it is shown to the student.
 
-.. figure:: programming/open-repository-instructor-participations.png
+.. figure:: local-vc/open-repository-instructor-participations.png
    :alt: Open Repository Button in Participations Page
    :align: center
 
@@ -66,11 +66,11 @@ This will show the repository of the student just like it is shown to the studen
 You can also see the repositories for an exercises **solution**, **template** and **test** repositories on the exercise management page.
 You can navigate to these repositories by pressing the '*Code*' button and clicking |open-repository-button| as described above.
 
-.. figure:: programming/course-management-repositories.png
+.. figure:: local-vc/course-management-repositories.png
    :alt: Solution, Template and Test Repositories in Exercise Management Page
    :align: center
 
    Solution, Template and Test Repositories in Exercise Management Page
 
-.. |open-repository-button| image:: programming/open-repository-button.png
+.. |open-repository-button| image:: local-vc/open-repository-button.png
    :scale: 50%

docs/user/icl/local-version-control.rst

@@ -0,0 +1,16 @@
+.. _local-vc:
+
+Local Version Control
+=====================
+
+.. contents:: Content of this document
+    :local:
+    :depth: 2
+
+
+Repository View
+^^^^^^^^^^^^^^^
+
+.. include:: local-vc-repository-view.inc
+
+.. include:: local-vc-authentication.inc

docs/user/icl/ssh-add-key-to-artemis.rst

@@ -0,0 +1,66 @@
+.. _use ssh key:
+
+Using SSH with Artemis
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. contents:: Content of this document
+    :local:
+    :depth: 1
+
+You can use SSH keys to establish a secure connection between your computer and Artemis when you are performing Git operations (pull, clone, push) from your local machine.
+Personal keys are attached to your Artemis account – they are bound by that account's permissions and use the account's identity for any operations.
+To use your generated SSH keys with Artemis, you need to add it in the account Settings.
+
+
+Add an SSH key to your Artemis account
+""""""""""""""""""""""""""""""""""""""
+
+**1. Copy your public key**
+
+On Windows in your command prompt, change directory to your .ssh directory, and copy the public key file to your clipboard by running:
+
+.. code-block:: bash
+
+    cd %userprofile%/.ssh
+    clip < id_ed25519.pub
+
+On macOS or Linux simply run the following in a terminal:
+
+.. code-block:: bash
+
+    pbcopy < ~/.ssh/id_ed25519.pub
+
+If pbcopy isn't working, locate the hidden .ssh folder, open the file in a text editor, and copy it to your clipboard.
+Note that on Linux, you may need to download and install xclip, then use that, as shown in this code snippet:
+
+.. code-block:: bash
+
+    sudo apt-get install xclip
+    xclip -sel clip < ~/.ssh/id_ed25519.pub
+
+Note that the key's name is not necessarily **id_ed25519.pub**, but can be arbitrary, and depends on how you saved it.
+
+
+**2. Add the key to your Artemis account**
+
+Open the settings, go to the SSH tab, and select 'New Key'.
+Then paste the copied SSH key into the text box.
+
++---------------------------------------------------+--------------------------------------------------------------+
+|.. figure:: local-vc/open-settings.png             |     .. figure:: local-vc/ssh-add-public-key.png              |
+|   :alt: Open account settings                     |        :alt: Add public SSH key to account                   |
+|   :align: center                                  |        :align: center                                        |
+|                                                   |                                                              |
+|   Open you Artemis account settings               |        Add public SSH key to account in account settings     |
++---------------------------------------------------+--------------------------------------------------------------+
+
+**3. Save the key. You're done!**
+
+Use SSH to connect to Artemis repositories
+""""""""""""""""""""""""""""""""""""""""""
+
+After everything is set up, you can go to a programming exercise, and use the SSH clone URL with git to access the repository locally, like this, for example:
+
+.. code-block:: bash
+
+    git clone ssh://[email protected]:7921/git/COURSE/exercise-user_1.git