Merge pull request #1396 from dodona-edu/docs/update-v2.5

rien · web-flow · commit d23b1b92cf09 · 2024-02-28T16:31:10.000+01:00
Update documentation website
diff --git a/README.md b/README.md
@@ -33,22 +33,13 @@ Dolos is a [web app](https://dolos.ugent.be) that analyses source code files for
 In addition, it offers a command-line interface to run an analysis locally, showing the interactive user interface in your browser by launching a local webserver.
 The analysis results are available in machine readable CSV files and Dolos can be integrated as a [JavaScript library](https://www.npmjs.com/package/@dodona/dolos-lib) in other applications empowering users to integrate plagiarism detection in their personal workflow.
 
-Try Dolos on <https://dolos.ugent.be>.
+You can use our free to use instance of Dolos on <https://dolos.ugent.be>.
 
 ## Self-hosting Dolos
 
-We provide an instance of the Dolos web app free of charge at <https://dolos.ugent.be>.
-There are no hidden costs and we do not sell, distribute or abuse data in it in any way.
+As Dolos is open source, it is also possible to host the Dolos web app.
 
-Dolos is fully open-source and you can self-host your own instance.
-The simplest way to self-host dolos, is by using the `docker-compose.yml` configuration in the root of this repository:
-
-1. Ensure [Docker Engine](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) are installed on the system where you will be running Dolos on.
-2. The compose-file is configured to run on localhost only. If you want to host Dolos publicly, change the corresponding configuration in the compose file.
-3. Run `docker-compose build` in this directory to pull and fetch all needed container images.
-4. Run `docker-compose up` to start the services.
-
-If you encounter any issues during the setup, please get in touch.
+Follow our instructions on <https://dolos.ugent.be/docs>.
 
 ## Local installation with Dolos CLI
 
diff --git a/docs/.vitepress/components/PublicationsPage.vue b/docs/.vitepress/components/PublicationsPage.vue
@@ -10,7 +10,7 @@ const props = defineProps<{
 <template>
   <div class="hero">
     <h1 class="hero-title">Publications</h1>
-    <p class="hero-lead">Dolos is developed by <a href="https://dodona.ugent.be/en/about/">Team Dodona</a> at Ghent University in Belgium. Our research is published in the following journals and conferences.</p>
+    <p class="hero-lead">Dolos is developed by <a href="https://dodona.be/en/about/">Team Dodona</a> at Ghent University in Belgium. Our research is published in the following journals and conferences.</p>
   </div>
   <slot />
 </template>
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -10,32 +10,31 @@ export default defineConfig({
   ],
 
   themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
-
     nav: [
-      { text: 'Documentation', link: '/guide/' },
-      { text: 'Examples', link: '/try/' },
+      { text: 'Documentation', link: '/docs/' },
+      { text: 'Examples', link: '/demo/' },
       { text: 'Use Dolos', link: 'https://dolos.ugent.be/server' },
     ],
 
     sidebar: [
-      { text: "Introduction", link: "/guide/" },
+      { text: "Introduction", link: "/docs/" },
       {
         text: 'Dolos',
         items: [
-          { text: 'Use Dolos', link: '/guide/server' },
-          { text: 'Use case: Dodona', link: '/guide/dodona' },
+          { text: 'Use Dolos', link: '/docs/server' },
+          { text: 'Use case: Dodona', link: '/docs/dodona' },
+          { text: 'Self-host Dolos', link: '/docs/hosting-dolos' },
         ]
       },
       {
         text: 'Dolos CLI & Library',
         items: [
-          { text: 'Install Dolos CLI', link: '/guide/installation' },
-          { text: 'Use Dolos CLI', link: '/guide/running' },
-          { text: 'Run Dolos CLI using docker', link: '/guide/docker' },
-          { text: 'Add metadata', link: '/guide/adding-metadata' },
-          { text: 'Add new languages', link: '/guide/adding-languages' },
-          { text: 'Use the Dolos library', link: '/guide/library' },
+          { text: 'Install Dolos CLI', link: '/docs/installation' },
+          { text: 'Use Dolos CLI', link: '/docs/running' },
+          { text: 'Run Dolos CLI using docker', link: '/docs/docker' },
+          { text: 'Add metadata', link: '/docs/adding-metadata' },
+          { text: 'Add new languages', link: '/docs/adding-languages' },
+          { text: 'Use the Dolos library', link: '/docs/library' },
         ]
       },
       {
@@ -44,10 +43,10 @@ export default defineConfig({
           { text: 'How Dolos works', link: '/about/algorithm' },
           { text: 'Supported programming languages', link: '/about/languages' },
           { text: 'Research publications', link: '/about/publications' },
+          { text: 'Contact us', link: '/about/contact' },
         ]
       }
     ],
-
     socialLinks: [
       { icon: 'github', link: 'https://github.com/dodona-edu/dolos' }
     ],
diff --git a/docs/about/contact.md b/docs/about/contact.md
@@ -0,0 +1,11 @@
+# Contact us
+
+We would love to hear from you how you are using Dolos and we stand by to help should any problem arise.
+
+Dolos is developed by [Team Dodona](https://dodona.be/en/about/), you can contact us by choosing one of the options below:
+
+- [Open a discussion on GitHub](https://github.com/dodona-edu/dolos/discussions) for general questions and support.
+- [Create an issue on GitHub](https://github.com/dodona-edu/dolos/issues/new/choose) for bug reports, feature requests or language requests.
+- [Send us a message](https://dodona.be/en/contact/) if you have a private question, security issue, or to say hi.
+
+We welcome pull requests, invitations for research contributions, and [donations](https://dodona.be/en/support-us/).
diff --git a/docs/about/languages.md b/docs/about/languages.md
@@ -38,11 +38,9 @@ Dolos and Dolos CLI have out-of-the-box support for the most commonly used progr
 ## Requesting support for a new language
 
 If you're using Dolos and your programming language of choice is not in the above list, you can request support
-on our [issue tracker on GitHub](https://github.com/dodona-edu/dolos/issues/1029) or [by sending us an email](mailto:dodona@ugent.be).
+on our [issue tracker on GitHub](https://github.com/dodona-edu/dolos/issues/1029) or [by contacting us](/about/contact).
 
 ## Adding a language locally
 
-If you don't want to wait on our support to add a new language, you can also add it yourself by running the [Dolos CLI](/guide/installation) and [installing additional parsers locally](/guide/adding-languages.md).
+If you don't want to wait on our support to add a new language, you can also add it yourself by running the [Dolos CLI](/docs/installation) and [installing additional parsers locally](/docs/adding-languages.md).
 
-Please let us know if you've been successful, so we can officially add support for the language in our next release of Dolos.
-If you need help, contact us [on GitHub](https://github.com/dodona-edu/dolos/issues/1029) or [by sending us an email](mailto:dodona@ugent.be).
diff --git a/docs/demo/index.md b/docs/demo/index.md
@@ -7,7 +7,7 @@ On this page you can find the results of a plagiarism analysis for a few differe
 
 ## Try on your own data!
 
-If you want to run Dolos yourself, you can follow our [quick start guide](/guide/server.md).
+If you want to run Dolos yourself, you can follow our [quick start guide](/docs/server.md).
 
 ## Classroom dataset
 
@@ -46,7 +46,7 @@ Analysis performed on all 392 submissions for a mandatory assignment. Communicat
 
 ## Benchmark dataset
 
-These reports shows how Dolos performs on the [SOCO dataset](https://pan.webis.de/fire14/pan14-web/soco.html). The inputs of Dolos were enhanced by adding [labels](../guide/running.html#adding-metadata)
+These reports shows how Dolos performs on the [SOCO dataset](https://pan.webis.de/fire14/pan14-web/soco.html). The inputs of Dolos were enhanced by adding [labels](../docs/running.html#adding-metadata)
 indicating whether a file is involved in plagiarism (orange) or not (blue).
 
 Note that these labels were added manually by experts, but they might not be fully accurate. Some submissions look very similar although they are not labeled as plagiarism.
diff --git a/docs/docs/adding-languages.md b/docs/docs/adding-languages.md
@@ -3,8 +3,11 @@
 Dolos is built on top of a [generic parser model](/about/languages.md) to achieve loose coupling with specific programming languages. 
 As a result, it is fairly easy to add support for additional programming languages if a suitable parser is available.
 
-Dolos automatically discovers the available [Tree-sitter parsers](https://tree-sitter.github.io/tree-sitter/) on the local system at runtime.
-As such, adding support for a new language comes down to installing a Tree-sitter parser for that language in the `node_modules` on your system (Dolos searches `NODE_PATH`).
+Dolos bundles officially supported parsers in the [`dolos-parsers`](https://www.npmjs.com/package/@dodona/dolos-parsers) module.
+[Let us know](https://github.com/dodona-edu/dolos/issues/1029) if you want to use a language that is not supported yet.
+
+In addition, Dolos can automatically discover available [Tree-sitter parsers](https://tree-sitter.github.io/tree-sitter/) on the local system at runtime.
+As such, if you are running Dolos locally, you can quickly add support for a new language by installing a Tree-sitter parser for that language in the `node_modules` on your system (Dolos searches `NODE_PATH`).
 
 As an example, we demonstrate how the **Rust** programming language can be supported.
 
@@ -32,7 +35,7 @@ There exists a Rust parser named [`tree-sitter-rust`](https://github.com/tree-si
 
 ::: tip
 If the language you are looking for is not listed on either the website or GitHub, it might be that there is no parser available.
-If that is the case, you can [contact us](mailto:dodona@ugent.be) and we will see if we can help.
+If that is the case, you can [contact us](/about/contact) and we will see if we can help.
 
 It is possible to [create a new parser](https://tree-sitter.github.io/tree-sitter/creating-parsers), but this quickly becomes complicated.
 :::
diff --git a/docs/docs/adding-metadata.md b/docs/docs/adding-metadata.md
diff --git a/docs/docs/docker.md b/docs/docs/docker.md
diff --git a/docs/docs/dodona.md b/docs/docs/dodona.md
@@ -1,10 +1,14 @@
 # Use case: Dodona
 
-To illustrate how Dolos can be used in education practice, we show how teachers can perform plagiarism detection on submissions exported from the coding platform [Dodona](https://dodona.ugent.be).
+To illustrate how Dolos can be used in education practice, we show how teachers can perform plagiarism detection on submissions exported from the coding platform [Dodona](https://dodona.be).
+
+View the video or **follow the instructions below**:
+
+<iframe src="https://player.vimeo.com/video/917504935?h=27230fe835" style="width:100%; aspect-ratio: 16 / 9;" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>
 
 ## Export submissions from Dodona
 
-Export submissions for a programming exercise in a [Dodona](https://dodona.ugent.be) course:
+Export submissions for a programming exercise in a [Dodona](https://dodona.be) course:
 
 1. In the series that contains the exercise, open the series menu and choose _Export student submissions_. ![Series menu showing "Export student submissions" as option](/images/dodona-export-0.png)
 2. Select the exercise and click _Next step_. ![Export wizard showing a selection of exercises](/images/dodona-export-1.png)
@@ -26,11 +30,11 @@ Open the [Dolos web app](https://dolos.ugent.be/server) in your browser. Upload
 
 Within a few seconds, the plagiarism detection report will be ready and you will be able to explore the results.
 
-[Read more about how to use Dolos](/guide/server).
+[Read more about how to use Dolos](/docs/server).
 
 ## Run Dolos CLI (offline)
 
-[Installing Dolos CLI](/guide/installation) on your computer if you haven't done so. Run Dolos on the ZIP-file you just downloaded from Dodona: 
+[Installing Dolos CLI](/docs/installation) on your computer if you haven't done so. Run Dolos on the ZIP-file you just downloaded from Dodona: 
 
 ```shell
 dolos run -f web -l ${LANGUAGE} dodona-exported.zip
diff --git a/docs/docs/hosting-dolos.md b/docs/docs/hosting-dolos.md
@@ -0,0 +1,46 @@
+# Self-hosting the Dolos web app
+
+If you do not want to use our free to use instance ([dolos.ugent.be/server](https://dolos.ugent.be/server)),
+it is also possible to host your own instance.
+
+## Using docker-compose
+
+[Docker](https://www.docker.com/) is a containerization technology that allows you to run our service without the hassle of installing the different dependencies and services yourself.
+
+::: info
+
+The instructions below are for **Linux** and **MacOS** systems only.
+[Contact us](/about/contact) if you want to run the Dolos web app on windows.
+
+:::
+
+Run Dolos on your own system using these instructions:
+
+1. Ensure [Git](https://git-scm.com/downloads), [Docker Engine](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) are installed on the system where you will be running Dolos on.
+2. Clone the Docker repository with Git and enter the new directory
+  ```
+    git clone https://github.com/dodona-edu/dolos.git
+    cd dolos/
+  ```
+2. _(Optional)_ The `docker-compose.yml` configuration is configured to run the web app on localhost only. If you want to host Dolos publicly, change the corresponding configuration in the compose file. [Contact us](/about/contact) if you need help how to do this.
+3. Run `docker-compose build` in this directory to pull and fetch all needed container images.
+4. Run `docker pull ghcr.io/dodona-edu/dolos:latest` to ensure the container running the Dolos CLI is up-to-date.
+5. Run `docker-compose up` to start the services.
+
+You can now visit the web app running locally on <http://localhost:8080>.
+The API is available on <http://localhost:3000>.
+
+::: warning
+
+The Dolos web app launches a new docker container for each analysis.
+For this reason, **we mount the docker socket** (`/var/run/docker.sock`) in the `docker-compose.yml` configuration.
+
+This grants the web app full control over your docker instance.
+
+:::
+
+## Without docker
+
+It is also possible to install the Dolos web app without Docker Compose.
+
+Please refer to the documentation of the `dolos-api` and `dolos-web` components in the repository how to do this or [get in touch with us](/about/contact).
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -1,11 +1,13 @@
 # Introduction
 
+<iframe src="https://player.vimeo.com/video/913639891?h=cbff92408d&loop=1" style="padding-top: 1em; width: 100%; aspect-ratio: 16 / 9;" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>
+
 Dolos is a source code plagiarism detection tool that [supports a broad range of programming languages](/about/languages).
-It is available as [a web app](/guide/server) for regular users, and as a [command-line tool](/guide/installation) and a [JavaScript library](/guide/library) for more advanced users. The source code of Dolos is [open](https://github.com/dodona-edu/dolos) under the MIT license.
+It is available as [a web app](/docs/server) for regular users, and as a [command-line tool](/docs/installation) and a [JavaScript library](/docs/library) for more advanced users. The source code of Dolos is [open](https://github.com/dodona-edu/dolos) under the MIT license.
 
-- [Online examples to see Dolos in action](/try/)
-- [Use Dolos on your own data](/guide/server)
-- [Install Dolos CLI for offline usage](/guide/installation)
+- [Online examples to see Dolos in action](/demo/)
+- [Use Dolos on your own data](/docs/server)
+- [Install Dolos CLI for offline usage](/docs/installation)
 
 See at a glance how similar the analyzed files are from the powerful visualizations provided by Dolos. Based on our experience with teaching programming courses, Dolos focuses on two main use cases:
 
@@ -26,7 +28,7 @@ With Dolos, we want to provide an **open-source** tool that can easily be extend
 
 ## Who made this software?
 
-Dolos is an active research project by [Team Dodona](https://dodona.ugent.be/en/about/) at [Ghent University](https://www.ugent.be/en) (Belgium). Please use this citation if you use Dolos in your own research:
+Dolos is an active research project by [Team Dodona](https://dodona.be/en/about/) at [Ghent University](https://www.ugent.be/en) (Belgium). Please use this citation if you use Dolos in your own research:
 
 > Maertens et. al. (2022) J. Computer Assisted Learning [doi:10.1111/jcal.12662](https://doi.org/10.1111/jcal.12662)
 
diff --git a/docs/docs/installation.md b/docs/docs/installation.md
@@ -75,13 +75,11 @@ dolos --version
 ```
 
 Dolos supports most commonly used programming languages out-of-the box.
-However, you can easily [add a new language](/guide/adding-languages#adding-a-new-language) if your target programming language is not yet supported.
+However, you can easily [add a new language](/docs/adding-languages#adding-a-new-language) if your target programming language is not yet supported.
 
 ## Troubleshooting
 
-If you encounter a problem not listed here, or if the solution does not work for you,
-please contact us a [dodona@ugent.be](mailto:dodona@ugent.be)
-or [open an issue on GitHub](https://github.com/dodona-edu/dolos/issues/new).
+If you encounter a problem not listed here, or if the solution does not work for you, please [get in touch](/about/contact) or [open an issue on GitHub](https://github.com/dodona-edu/dolos/issues/new).
 
 ### Module was compiled against a different Node.js version
 
diff --git a/docs/docs/library.md b/docs/docs/library.md
@@ -3,11 +3,11 @@
 The Dolos CLI is actually a wrapper around the core TypeScript/JavaScript library [@dodona/dolos-lib](https://www.npmjs.com/package/@dodona/dolos-lib).
 This library implements the [algorithms](/about/algorithm) of the Dolos plagiarism detection pipeline.
 Feel free to use or extend individual algorithms in your own projects.
-We're happy to [hear](https://dodona.ugent.be/nl/contact/) about any extensions you make.
+We're happy to [hear](/about/contact) about any extensions you make.
 
 ## Installation
 
-Using `npm` or `yarn` to install the library, similar to [installing the CLI](/guide/installation):
+Using `npm` or `yarn` to install the library, similar to [installing the CLI](/docs/installation):
 
 ```shell
 npm install @dodona/dolos-lib
@@ -42,6 +42,6 @@ for (const pair of report.allPairs()) {
 }
 ```
 
-Since Dolos primarily targets teachers that will use Dolos as a [web app](/guide/server) or as a [command line tool](/guide/running),
+Since Dolos primarily targets teachers that will use Dolos as a [web app](/docs/server) or as a [command line tool](/docs/running),
 the library is not documented as extensive as we would like.
-Feel free to [create an issue on GitHub](https://github.com/dodona-edu/dolos) or [send us an email](mailto:dodona@ugent.be) if you have any questions.
+Feel free to [create an issue on GitHub](https://github.com/dodona-edu/dolos) or [contact us](/about/contact) if you have any questions.
diff --git a/docs/docs/running.md b/docs/docs/running.md
@@ -47,7 +47,7 @@ You can show all command line options by passing the `-h` or `--help` flag or by
 ## Adding metadata
 
 You can improve the plagiarism detection report by adding metadata to your submissions (submission time, labels, author name, ...).
-See the page about [adding metadata](/guide/adding-metadata) to see how.
+See the page about [adding metadata](/docs/adding-metadata) to see how.
 
 ## Modifying plagiarism detection parameters
 
diff --git a/docs/docs/server.md b/docs/docs/server.md
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/package.json b/docs/package.json
diff --git a/docs/yarn.lock b/docs/yarn.lock
