docs: improve global structure (#1023)

Closes #1029

### Summary of Changes

* Separate explanation of the pipeline and the stub language.
* Explain segments after comments. They are not needed to get started.
* Improve home page.
* Improve installation guide.
* Improve home page of language reference.
* Improve documentation of packages.

.github/README.md

@@ -8,20 +8,25 @@
 Safely develop Data Science programs with a statically checked domain specific language (DSL) and integrated tools for data
 inspection.
 
-![demo](../docs/img/readme/demo.gif)
+![demo](../docs/img/home/demo.gif)
 
 ## Installation
 
-1. Get the latest extension for [Visual Studio Code](https://code.visualstudio.com/) from the
-   [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=safe-ds.safe-ds). This sets up a
-   complete _development environment_ for Safe-DS programs.
-2. To _execute_ Safe-DS programs, the [Safe-DS Runner](https://github.com/Safe-DS/Runner) has to be installed and
-   configured additionally:
-    1. Install [Python](https://www.python.org/) (3.11 or 3.12).
-    2. Run `pip install "safe-ds-runner>=0.10.0,<0.11.0"` in a command line to download the latest matching Runner version
-       from [PyPI](https://pypi.org/project/safe-ds-runner/).
-    3. If the Visual Studio Code extension cannot start the runner, adjust the setting `safe-ds.runner.command`.
-       Enter the absolute path to the Runner executable.
+To set up a powerful _integrated development environment_ (_IDE_) for Safe-DS, follow these steps:
+
+1. **Install [Visual Studio Code](https://code.visualstudio.com/)** (VS Code).
+2. **Install the [Safe-DS extension](https://marketplace.visualstudio.com/items?itemName=safe-ds.safe-ds)** for VS Code.
+
+To run Safe-DS programs, you also need the [Safe-DS Runner](https://github.com/Safe-DS/Runner):
+
+1. **Install [Python](https://www.python.org/) (3.11 or 3.12)**. Make sure to add Python to your
+   system's `PATH` during installation. Verify installation by running `python --version` in a
+   command line. You should get output similar to `Python 3.12.2`.
+2. **Open VS Code**.
+3. **Open the command palette** (Menu bar > View > Command Palette).
+4. **Type `Install the Safe-DS Runner`**.
+5. **Press ++enter++**. Installation may take a few minutes, since it downloads and installs several large libraries
+   like PyTorch.
 
 ## Documentation
 

docs/README.md

@@ -5,30 +5,35 @@ hide:
 
 # Safe-DS DSL
 
-Safely develop Data Science programs with a statically checked domain specific language (DSL) and integrated tools for data
-inspection.
+Safely develop Data Science programs with a statically checked domain specific language (DSL) and integrated tools for
+data inspection.
 
-![demo](img/readme/demo.gif){ max-width="400" }
+![demo](img/home/demo.gif){ max-width="400" }
 
-## Installation
 
-1. Get the latest extension for [Visual Studio Code](https://code.visualstudio.com/) from the
-   [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=safe-ds.safe-ds). This sets up a
-   complete _development environment_ for Safe-DS programs.
-2. To _execute_ Safe-DS programs, the [Safe-DS Runner](https://github.com/Safe-DS/Runner) has to be installed and
-   configured additionally:
-    1. Install [Python](https://www.python.org/) (3.11 or 3.12).
-    2. Run `pip install "safe-ds-runner>=0.10.0,<0.11.0"` in a command line to download the latest matching Runner version
-       from [PyPI](https://pypi.org/project/safe-ds-runner/).
-    3. If the Visual Studio Code extension cannot start the runner, adjust the setting `safe-ds.runner.command`.
-       Enter the absolute path to the Runner executable.
+## Using this Documentation
+
+If you look for information about a specific topic, use the search bar at the top of this page. Otherwise, use the
+navigational elements to reach one of the following sections:
+
+| Section                                                  | Description                                                                                      |
+|----------------------------------------------------------|--------------------------------------------------------------------------------------------------|
+| [Getting Started](getting-started/installation.md)       | Learn how to configure a development environment for Safe-DS and write your first program.       |
+| [Language Reference](pipeline-language/README.md)        | Learn about the concepts of the Safe-DS language.                                                |
+| [API Reference][safeds.data.image.containers.Image]      | Learn about the API elements that you can use in Safe-DS programs, like classes and functions.   |
+| [Integrating New Libraries](stub-language/README.md)     | Learn how to integrate new libraries into Safe-DS (:warning: documentation is work in progress). |
+| [Development](development/testing/call-graph-testing.md) | Learn about various aspects of developing Safe-DS itself.                                        |
+
 
 ## Contributing
 
-We welcome contributions from everyone. As a starting point, check the following resources:
+We welcome contributions from everyone, be it a new feature, a bugfix, better documentation, or something else. As a
+starting point, check the following resources:
 
 * [Contributing page](https://github.com/Safe-DS/DSL/contribute)
+* [Open issues](https://github.com/Safe-DS/DSL/issues)
+
 
-If you need further help, please [use our discussion forum][forum].
+## Getting Help
 
-[forum]: https://github.com/orgs/Safe-DS/discussions
+If you need further help, please [use our discussion forum](https://github.com/orgs/Safe-DS/discussions).

docs/getting-started/first-program.md

@@ -0,0 +1,3 @@
+# Your First Safe-DS Program
+
+TODO

docs/getting-started/installation.md

@@ -0,0 +1,33 @@
+# Installation
+
+To set up a powerful _integrated development environment_ (_IDE_) for Safe-DS, follow these steps:
+
+1. **Install [Visual Studio Code](https://code.visualstudio.com/)** (VS Code).
+2. **Install the [Safe-DS extension](https://marketplace.visualstudio.com/items?itemName=safe-ds.safe-ds)** for VS Code.
+
+To run Safe-DS programs, you also need the [Safe-DS Runner](https://github.com/Safe-DS/Runner):
+
+1. **Install [Python](https://www.python.org/) (3.11 or 3.12)**. Make sure to add Python to your
+   system's `PATH` during installation. Verify installation by running `python --version` in a
+   command line. You should get output similar to `Python 3.12.2`.
+2. **Open VS Code**.
+3. **Open the command palette** (Menu bar > View > Command Palette).
+4. **Type `Install the Safe-DS Runner`**.
+5. **Press ++enter++**. Installation may take a few minutes, since it downloads and installs several large libraries
+   like PyTorch.
+
+## Updating the Safe-DS Extension
+
+By default, VS Code automatically updates extensions. You only need to restart VS Code to apply the update.
+
+## Updating the Safe-DS Runner
+
+You need to update the Safe-DS Runner if you see an error message like this:
+
+!!! failure "Error message"
+
+    The installed runner version `0.9.0` is not compatible with this version of the extension.
+
+    The installed version should match these requirements: `>=0.10.0,<0.11.0`. Please update to a matching version.
+
+Click on the button "Update runner" in the error message to trigger the update process.

docs/language/README.md

@@ -1,10 +0,0 @@
-# Safe-DS DSL Tutorial
-
-The Safe-DS DSL is split into two main parts:
-
-- The _[pipeline language][pipeline-language]_ is used to solve specific data science problems. Unless you want to add functionality to Safe-DS, this sublanguage is all you need to learn. To use the pipeline language, create a file with the extension `.sds`.
-- The _[stub language][stub-language]_ is used to integrate external code written in Python into Safe-DS, so it can be used in the [pipeline language][pipeline-language]. The main purpose of this sublanguage is to define the [Safe-DS Standard Library (stdlib)][stdlib]. To use the stub language, create a file with the extension `.sdsstub`.
-
-[pipeline-language]: pipeline-language/README.md
-[stub-language]: stub-language/README.md
-[stdlib]: https://github.com/Safe-DS/DSL/blob/main/packages/safe-ds-lang/src/resources/builtins

docs/language/pipeline-language/README.md

@@ -1,22 +0,0 @@
-# Pipeline Language
-
-The pipeline language is the part of the Safe-DS DSL that is designed to solve specific data science problems. It has the following concepts:
-
-- [Packages][packages] help avoid conflicts that could arise if two declarations have the same name.
-- [Imports][imports] make declarations in other packages accessible.
-- [Pipelines][pipelines] define the entry point of a data science program.
-- [Segments][segments] encapsulate parts of a data science program and make them reusable.
-- [Statements][statements] are the instructions that are executed as part of a [pipeline][pipelines], [segment][segments], or [block lambda][block-lambdas].
-- [Expressions][expressions] are computations that produce some value.
-- [Comments][comments] document the code.
-
-Files that use the pipeline language must have the extension `.sds`.
-
-[packages]: ../common/packages.md
-[imports]: ../common/imports.md
-[pipelines]: pipelines.md
-[segments]: segments.md
-[statements]: statements.md
-[expressions]: expressions.md
-[block-lambdas]: expressions.md#block-lambdas
-[comments]: ../common/comments.md

docs/mkdocs.yml

@@ -12,31 +12,34 @@ exclude_docs: |
 nav:
   - Home:
     - README.md
-  - Language:
-    - language/README.md
-    - Pipeline Language:
-      - language/pipeline-language/README.md
-      - Pipelines: language/pipeline-language/pipelines.md
-      - Segments: language/pipeline-language/segments.md
-      - Statements: language/pipeline-language/statements.md
-      - Expressions: language/pipeline-language/expressions.md
-    - Common:
-      - language/common/README.md
-      - Comments: language/common/comments.md
-      - Packages: language/common/packages.md
-      - Imports: language/common/imports.md
-      - Parameters: language/common/parameters.md
-      - Results: language/common/results.md
-      - Types: language/common/types.md
-      - Variance: language/common/variance.md
-    - Stub Language:
-      - language/stub-language/README.md
-      - Classes: language/stub-language/classes.md
-      - Global Functions: language/stub-language/global-functions.md
-      - Enumerations: language/stub-language/enumerations.md
-      - Annotations: language/stub-language/annotations.md
-      - Type Parameters: language/stub-language/type-parameters.md
-  - Standard Library: stdlib/
+  - Getting Started:
+    - Installation: getting-started/installation.md
+    - First Program: getting-started/first-program.md
+  - Language Reference:
+    - pipeline-language/README.md
+    - Packages: pipeline-language/packages.md
+    - Pipelines: pipeline-language/pipelines.md
+    - Statements: pipeline-language/statements.md
+    - Expressions: pipeline-language/expressions.md
+    - Comments: pipeline-language/comments.md
+    - Segments: pipeline-language/segments.md
+    - Types: pipeline-language/types.md
+    - Imports: pipeline-language/imports.md
+  - API Reference: api/
+  - Integrating New Libraries:
+    - stub-language/README.md
+    - Packages: stub-language/packages.md
+    - Imports: stub-language/imports.md
+    - Classes: stub-language/classes.md
+    - Global Functions: stub-language/global-functions.md
+    - Enumerations: stub-language/enumerations.md
+    - Annotations: stub-language/annotations.md
+    - Comments: stub-language/comments.md
+    - Parameters: stub-language/parameters.md
+    - Results: stub-language/results.md
+    - Types: stub-language/types.md
+    - Type Parameters: stub-language/type-parameters.md
+    - Variance: stub-language/variance.md
   - Development:
     - Testing:
       - Call Graph Testing: development/testing/call-graph-testing.md
@@ -140,9 +143,9 @@ markdown_extensions:
       permalink: true
 
 extra_css:
-  - stylesheets/extra.css
+  - src/stylesheets/extra.css
 
 extra_javascript:
-  - javascript/mathjax.js
+  - src/javascript/mathjax.js
   - https://polyfill.io/v3/polyfill.min.js?features=es6
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

docs/pipeline-language/README.md

@@ -0,0 +1,30 @@
+# Language Reference
+
+Safe-DS is a domain-specific language (DSL) to quickly and safely develop data science programs. In this context,
+safety means that it tries to prevent errors or detect them while you program, so you do not waste time running a
+program that will fail.
+
+!!! note "File extension"
+
+    Safe-DS programs must have the file extension `sds`, like in `titanic.sds`.
+
+This remaining documentation provides a detailed reference for the concepts of the Safe-DS language:
+
+- [Packages][packages] help avoid conflicts that could arise if two declarations have the same name.
+- [Pipelines][pipelines] define the entry point of a program.
+- [Statements][statements] are the instructions that are executed as part of a program.
+- [Expressions][expressions] are computations that produce some value.
+- [Comments][comments] document the code.
+- [Segments][segments] encapsulate parts of program and make them reusable.
+- [Types][types] describe the kind of data that a declaration accepts.
+- [Imports][imports] make declarations in other packages accessible.
+
+
+[packages]: packages.md
+[pipelines]: pipelines.md
+[statements]: statements.md
+[expressions]: expressions.md
+[comments]: comments.md
+[segments]: segments.md
+[types]: types.md
+[imports]: imports.md