Skip to content

Commit

Permalink
docs: improve installation guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@lars-reimann
lars-reimann committed Apr 14, 2024
1 parent 8343680 commit 6347908
Show file tree
Hide file tree
Showing 6 changed files with 66 additions and 30 deletions.
25 changes: 15 additions & 10 deletions .github/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,21 @@ inspection.

## 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

Expand Down
3 changes: 3 additions & 0 deletions docs/getting-started/first-program.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Your First Safe-DS Program

TODO
41 changes: 31 additions & 10 deletions docs/getting-started/installation.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,33 @@
# 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.

## 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.
1 change: 1 addition & 0 deletions docs/mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ nav:
- README.md
- Getting Started:
- Installation: getting-started/installation.md
- First Program: getting-started/first-program.md
- Language Reference:
- pipeline-language/README.md
- Files: pipeline-language/files.md
Expand Down
3 changes: 1 addition & 2 deletions docs/pipeline-language/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# Language Reference

This part of the documentation provides a detailed reference for the Safe-DS DSL. It is divided into the following
sections:
This part of the documentation provides a detailed reference for the Safe-DS language. It is divided into the following sections:

-

Expand Down
23 changes: 15 additions & 8 deletions packages/safe-ds-vscode/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,21 @@ inspection.

## Installation

1. Install this extension to set 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 this extension** 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

Expand Down

0 comments on commit 6347908

Please sign in to comment.