diff --git a/.github/README.md b/.github/README.md index 7bafa20f2..b4af47ce7 100644 --- a/.github/README.md +++ b/.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 diff --git a/docs/README.md b/docs/README.md index 634c917e0..0ff19ece5 100644 --- a/docs/README.md +++ b/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). diff --git a/docs/stdlib/SUMMARY.md b/docs/api/SUMMARY.md similarity index 100% rename from docs/stdlib/SUMMARY.md rename to docs/api/SUMMARY.md diff --git a/docs/stdlib/safeds/data/image/containers/Image.md b/docs/api/safeds/data/image/containers/Image.md similarity index 100% rename from docs/stdlib/safeds/data/image/containers/Image.md rename to docs/api/safeds/data/image/containers/Image.md diff --git a/docs/stdlib/safeds/data/tabular/containers/Column.md b/docs/api/safeds/data/tabular/containers/Column.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/containers/Column.md rename to docs/api/safeds/data/tabular/containers/Column.md diff --git a/docs/stdlib/safeds/data/tabular/containers/Row.md b/docs/api/safeds/data/tabular/containers/Row.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/containers/Row.md rename to docs/api/safeds/data/tabular/containers/Row.md diff --git a/docs/stdlib/safeds/data/tabular/containers/Table.md b/docs/api/safeds/data/tabular/containers/Table.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/containers/Table.md rename to docs/api/safeds/data/tabular/containers/Table.md diff --git a/docs/stdlib/safeds/data/tabular/containers/TaggedTable.md b/docs/api/safeds/data/tabular/containers/TaggedTable.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/containers/TaggedTable.md rename to docs/api/safeds/data/tabular/containers/TaggedTable.md diff --git a/docs/stdlib/safeds/data/tabular/containers/TimeSeries.md b/docs/api/safeds/data/tabular/containers/TimeSeries.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/containers/TimeSeries.md rename to docs/api/safeds/data/tabular/containers/TimeSeries.md diff --git a/docs/stdlib/safeds/data/tabular/transformation/Discretizer.md b/docs/api/safeds/data/tabular/transformation/Discretizer.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/transformation/Discretizer.md rename to docs/api/safeds/data/tabular/transformation/Discretizer.md diff --git a/docs/stdlib/safeds/data/tabular/transformation/Imputer.md b/docs/api/safeds/data/tabular/transformation/Imputer.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/transformation/Imputer.md rename to docs/api/safeds/data/tabular/transformation/Imputer.md diff --git a/docs/stdlib/safeds/data/tabular/transformation/InvertibleTableTransformer.md b/docs/api/safeds/data/tabular/transformation/InvertibleTableTransformer.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/transformation/InvertibleTableTransformer.md rename to docs/api/safeds/data/tabular/transformation/InvertibleTableTransformer.md diff --git a/docs/stdlib/safeds/data/tabular/transformation/LabelEncoder.md b/docs/api/safeds/data/tabular/transformation/LabelEncoder.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/transformation/LabelEncoder.md rename to docs/api/safeds/data/tabular/transformation/LabelEncoder.md diff --git a/docs/stdlib/safeds/data/tabular/transformation/OneHotEncoder.md b/docs/api/safeds/data/tabular/transformation/OneHotEncoder.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/transformation/OneHotEncoder.md rename to docs/api/safeds/data/tabular/transformation/OneHotEncoder.md diff --git a/docs/stdlib/safeds/data/tabular/transformation/RangeScaler.md b/docs/api/safeds/data/tabular/transformation/RangeScaler.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/transformation/RangeScaler.md rename to docs/api/safeds/data/tabular/transformation/RangeScaler.md diff --git a/docs/stdlib/safeds/data/tabular/transformation/StandardScaler.md b/docs/api/safeds/data/tabular/transformation/StandardScaler.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/transformation/StandardScaler.md rename to docs/api/safeds/data/tabular/transformation/StandardScaler.md diff --git a/docs/stdlib/safeds/data/tabular/transformation/TableTransformer.md b/docs/api/safeds/data/tabular/transformation/TableTransformer.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/transformation/TableTransformer.md rename to docs/api/safeds/data/tabular/transformation/TableTransformer.md diff --git a/docs/stdlib/safeds/data/tabular/typing/ColumnType.md b/docs/api/safeds/data/tabular/typing/ColumnType.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/typing/ColumnType.md rename to docs/api/safeds/data/tabular/typing/ColumnType.md diff --git a/docs/stdlib/safeds/data/tabular/typing/Schema.md b/docs/api/safeds/data/tabular/typing/Schema.md similarity index 100% rename from docs/stdlib/safeds/data/tabular/typing/Schema.md rename to docs/api/safeds/data/tabular/typing/Schema.md diff --git a/docs/stdlib/safeds/lang/AnnotationTarget.md b/docs/api/safeds/lang/AnnotationTarget.md similarity index 100% rename from docs/stdlib/safeds/lang/AnnotationTarget.md rename to docs/api/safeds/lang/AnnotationTarget.md diff --git a/docs/stdlib/safeds/lang/Any.md b/docs/api/safeds/lang/Any.md similarity index 100% rename from docs/stdlib/safeds/lang/Any.md rename to docs/api/safeds/lang/Any.md diff --git a/docs/stdlib/safeds/lang/Boolean.md b/docs/api/safeds/lang/Boolean.md similarity index 100% rename from docs/stdlib/safeds/lang/Boolean.md rename to docs/api/safeds/lang/Boolean.md diff --git a/docs/stdlib/safeds/lang/Deprecated.md b/docs/api/safeds/lang/Deprecated.md similarity index 100% rename from docs/stdlib/safeds/lang/Deprecated.md rename to docs/api/safeds/lang/Deprecated.md diff --git a/docs/stdlib/safeds/lang/Experimental.md b/docs/api/safeds/lang/Experimental.md similarity index 100% rename from docs/stdlib/safeds/lang/Experimental.md rename to docs/api/safeds/lang/Experimental.md diff --git a/docs/stdlib/safeds/lang/Expert.md b/docs/api/safeds/lang/Expert.md similarity index 100% rename from docs/stdlib/safeds/lang/Expert.md rename to docs/api/safeds/lang/Expert.md diff --git a/docs/stdlib/safeds/lang/Float.md b/docs/api/safeds/lang/Float.md similarity index 100% rename from docs/stdlib/safeds/lang/Float.md rename to docs/api/safeds/lang/Float.md diff --git a/docs/stdlib/safeds/lang/Impure.md b/docs/api/safeds/lang/Impure.md similarity index 100% rename from docs/stdlib/safeds/lang/Impure.md rename to docs/api/safeds/lang/Impure.md diff --git a/docs/stdlib/safeds/lang/ImpurityReason.md b/docs/api/safeds/lang/ImpurityReason.md similarity index 100% rename from docs/stdlib/safeds/lang/ImpurityReason.md rename to docs/api/safeds/lang/ImpurityReason.md diff --git a/docs/stdlib/safeds/lang/Int.md b/docs/api/safeds/lang/Int.md similarity index 100% rename from docs/stdlib/safeds/lang/Int.md rename to docs/api/safeds/lang/Int.md diff --git a/docs/stdlib/safeds/lang/List.md b/docs/api/safeds/lang/List.md similarity index 100% rename from docs/stdlib/safeds/lang/List.md rename to docs/api/safeds/lang/List.md diff --git a/docs/stdlib/safeds/lang/Map.md b/docs/api/safeds/lang/Map.md similarity index 100% rename from docs/stdlib/safeds/lang/Map.md rename to docs/api/safeds/lang/Map.md diff --git a/docs/stdlib/safeds/lang/Nothing.md b/docs/api/safeds/lang/Nothing.md similarity index 100% rename from docs/stdlib/safeds/lang/Nothing.md rename to docs/api/safeds/lang/Nothing.md diff --git a/docs/stdlib/safeds/lang/Number.md b/docs/api/safeds/lang/Number.md similarity index 100% rename from docs/stdlib/safeds/lang/Number.md rename to docs/api/safeds/lang/Number.md diff --git a/docs/stdlib/safeds/lang/Pure.md b/docs/api/safeds/lang/Pure.md similarity index 100% rename from docs/stdlib/safeds/lang/Pure.md rename to docs/api/safeds/lang/Pure.md diff --git a/docs/stdlib/safeds/lang/PythonCall.md b/docs/api/safeds/lang/PythonCall.md similarity index 100% rename from docs/stdlib/safeds/lang/PythonCall.md rename to docs/api/safeds/lang/PythonCall.md diff --git a/docs/stdlib/safeds/lang/PythonModule.md b/docs/api/safeds/lang/PythonModule.md similarity index 100% rename from docs/stdlib/safeds/lang/PythonModule.md rename to docs/api/safeds/lang/PythonModule.md diff --git a/docs/stdlib/safeds/lang/PythonName.md b/docs/api/safeds/lang/PythonName.md similarity index 100% rename from docs/stdlib/safeds/lang/PythonName.md rename to docs/api/safeds/lang/PythonName.md diff --git a/docs/stdlib/safeds/lang/Repeatable.md b/docs/api/safeds/lang/Repeatable.md similarity index 100% rename from docs/stdlib/safeds/lang/Repeatable.md rename to docs/api/safeds/lang/Repeatable.md diff --git a/docs/stdlib/safeds/lang/String.md b/docs/api/safeds/lang/String.md similarity index 100% rename from docs/stdlib/safeds/lang/String.md rename to docs/api/safeds/lang/String.md diff --git a/docs/stdlib/safeds/lang/Target.md b/docs/api/safeds/lang/Target.md similarity index 100% rename from docs/stdlib/safeds/lang/Target.md rename to docs/api/safeds/lang/Target.md diff --git a/docs/stdlib/safeds/ml/classical/classification/AdaBoostClassifier.md b/docs/api/safeds/ml/classical/classification/AdaBoostClassifier.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/classification/AdaBoostClassifier.md rename to docs/api/safeds/ml/classical/classification/AdaBoostClassifier.md diff --git a/docs/stdlib/safeds/ml/classical/classification/Classifier.md b/docs/api/safeds/ml/classical/classification/Classifier.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/classification/Classifier.md rename to docs/api/safeds/ml/classical/classification/Classifier.md diff --git a/docs/stdlib/safeds/ml/classical/classification/DecisionTreeClassifier.md b/docs/api/safeds/ml/classical/classification/DecisionTreeClassifier.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/classification/DecisionTreeClassifier.md rename to docs/api/safeds/ml/classical/classification/DecisionTreeClassifier.md diff --git a/docs/stdlib/safeds/ml/classical/classification/GradientBoostingClassifier.md b/docs/api/safeds/ml/classical/classification/GradientBoostingClassifier.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/classification/GradientBoostingClassifier.md rename to docs/api/safeds/ml/classical/classification/GradientBoostingClassifier.md diff --git a/docs/stdlib/safeds/ml/classical/classification/KNearestNeighborsClassifier.md b/docs/api/safeds/ml/classical/classification/KNearestNeighborsClassifier.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/classification/KNearestNeighborsClassifier.md rename to docs/api/safeds/ml/classical/classification/KNearestNeighborsClassifier.md diff --git a/docs/stdlib/safeds/ml/classical/classification/LogisticRegressionClassifier.md b/docs/api/safeds/ml/classical/classification/LogisticRegressionClassifier.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/classification/LogisticRegressionClassifier.md rename to docs/api/safeds/ml/classical/classification/LogisticRegressionClassifier.md diff --git a/docs/stdlib/safeds/ml/classical/classification/RandomForestClassifier.md b/docs/api/safeds/ml/classical/classification/RandomForestClassifier.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/classification/RandomForestClassifier.md rename to docs/api/safeds/ml/classical/classification/RandomForestClassifier.md diff --git a/docs/stdlib/safeds/ml/classical/classification/SupportVectorMachineClassifier.md b/docs/api/safeds/ml/classical/classification/SupportVectorMachineClassifier.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/classification/SupportVectorMachineClassifier.md rename to docs/api/safeds/ml/classical/classification/SupportVectorMachineClassifier.md diff --git a/docs/stdlib/safeds/ml/classical/regression/AdaBoostRegressor.md b/docs/api/safeds/ml/classical/regression/AdaBoostRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/AdaBoostRegressor.md rename to docs/api/safeds/ml/classical/regression/AdaBoostRegressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/DecisionTreeRegressor.md b/docs/api/safeds/ml/classical/regression/DecisionTreeRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/DecisionTreeRegressor.md rename to docs/api/safeds/ml/classical/regression/DecisionTreeRegressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/ElasticNetRegressor.md b/docs/api/safeds/ml/classical/regression/ElasticNetRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/ElasticNetRegressor.md rename to docs/api/safeds/ml/classical/regression/ElasticNetRegressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/GradientBoostingRegressor.md b/docs/api/safeds/ml/classical/regression/GradientBoostingRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/GradientBoostingRegressor.md rename to docs/api/safeds/ml/classical/regression/GradientBoostingRegressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/KNearestNeighborsRegressor.md b/docs/api/safeds/ml/classical/regression/KNearestNeighborsRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/KNearestNeighborsRegressor.md rename to docs/api/safeds/ml/classical/regression/KNearestNeighborsRegressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/LassoRegressor.md b/docs/api/safeds/ml/classical/regression/LassoRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/LassoRegressor.md rename to docs/api/safeds/ml/classical/regression/LassoRegressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/LinearRegressionRegressor.md b/docs/api/safeds/ml/classical/regression/LinearRegressionRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/LinearRegressionRegressor.md rename to docs/api/safeds/ml/classical/regression/LinearRegressionRegressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/RandomForestRegressor.md b/docs/api/safeds/ml/classical/regression/RandomForestRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/RandomForestRegressor.md rename to docs/api/safeds/ml/classical/regression/RandomForestRegressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/Regressor.md b/docs/api/safeds/ml/classical/regression/Regressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/Regressor.md rename to docs/api/safeds/ml/classical/regression/Regressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/RidgeRegressor.md b/docs/api/safeds/ml/classical/regression/RidgeRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/RidgeRegressor.md rename to docs/api/safeds/ml/classical/regression/RidgeRegressor.md diff --git a/docs/stdlib/safeds/ml/classical/regression/SupportVectorMachineRegressor.md b/docs/api/safeds/ml/classical/regression/SupportVectorMachineRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/classical/regression/SupportVectorMachineRegressor.md rename to docs/api/safeds/ml/classical/regression/SupportVectorMachineRegressor.md diff --git a/docs/stdlib/safeds/ml/nn/FNNLayer.md b/docs/api/safeds/ml/nn/FNNLayer.md similarity index 100% rename from docs/stdlib/safeds/ml/nn/FNNLayer.md rename to docs/api/safeds/ml/nn/FNNLayer.md diff --git a/docs/stdlib/safeds/ml/nn/NeuralNetworkClassifier.md b/docs/api/safeds/ml/nn/NeuralNetworkClassifier.md similarity index 100% rename from docs/stdlib/safeds/ml/nn/NeuralNetworkClassifier.md rename to docs/api/safeds/ml/nn/NeuralNetworkClassifier.md diff --git a/docs/stdlib/safeds/ml/nn/NeuralNetworkRegressor.md b/docs/api/safeds/ml/nn/NeuralNetworkRegressor.md similarity index 100% rename from docs/stdlib/safeds/ml/nn/NeuralNetworkRegressor.md rename to docs/api/safeds/ml/nn/NeuralNetworkRegressor.md diff --git a/docs/getting-started/first-program.md b/docs/getting-started/first-program.md new file mode 100644 index 000000000..2bb9a78d2 --- /dev/null +++ b/docs/getting-started/first-program.md @@ -0,0 +1,3 @@ +# Your First Safe-DS Program + +TODO diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 000000000..abd73e786 --- /dev/null +++ b/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. diff --git a/docs/img/readme/demo.gif b/docs/img/home/demo.gif similarity index 100% rename from docs/img/readme/demo.gif rename to docs/img/home/demo.gif diff --git a/docs/language/README.md b/docs/language/README.md index d4676b4a1..e69de29bb 100644 --- a/docs/language/README.md +++ b/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 diff --git a/docs/language/common/README.md b/docs/language/common/README.md deleted file mode 100644 index 95e6e6d82..000000000 --- a/docs/language/common/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# Common Parts of Pipeline Language and Stub Language - -Several parts of the Safe-DS DSL are shared between the [pipeline lanugage][pipeline-language] and the [stub language][stub-language]. Here is the list: - -- [Packages][packages] help avoid conflicts that could arise if two declarations have the same name. -- [Imports][imports] make declarations in other packages accessible. -- [Parameters][parameters] define the expected inputs of some declaration that can be [called][calls]. -- [Results][results] define the outputs of some declaration when it is [called][calls]. -- [Types][types] describe the values that a declaration can accept. -- [Comments][comments] document the code. - -[pipeline-language]: ../pipeline-language/README.md -[stub-language]: ../stub-language/README.md -[calls]: ../pipeline-language/expressions.md#calls -[packages]: packages.md -[imports]: imports.md -[parameters]: parameters.md -[results]: results.md -[types]: types.md -[comments]: comments.md diff --git a/docs/language/pipeline-language/README.md b/docs/language/pipeline-language/README.md index 46cac1b72..e69de29bb 100644 --- a/docs/language/pipeline-language/README.md +++ b/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 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 130f7a084..20926c892 100644 --- a/docs/mkdocs.yml +++ b/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 diff --git a/docs/pipeline-language/README.md b/docs/pipeline-language/README.md new file mode 100644 index 000000000..7e23ef2ec --- /dev/null +++ b/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 diff --git a/docs/pipeline-language/comments.md b/docs/pipeline-language/comments.md new file mode 100644 index 000000000..bcd72839a --- /dev/null +++ b/docs/pipeline-language/comments.md @@ -0,0 +1,164 @@ +# Comments + +Comments are mostly used to add explanations to the code for future readers — which is often yourself. They can also be +used to "comment out" code that you want to keep but that should not be run right now, since comments are ignored by the +compiler. + +Safe-DS has three types of comments, namely + +* [_line comments_](#line-comments), which end at a linebreak, +* [_block comments_](#block-comments), which can cover multiple lines, and +* [_documentation comments_](#documentation-comments), which are used to specify the documentation for declarations. + +## Line Comments + +Line comments stop at the end of a line: + +```sds +// This is a comment. +``` + +They start with `#!sds //`. There must be no space between the slashes. Everything after the double slashes in the same +line is the text of the comment. + +To use line comments to "comment out" code you edit in VS Code, select the code and press ++ctrl+slash++ on your +keyboard. This will add `#!sds //` to the beginning of each selected line. You can also trigger this functionality by +using the `Toggle Line Comment` command in the command palette. To remove the line comments, select the commented code +and press ++ctrl+slash++ again. + +## Block Comments + +Block comments have a start and end delimiter, which allows them to cover multiple lines: + +```sds +/* +This +is +another +comment +*/ +``` + +They start with `#!sds /*` and end at the inverted delimiter `#!sds */`. There must be no space between the slash +and the star. Block comments cannot be nested. Everything in between the delimiters is the text of the comment. + +To use block comments to "comment out" code you edit in VS Code, select the code and press ++ctrl+shift+slash++ on your +keyboard. This will surround the selected code with `#!sds /*` and `#!sds */`. You can also trigger this functionality +by using the `Toggle Block Comment` command in the command palette. To remove the block comment, select the commented +code and press ++ctrl+shift+slash++ again. + +## Documentation Comments + +Documentation comments are special [block comments](#block-comments) that are used to document declarations[^1]. The +documentation is used in various places, e.g. when hovering over a declaration or one of its usage in VS Code. Here is +an example: + +```sds +/** + * This is a documentation comment. + */ +class C +``` + +They start with `#!sds /**` and end with `#!sds */`. There must be no spaces inside the delimiters. Documentation +comments cannot be nested. Everything in between the delimiters is the text of the comment, except an optional leading +asterisk in each line, which is ignored. Documentation comments are attached to the declaration that follows them. If +there is no declaration following the documentation comment, it is treated as a normal [block comment](#block-comments), +with no special meaning. + +### Markdown + +Documentation comments support [Markdown](https://www.markdownguide.org/) to format the text. Here is an example: + +```sds hl_lines="2" +/** + * This is a documentation comment with **bold** and *italic* text. + */ +class C +``` + +### Tags + +Documentation comments can contain tags to provide structured information. + +#### `{@link}` + +`{@link}` is an **inline** tag that can be used to link to another declaration. It takes the name of the declaration as +an argument: + +```sds hl_lines="2" +/** + * Computes the sum of two {@link Int}s. + */ +fun sum(a: Int, b: Int): sum: Int +``` + +To point to a member of a [class][class] or an [enum variant][enum-variant] of an [enum][enum], write the name of the +containing declaration followed by a dot and the name of the member or enum variant: + +```sds hl_lines="2" +/** + * To create a Configuration, use {@link Configuration.fromFile}. + */ +class Configuration { + + /** + * Creates a Configuration from a file. + */ + fun fromFile(file: String) -> result: Configuration +} +``` + +#### `@param` + +Use `@param` to document a [parameter][parameter] of a callable declaration. This tag takes the name of the parameter +and its description as arguments. Since a callable can have multiple parameters, this tag can be used multiple times. + +```sds hl_lines="4 5" +/** + * ... + * + * @param a The first integer. + * @param b The second integer. + */ +fun sum(a: Int, b: Int): sum: Int +``` + +#### `@result` + +Use `@result` to document a [result][result] of a callable declaration. This tag takes the name of the result and its +description as arguments. Since a callable can have multiple results, this tag can be used multiple times. + +```sds hl_lines="4" +/** + * ... + * + * @result sum The sum of `a` and `b`. + */ +fun sum(a: Int, b: Int): sum: Int +``` + +#### `@since` + +The `@since` tag can be used to specify when a declaration was added. It takes the version as argument and should be +used only once. + +```sds hl_lines="4" +/** + * ... + * + * @since 1.0.0 + */ +fun sum(a: Int, b: Int): sum: Int +``` + +[^1]: Except [parameter][parameter], [results][result], and [type parameters][type-parameter], which are documented with +the [`@param`](#param), [`@result`](#result), and [`@typeParam`](#typeparam) tags on the containing declaration, +respectively. + +[class]: ../stub-language/classes.md +[enum]: ../stub-language/enumerations.md +[enum-variant]: ../stub-language/enumerations.md#enum-variants +[parameter]: segments.md#parameters +[result]: segments.md#results +[type-parameter]: ../stub-language/type-parameters.md diff --git a/docs/language/pipeline-language/expressions.md b/docs/pipeline-language/expressions.md similarity index 99% rename from docs/language/pipeline-language/expressions.md rename to docs/pipeline-language/expressions.md index aefcf70f9..c7b153bfa 100644 --- a/docs/language/pipeline-language/expressions.md +++ b/docs/pipeline-language/expressions.md @@ -602,13 +602,13 @@ We all know that `#!sds 2 + 3 * 7` is `#!sds 23` and not `#!sds 35`. The reason If the default precedence of operators is not sufficient, parentheses can be used to force a part of an expression to be evaluated first. -[imports]: ../common/imports.md -[packages]: ../common/packages.md -[parameters]: ../common/parameters.md -[required-parameters]: ../common/parameters.md#required-parameters -[results]: ../common/results.md -[types]: ../common/types.md -[callable-types]: ../common/types.md#callable-types +[imports]: imports.md +[packages]: packages.md +[parameters]: segments.md#parameters +[required-parameters]: segments.md#required-parameters +[results]: segments.md#results +[types]: types.md +[callable-types]: types.md#callable-types [classes]: ../stub-language/classes.md [attributes]: ../stub-language/classes.md#defining-attributes [methods]: ../stub-language/classes.md#defining-methods diff --git a/docs/language/common/imports.md b/docs/pipeline-language/imports.md similarity index 100% rename from docs/language/common/imports.md rename to docs/pipeline-language/imports.md diff --git a/docs/pipeline-language/packages.md b/docs/pipeline-language/packages.md new file mode 100644 index 000000000..e2c9e5d32 --- /dev/null +++ b/docs/pipeline-language/packages.md @@ -0,0 +1,24 @@ +# Packages + +_Packages_ prevent conflicts when multiple files have declarations with the same name. They accomplish this by grouping +all declarations in a file into a namespace. All Safe-DS programs must declare their package at the beginning of the +file. Here is an example: + +```sds +package com.safeds.titanic +``` + +It has these syntactic elements: + +- The keyword `#!sds package`. +- The name of the package. It consists of multiple _parts_ separated by dots. Each part can be any combination of lower- + and uppercase letters, underscores, and numbers, as long as it does not start with a number. + +??? info "Name convention" + + - Use `#!sds lowerCamelCase` for all parts. + - Use the [reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) for the package + name. + +Multiple files can belong to the same package. However, within the same package the names of declarations must be +unique. diff --git a/docs/language/pipeline-language/pipelines.md b/docs/pipeline-language/pipelines.md similarity index 94% rename from docs/language/pipeline-language/pipelines.md rename to docs/pipeline-language/pipelines.md index 146a426ac..4810929e3 100644 --- a/docs/language/pipeline-language/pipelines.md +++ b/docs/pipeline-language/pipelines.md @@ -15,7 +15,7 @@ pipeline predictSpeed {} This declaration of a pipeline has the following syntactic elements: - The keyword `#!sds pipeline`. -- The name of the pipeline, here `#!sds predictSpeed`, which can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use `#!sds lowerCamelCase` for the names of pipelines. +- The name of the pipeline, here `#!sds predictSpeed`, which can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest using `#!sds lowerCamelCase` for the names of pipelines. - The body of the pipeline, which contains the [statements][statements] that should be run when the pipeline is executed. The body is delimited by curly braces. In this example, the body is empty, so running this pipeline does nothing. ### Statements diff --git a/docs/language/pipeline-language/segments.md b/docs/pipeline-language/segments.md similarity index 55% rename from docs/language/pipeline-language/segments.md rename to docs/pipeline-language/segments.md index e97284e0b..061ad2b34 100644 --- a/docs/language/pipeline-language/segments.md +++ b/docs/pipeline-language/segments.md @@ -15,11 +15,70 @@ segment loadMovieRatingsSample() {} This declaration of a segment has the following syntactic elements: - The keyword `#!sds segment`. -- The name of the segment, here `#!sds loadMovieRatingsSample`. This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use `#!sds lowerCamelCase` for the names of segments. +- The name of the segment, here `#!sds loadMovieRatingsSample`. This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest using `#!sds lowerCamelCase` for the names of segments. - The list of parameters (i.e. inputs) of the segment. This is delimited by parentheses. In the example above, the segment has no parameters. - The _body_ of the segment, which contains the [statements][statements] that should be run when the segment is [called](#calling-a-segment). The body is delimited by curly braces. In this example, the body is empty, so running this segment does nothing. -### Parameters +## Parameters + +_Parameters_ define the expected inputs of some declaration that can be [called][calls]. We refer to such declarations as _callables_. We distinguish between + +- [required parameters](#required-parameters), which must always be passed, and +- [optional parameters](#optional-parameters), which use a default value if no value is passed explicitly. + +### Required Parameters + +_Required parameters_ must always be passed when the declaration is [called][calls]. Let us look at an example: + +```sds +requiredParameter: Int +``` + +Here are the pieces of syntax: + +- The name of the parameter (here `#!sds requiredParameter`). This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use `#!sds lowerCamelCase` for the names of parameters. +- A colon. +- The [type][types] of the parameter (here `#!sds Int`). + +### Optional Parameters + +_Optional parameters_ have a default value and, thus, need not be passed as an [argument][calls] unless the default value does not fit. Here is an example: + +```sds +optionalParameter: Int = 1 +``` + +These are the syntactic elements: + +- The name of the parameter (here `#!sds optionalParameter`). This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use `#!sds lowerCamelCase` for the names of parameters. +- A colon. +- The [type][types] of the parameter (here `#!sds Int`). +- An equals sign. +- The default value of the parameter (here `#!sds 1`). This must be a constant expression, i.e. something that can be evaluated by the compiler. Particularly [calls][calls] usually do not fulfill this requirement. + +### Complete Example + +Let us now look at a full example of a [segment][segments] called `#!sds doSomething` with one [required parameter](#required-parameters) and one [optional parameter](#optional-parameters): + +```sds +segment doSomething(requiredParameter: Int, optionalParameter: Boolean = false) { + // ... +} +``` + +The interesting part is the list of parameters, which uses the following syntactic elements: + +- An opening parenthesis. +- A list of parameters, the syntax is as described above. They are separated by commas. A trailing commas is permitted. +- A closing parenthesis. + +### Restrictions + +Several restrictions apply to the order of parameters and to combinations of the various categories of parameters: + +- After an [optional parameter](#optional-parameters) all parameters must be optional. + +### Parameters Old To make a segment configurable, add [parameters][parameters] (inputs). We will first show how to [declare parameters](#parameter-declaration) and afterwards how to [refer to them](#references-to-parameters) in the body of the segment. @@ -47,23 +106,67 @@ segment loadMovieRatingsSample(nInstances: Int) { More information about references can be found in the [linked document][references]. -### Statements -In order to describe what should be done when the segment is executed, we need to add [statements][statements] to its body. The previous example in the section ["References to Parameters"](#references-to-parameters) already contained a statement - an [expression statement][expression-statements] to be precise. Here is another example, this time showing an [assignment][assignments]: +## Results + +_Results_ define the outputs of some declaration when it is [called][calls]. Here is an example: ```sds -segment loadMovieRatingsSample(nInstances: Int) { - val movieRatingsSample = loadDataset("movieRatings").sample(nInstances = 1000); +result: Int +``` + +Here is a breakdown of the syntax: + +- The name of the result (here `#!sds result`). This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use `#!sds lowerCamelCase` for the names of parameters. +- A colon. +- The [type][types] of the parameter (here `#!sds Int`). + +### Complete Example + +Let us now look at a full example of a [segment][segments] called `#!sds doSomething` with two results: + +```sds +segment doSomething() -> (result1: Int, result2: Boolean) { + // ... } ``` -More information about statements can be found in the [linked document][statements]. Note particularly, that all statements must end with a semicolon. +The interesting part is the list of results, which uses the following syntactic elements: + +- An arrow `#!sds ->`. +- An opening parenthesis. +- A list of results, the syntax is as described above. They are separated by commas. A trailing commas is permitted. +- A closing parenthesis. + +### Shorthand Version: Single Result + +In case that the callable produces only a single result, we can omit the parentheses. The following two declarations are, hence, equivalent: + +```sds +segment doSomething1() -> (result: Int) {} +``` + +```sds +segment doSomething2() -> result: Int {} +``` + +### Shorthand Version: No Results + +In case that the callable produces no results, we can usually omit the entire results list. The following two declarations are, hence equivalent: + +```sds +segment doSomething1() -> () {} +``` + +```sds +segment doSomething2() {} +``` -### Results +The notable exception are [callable types][callable-types], where the result list must always be specified even when it is empty. [Results][results] (outputs) are used to return values that are produced inside the segment back to the caller. First, we show how to [declare the available results](#result-declaration) of the segment and then how to [assign a value to them](#assigning-to-results). -#### Result Declaration +### Result Declaration As with [parameters](#parameters) we first need to declare the available results in the headed. This tells [callers](#calling-a-segment) that they can use these results and reminds us to [assign a value to them](#assigning-to-results) in the body of the segment. Let's look at an example: @@ -77,7 +180,7 @@ We added two results to the segment: The first one is called `#!sds features` an More information about the declaration of results can be found in the [linked document][results]. -#### Assigning to Results +### Assigning to Results Currently, the program will not compile since we never assigned a value to these results. This can be done with an [assignment][assignments] and the `#!sds yield` keyword: @@ -99,6 +202,18 @@ In the assignment beginning with `#!sds yield features =` we specify the value o The order of the [result declarations](#result-declaration) does not need to match the order of assignment. However, **each result must be assigned exactly once**. Note that unlike the `#!sds return` in other programming languages, `#!sds yield` does not stop the execution of the segment, which allows [assignments][assignments] to different results to be split across multiple [statements][statements]. +## Statements + +In order to describe what should be done when the segment is executed, we need to add [statements][statements] to its body. The previous example in the section ["References to Parameters"](#references-to-parameters) already contained a statement - an [expression statement][expression-statements] to be precise. Here is another example, this time showing an [assignment][assignments]: + +```sds +segment loadMovieRatingsSample(nInstances: Int) { + val movieRatingsSample = loadDataset("movieRatings").sample(nInstances = 1000); +} +``` + +More information about statements can be found in the [linked document][statements]. Note particularly, that all statements must end with a semicolon. + ## Visibility By default, a segment can be [imported][imports] in any other file and reused there. We say they have public visibility. However, it is possible to restrict the visibility of a segment with modifiers: @@ -121,11 +236,11 @@ val features, val target = loadMovieRatingsSample(nInstances = 1000); More information about calls can be found in the [linked document][calls]. -[imports]: ../common/imports.md -[parameters]: ../common/parameters.md -[results]: ../common/results.md -[types]: ../common/types.md -[packages]: ../common/packages.md +[imports]: imports.md +[parameters]: segments.md#parameters +[results]: segments.md#results +[types]: types.md +[packages]: packages.md [statements]: statements.md [assignments]: statements.md#assignments [assignments-to-placeholders]: statements.md#declaring-placeholders @@ -134,3 +249,17 @@ More information about calls can be found in the [linked document][calls]. [lambdas]: expressions.md#lambdas [references]: expressions.md#references [pipelines]: pipelines.md + +[stub-language]: ../stub-language/README.md +[callable-types]: types.md#callable-types + +[segments]: ../pipeline-language/segments.md +[calls]: ../pipeline-language/expressions.md#calls +[stub-language]: ../stub-language/README.md +[int-literals]: ../pipeline-language/expressions.md#int-literals +[float-literals]: ../pipeline-language/expressions.md#float-literals +[string-literals]: ../pipeline-language/expressions.md#string-literals +[boolean-literals]: ../pipeline-language/expressions.md#boolean-literals +[null-literals]: ../pipeline-language/expressions.md#null-literal +[python-keyword-only]: https://peps.python.org/pep-3102/ +[python-positional-only]: https://peps.python.org/pep-0570/ diff --git a/docs/language/pipeline-language/statements.md b/docs/pipeline-language/statements.md similarity index 97% rename from docs/language/pipeline-language/statements.md rename to docs/pipeline-language/statements.md index 4cec933bb..c9e43ce40 100644 --- a/docs/language/pipeline-language/statements.md +++ b/docs/pipeline-language/statements.md @@ -42,7 +42,7 @@ val one = 1; This assignment to a placeholder has the following syntactic elements: - The keyword `#!sds val`, which indicates that we want to declare a placeholder. -- The name of the placeholder, here `#!sds one`. This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use `#!sds lowerCamelCase` for the names of placeholders. +- The name of the placeholder, here `#!sds one`. This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest using `#!sds lowerCamelCase` for the names of placeholders. - An `#!sds =` sign. - The expression to evaluate (right-hand side). - A semicolon at the end. @@ -95,7 +95,7 @@ Similar syntax is used to yield results of [block lambdas][block-lambdas]. The d The assignment here has the following syntactic elements: - The keyword `#!sds yield`, which indicates that we want to declare a result. -- The name of the result, here `#!sds result`. This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use `#!sds lowerCamelCase` for the names of results. +- The name of the result, here `#!sds result`. This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest using `#!sds lowerCamelCase` for the names of results. - An `#!sds =` sign. - The expression to evaluate (right-hand side). - A semicolon at the end. @@ -135,7 +135,7 @@ Let us sum up the complete syntax of an assignment: Assignment happens by index, so the first result is assigned to the first assignee, the second result is assigned to the second assignee, and so forth. If there are more results than assignees, any trailing results are implicitly ignored. -[results]: ../common/results.md +[results]: segments.md#results [stub-language]: ../stub-language/README.md [pipeline-language]: README.md [expressions]: expressions.md diff --git a/docs/pipeline-language/types.md b/docs/pipeline-language/types.md new file mode 100644 index 000000000..001dc6dfe --- /dev/null +++ b/docs/pipeline-language/types.md @@ -0,0 +1,314 @@ +# Types + +Types describe the values that a declaration can accept. Safe-DS has various categories of types, which are explained in this document. + +## Categories of Types + +### Named Types + +_Named types_ either denote that a declaration must be an instance of a [class][classes] or one of its [subclasses][subclassing], or an instance of a [variant][variants] of an [enum][enums]. In either case the syntax of the type is just the name of the [class][classes] or the [enum][enums] respectively. + +#### Class Types + +A declaration with a _class type_ must be an instance of a [class][classes] or one of its [subclasses][subclassing]. Let us use the following [classes][classes] for our example: + +```sds +class SomeClass + +class SomeSubclass sub SomeClass +``` + +To denote that a declaration accepts instances of `#!sds SomeClass` and its [subclass][subclassing] `#!sds SomeSubclass`, we write the name of the class as the type: + +```sds +SomeClass +``` + +##### Nullable Class Types + +The value `#!sds null` (see [null][null-literal]) deserves special treatment since it is not possible to operate on it in the same manner as on proper instances of a [class][classes]. For this reason `#!sds null` cannot be assigned to declarations with class types such as `#!sds SomeClass`. + +To specifically allow `#!sds null` as a value, simply add a question mark to the named type: + +```sds +SomeClass? +``` + +#### Enum Types + +A declaration with an _enum type_ must be one of the [variants][variants] of the [enum][enums]. Let us use the following [enum][enums] for our example: + +```sds +enum SomeEnum { + SomeEnumVariant + SomeOtherEnumVariant(count: Int) +} +``` + +To denote that a declaration accepts instances of any [variant][variants] of `#!sds SomeEnum`, use the name of the enum as the type: + +```sds +SomeEnum +``` + +This type expects either the value `#!sds SomeEnum.SomeEnumVariant` (see [member access][member-accesses]) or anything constructed from the [variant][variants] `#!sds SomeOtherEnumVariant` such as `#!sds SomeEnum.SomeOtherEnumVariant(3)`. + +#### Type Arguments + +**Note:** This is an advanced section. Feel free to skip it initially. + +If a declaration has [type parameters][type-parameters] we need to assign all of them when we use the declaration as a named type. This assignment happens in the form of _type arguments_. We explain this using the following declaration: + +```sds +class SomeSpecialList +``` + +When we use this [class][classes] as a named type, we need to specify the value for the [type parameter][type-parameters] `#!sds T`, which is supposed to denote the type of the elements in the list.Similar to [calls][calls], we can either use _positional type arguments_ or _named type arguments_. + +In the case of positional type arguments, they are mapped to [type parameters][type-parameters] by position, i.e. the first type argument is assigned to the first [type parameter][type-parameters], the second type argument is assigned to the second [type parameter][type-parameters] and so forth. + +If a positional type argument is used, we just write down its value, which is a [type projection](#type-projection). + +For example, if we expect a list of integers, we could use the following type: + +```sds +SomeSpecialList +``` + +Let us break down the syntax: + +- The usual named type (here `#!sds SomeSpecialList`). +- Opening angle bracket. +- A positional type argument (here `#!sds Int`). +- A closing angle bracket. + +When a named type argument is used, we explicitly specify the [type parameter][type-parameters] that we want to assign. This allows us to specify them in any order. It can also improve the clarity of the code since the meaning of the type argument becomes more apparent. Here is the type for our list of integers when a named argument is used: + +```sds +SomeSpecialList +``` + +These are the syntactic elements: + +- The usual named type (here `#!sds SomeSpecialList`). +- Opening angle bracket. +- A named type argument (here `#!sds T = Int`). This in turn consists of + - The name of the [type parameter][type-parameters] (here `#!sds T`) + - An equals sign. + - The value of the type argument, which is still a [type projection](#type-projection). +- A closing angle bracket. + +Within a list of type arguments both positional and named type arguments can be used. However, after the first named type arguments all type arguments must be named. + +Let us finally look at how multiple type arguments are passed. For this we use the following declaration: + +```sds +class SomeSpecialMap +``` + +This [class][classes] has to [type parameters][type-parameters], namely `#!sds K` and `#!sds V`, which must both be set if we use this [class][classes] as a named type. + +Here is a valid use: + +```sds +SomeSpecialMap +``` + +We will again go over the syntax: + +- The usual named type (here `#!sds SomeSpecialMap`). +- An opening angle bracket. +- The list of type arguments. Each element is either a positional or a named type argument (see above). Individual elements are separated by commas. A trailing comma is allowed +- A closing angle bracket. + +We will now look at the values that we can pass within type arguments. + +##### Type Projection + +The most basic case is that we pass a concrete type as the value. We have already seen this in the example above where we constructed the type for a list of integers: + +```sds +SomeSpecialList +``` + +The value of the type argument is just another named type (here `#!sds Int`). + +### Member Types + +A member type is essentially the same as a [named type](#named-types) with the difference that the declaration we refer to is nested inside [classes][classes] or [enums][enums]. + +#### Class Member Types + +We begin with nested classes and use these declarations to illustrate the concept: + +```sds +class SomeOuterClass { + class SomeInnerClass +} +``` + +To specify that a declaration accepts instances of `#!sds SomeInnerClass` or its [subclasses][subclassing], use the following member type: + +```sds +SomeOuterClass.SomeInnerClass +``` + +This has the following syntactic elements: + +- Name of the outer [class][classes] (here `#!sds SomeOuterClass`). +- A dot. +- Name of the inner [class][classes] (here `#!sds SomeInnerClass`). + +Classes can be nested multiple levels deep. In this case, use a member access for each level. Let us use the following declarations to explain this: + +```sds +class SomeOuterClass { + class SomeMiddleClass { + class SomeInnerClass + } +} +``` + +To specify that a declaration accepts instances of `#!sds SomeInnerClass`, or its [subclasses][subclassing], use the following member type: + +```sds +SomeOuterClass.SomeMiddleClass.SomeInnerClass +``` + +If any referenced class has [type parameters][type-parameters] these must be specified by [type arguments](#type-arguments). For this we use these declarations: + +```sds +class SomeOuterClass { + class SomeInnerClass +} +``` + +To specify that a declaration accepts instances of `#!sds SomeInnerClass` where all type parameters are set to `#!sds Int`, or its [subclasses][subclassing], use the following member type: + +```sds +SomeOuterClass.SomeInnerClass +``` + +Finally, as with [named types](#named-types), `#!sds null` is not an allowed value by default. To allow it, add a question mark at the end of the member type. This can be used independently from [type arguments](#type-arguments): + +```sds +SomeOuterClass.SomeInnerClass? +``` + +#### Enum Variant Types + +Member types are also used to specify that a declaration is an instance of a single [variant][variants] of an [enum][enums]. For this, we use the following declarations: + +```sds +enum SomeEnum { + SomeEnumVariant(count: Int), + SomeOtherEnumVariant +} +``` + +To allow only instances of the [variant][variants] `#!sds SomeEnumVariant`, use the following member type: + +```sds +SomeEnum.SomeEnumVariant +``` + +Let us take apart the syntax: + +- The name of the [enum][enums] (here `#!sds SomeEnum`). +- A dot. +- The name of the [enum variant][variants] (here `#!sds SomeEnumVariant`). + +Identical to [class member types](#class-member-types), all [type parameters][type-parameters] of the [enum variant][variants] must be assigned by [type arguments](#type-arguments). We use these declarations to explain the concept: + +```sds +enum SomeEnum { + SomeEnumVariant(value: T), + SomeOtherEnumVariant +} +``` + +To now allow only instances of the [variant][variants] `#!sds SomeEnumVariant` with `#!sds Int` values, use the following member type: + +```sds +SomeEnum.SomeEnumVariant +``` + +### Callable Types + +A _callable type_ denotes that only values that can be [called][calls] are accepted. This includes: + +- [class constructors][class-constructors] +- [constructors of enum variants][enum-variant-constructors] +- [methods][methods] +- [global functions][global-functions] +- [segments][segments] +- [lambdas][lambdas] + +Additionally, a callable types specifies the names and types of parameters and results. Here is the most basic callable type that expects neither parameters nor results: + +```sds +() -> () +``` + +Let us break down the syntax: + +- A pair of parentheses, which is the list of expected [parameters][parameters]. +- An arrow `#!sds ->`. +- A pair of parentheses, which is the list of expected [results][results]. + +We can now add some expected [parameters][parameters]: + +```sds +(a: Int, b: Int) -> () +``` + +These are the syntactic elements: + +- [Parameters][parameters] are written in the first pair of parentheses. +- For each [parameter][parameters], specify: + - Its name. + - A colon. + - Its type. +- Separate [parameters][parameters] by commas. A trailing comma is permitted. + +Finally, we can add some expected [results][results]: + +```sds +(a: Int, b: Int) -> (r: Int, s: Int) +``` + +The syntax is reminiscent of the notation for [parameters][parameters]: + +- [Results][results] are written in the second pair of parentheses. +- For each [result][results], specify: + - Its name. + - A colon. + - Its type. +- Separate [result][results] by commas. A trailing comma is permitted. + +If exactly one result is expected, the surrounding parentheses may be also removed: + +```sds +(a: Int, b: Int) -> r: Int +``` + +[parameters]: segments.md#parameters +[results]: segments.md#results +[stub-language]: ../stub-language/README.md +[classes]: ../stub-language/classes.md +[subclassing]: ../stub-language/classes.md#subclassing +[enums]: ../stub-language/enumerations.md +[variants]: ../stub-language/enumerations.md#enum-variants +[type-parameters]: ../stub-language/type-parameters.md +[type-parameter-bounds]: ../stub-language/type-parameters.md#bounds +[class-constructors]: ../stub-language/classes.md +[enum-variant-constructors]: ../stub-language/enumerations.md#constructors +[methods]: ../stub-language/classes.md#defining-methods +[global-functions]: ../stub-language/global-functions.md +[member-accesses]: ../pipeline-language/expressions.md#member-access-of-enum-variants +[null-literal]: ../pipeline-language/expressions.md#sds-null-literal +[calls]: ../pipeline-language/expressions.md#calls +[segments]: ../pipeline-language/segments.md +[lambdas]: ../pipeline-language/expressions.md#lambdas +[mypy]: http://mypy-lang.org/ +[type-hints]: https://docs.python.org/3/library/typing.html diff --git a/docs/poetry.lock b/docs/poetry.lock index 2cf56ee8a..d86424f5d 100644 --- a/docs/poetry.lock +++ b/docs/poetry.lock @@ -533,7 +533,6 @@ files = [ {file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"}, {file = "PyYAML-6.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:855fb52b0dc35af121542a76b9a84f8d1cd886ea97c84703eaa6d88e37a2ad28"}, {file = "PyYAML-6.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40df9b996c2b73138957fe23a16a4f0ba614f4c0efce1e9406a184b6d07fa3a9"}, - {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a08c6f0fe150303c1c6b71ebcd7213c2858041a7e01975da3a99aed1e7a378ef"}, {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c22bec3fbe2524cde73d7ada88f6566758a8f7227bfbf93a408a9d86bcc12a0"}, {file = "PyYAML-6.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8d4e9c88387b0f5c7d5f281e55304de64cf7f9c0021a3525bd3b1c542da3b0e4"}, {file = "PyYAML-6.0.1-cp312-cp312-win32.whl", hash = "sha256:d483d2cdf104e7c9fa60c544d92981f12ad66a457afae824d146093b8c294c54"}, diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 438045049..79e7eef96 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -5,18 +5,18 @@ description = "Documentation for the Safe-DS DSL" authors = ["Lars Reimann "] classifiers = ["Private :: Do not Upload"] packages = [ - { include = "safe_ds_lexer", from = "lexer"}, + { include = "safe_ds_lexer", from = "src/lexer"}, ] [tool.poetry.dependencies] python = "^3.11" mkdocs = "^1.5.3" +mkdocs-autorefs = "^1.0.1" mkdocs-glightbox = "^0.3.7" mkdocs-literate-nav = "^0.6.1" mkdocs-material = "^9.5.16" mkdocs-same-dir = "^0.1.3" pygments = "^2.17.2" -mkdocs-autorefs = "^1.0.1" [tool.poetry.plugins."pygments.lexers"] sds = "safe_ds_lexer:SafeDsLexer" diff --git a/docs/javascript/mathjax.js b/docs/src/javascript/mathjax.js similarity index 100% rename from docs/javascript/mathjax.js rename to docs/src/javascript/mathjax.js diff --git a/docs/lexer/safe_ds_lexer/__init__.py b/docs/src/lexer/safe_ds_lexer/__init__.py similarity index 100% rename from docs/lexer/safe_ds_lexer/__init__.py rename to docs/src/lexer/safe_ds_lexer/__init__.py diff --git a/docs/lexer/safe_ds_lexer/_safe_ds_lexer.py b/docs/src/lexer/safe_ds_lexer/_safe_ds_lexer.py similarity index 100% rename from docs/lexer/safe_ds_lexer/_safe_ds_lexer.py rename to docs/src/lexer/safe_ds_lexer/_safe_ds_lexer.py diff --git a/docs/stylesheets/extra.css b/docs/src/stylesheets/extra.css similarity index 100% rename from docs/stylesheets/extra.css rename to docs/src/stylesheets/extra.css diff --git a/docs/language/stub-language/README.md b/docs/stub-language/README.md similarity index 92% rename from docs/language/stub-language/README.md rename to docs/stub-language/README.md index 6040fd5e9..e4bce187c 100644 --- a/docs/language/stub-language/README.md +++ b/docs/stub-language/README.md @@ -12,10 +12,10 @@ The stub language is the part of the Safe-DS DSL that is used to integrate funct Files that use the stub language must have the extension `.sdsstub`. -[packages]: ../common/packages.md -[imports]: ../common/imports.md +[packages]: packages.md +[imports]: imports.md [classes]: classes.md [global-functions]: global-functions.md [enumerations]: enumerations.md [annotations]: annotations.md -[comments]: ../common/comments.md +[comments]: comments.md diff --git a/docs/language/stub-language/annotations.md b/docs/stub-language/annotations.md similarity index 98% rename from docs/language/stub-language/annotations.md rename to docs/stub-language/annotations.md index 8b5d0aef8..a9f27f9c0 100644 --- a/docs/language/stub-language/annotations.md +++ b/docs/stub-language/annotations.md @@ -92,15 +92,15 @@ The package `#!sds safeds.lang` contains several annotations that are processed - [`Target`][safeds.lang.Target], which can restrict the possible targets of an annotation, and - [`Repeatable`][safeds.lang.Repeatable], which allows an annotation to be called multiple times on the same declaration. -[parameters]: ../common/parameters.md -[types]: ../common/types.md +[parameters]: parameters.md +[types]: types.md [attributes]: classes.md#defining-attributes [classes]: classes.md#defining-classes [enums]: enumerations.md#declaring-an-enumeration [enum-variants]: enumerations.md#enum-variants [global-functions]: global-functions.md [methods]: classes.md#defining-methods -[results]: ../common/parameters.md +[results]: parameters.md [segments]: ../pipeline-language/segments.md [type-parameters]: type-parameters.md [pipelines]: ../pipeline-language/pipelines.md diff --git a/docs/language/stub-language/classes.md b/docs/stub-language/classes.md similarity index 100% rename from docs/language/stub-language/classes.md rename to docs/stub-language/classes.md diff --git a/docs/language/common/comments.md b/docs/stub-language/comments.md similarity index 96% rename from docs/language/common/comments.md rename to docs/stub-language/comments.md index 9a150b958..25afca9f8 100644 --- a/docs/language/common/comments.md +++ b/docs/stub-language/comments.md @@ -171,9 +171,9 @@ fun sum(a: Int, b: Int): sum: Int the [`@param`](#param), [`@result`](#result), and [`@typeParam`](#typeparam) tags on the containing declaration, respectively. -[class]: ../stub-language/classes.md -[enum]: ../stub-language/enumerations.md -[enum-variant]: ../stub-language/enumerations.md#enum-variants +[class]: classes.md +[enum]: enumerations.md +[enum-variant]: enumerations.md#enum-variants [parameter]: parameters.md [result]: results.md -[type-parameter]: ../stub-language/type-parameters.md +[type-parameter]: type-parameters.md diff --git a/docs/language/stub-language/enumerations.md b/docs/stub-language/enumerations.md similarity index 100% rename from docs/language/stub-language/enumerations.md rename to docs/stub-language/enumerations.md diff --git a/docs/language/stub-language/global-functions.md b/docs/stub-language/global-functions.md similarity index 100% rename from docs/language/stub-language/global-functions.md rename to docs/stub-language/global-functions.md diff --git a/docs/stub-language/imports.md b/docs/stub-language/imports.md new file mode 100644 index 000000000..991efc2fb --- /dev/null +++ b/docs/stub-language/imports.md @@ -0,0 +1,92 @@ +# Imports + +By default, only declarations in the same package as the current file or in a package whose name starts with `safeds` [package][packages] are accessible. All other declarations must be imported first. + +Safe-DS has two kinds of imports, namely a _qualified import_, which imports a single declaration, and a _wildcard import_, which imports everything in a [package][packages]. + +## Qualified Imports + +A _qualified import_ makes a single declaration available. Here is an example that imports the [class][classes] `DecisionTree` in the [package][packages] `safeds.model.regression`: + +```sds +from safeds.model.regression import DecisionTree +``` + +The syntax consists of the following parts: + +- The keyword `from`. +- The name of the [package][packages] that contains the declaration (here `safeds.model.regression`). +- The keyword `import`. +- The name of the declaration (i.e. `DecisionTree`). + +Once the declaration is imported, we can refer to it by its name. Here is, for example, a [call][calls] to the constructor of the `DecisionTree` class: + +```sds +DecisionTree() +``` + +Multiple declarations can be imported from the same package in a single import statement by separating them with commas: + +```sds +from safeds.model.regression import DecisionTree, RandomForest +``` + +### Qualified Imports with Alias + +Sometimes the name of the imported declaration can conflict with other declarations that are imported or that are contained in the importing file. To counter this, declarations can be imported under an alias: + +```sds +from safeds.model.regression import DecisionTree as StdlibDecisionTree +``` + +Let us take apart the syntax: + +- The keyword `#!sds from`. +- The name of the [package][packages] that contains the declaration (here `safeds.model.regression`). +- The keyword `#!sds import`. +- The name of the declaration (i.e. `DecisionTree`). +- The keyword `#!sds as`. +- The alias to use (here `StdlibDecisionTree`). This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. + +Afterwards, the declaration can **only** be accessed using the alias. The next example shows how to create a new instance of the class now by invoking its constructor: + +```sds +StdlibDecisionTree() +``` + +Multiple declarations can be imported with or without an alias in a single import statement by separating them with commas: + +```sds +from safeds.model.regression import DecisionTree as StdlibDecisionTree, RandomForest +``` + +## Wildcard Imports + +We can also import all declarations in a [package][packages] with a single import. While this saves some typing, it also increases the likelihood of name conflicts and can make it harder for readers of the code to determine where a declaration comes from. Therefore, this should be used with caution. + +Nevertheless, let us look at an example, which imports all declarations from the [package][packages] `#!sds safeds.model.regression`: + +```sds +from safeds.model.regression import * +``` + +Here is the breakdown of the syntax: + +- The keyword `#!sds from`. +- The name of the [package][packages] to import (here `#!sds safeds.model.regression`). +- The keyword `#!sds import`. +- A star. + +Afterward, we can again access declarations by their simple name, such as the [class][classes] `#!sds DecisionTree`: + +```sds +DecisionTree() +``` + +[Aliases](#qualified-imports-with-alias) cannot be used together with wildcard imports. + +Note that declarations in subpackages, i.e. packages that have a different name but the same prefix as the imported one, are **not** imported. Therefore, if we would instead write `#!sds from safeds.model import *`, we could no longer access the [class][classes] `#!sds DecisionTree`. + +[classes]: classes.md +[packages]: packages.md +[calls]: ../pipeline-language/expressions.md#calls diff --git a/docs/language/common/packages.md b/docs/stub-language/packages.md similarity index 98% rename from docs/language/common/packages.md rename to docs/stub-language/packages.md index 83f930ffa..df87a241b 100644 --- a/docs/language/common/packages.md +++ b/docs/stub-language/packages.md @@ -126,9 +126,9 @@ from safeds.model.regression import DecisionTree It is important to note that the `#!sds @PythonModule` annotation only affects the one Safe-DS file that contains it rather than the entire Safe-DS package. This allows different Safe-DS files in the same package to point to different [Python modules][python-modules]. -[stub-language]: ../stub-language/README.md -[annotations]: ../stub-language/annotations.md -[annotation-calls]: ../stub-language/annotations.md#calling-an-annotation +[stub-language]: README.md +[annotations]: annotations.md +[annotation-calls]: annotations.md#calling-an-annotation [imports]: imports.md [string-literals]: ../pipeline-language/expressions.md#string-literals [python-modules]: https://docs.python.org/3/tutorial/modules.html#modules diff --git a/docs/language/common/parameters.md b/docs/stub-language/parameters.md similarity index 98% rename from docs/language/common/parameters.md rename to docs/stub-language/parameters.md index fba0cf21e..6ac626a42 100644 --- a/docs/language/common/parameters.md +++ b/docs/stub-language/parameters.md @@ -147,11 +147,11 @@ Most commonly, default values in Python are literals, since default values are o [types-python]: types.md#corresponding-python-code [segments]: ../pipeline-language/segments.md [calls]: ../pipeline-language/expressions.md#calls -[stub-language]: ../stub-language/README.md +[stub-language]: README.md [int-literals]: ../pipeline-language/expressions.md#int-literals [float-literals]: ../pipeline-language/expressions.md#float-literals [string-literals]: ../pipeline-language/expressions.md#string-literals [boolean-literals]: ../pipeline-language/expressions.md#boolean-literals -[null-literals]: ../pipeline-language/expressions.md#null-literal +[null-literals]: ../pipeline-language/expressions.md#sds-null-literal [python-keyword-only]: https://peps.python.org/pep-3102/ [python-positional-only]: https://peps.python.org/pep-0570/ diff --git a/docs/language/common/results.md b/docs/stub-language/results.md similarity index 98% rename from docs/language/common/results.md rename to docs/stub-language/results.md index 395c7d451..9cf4bc856 100644 --- a/docs/language/common/results.md +++ b/docs/stub-language/results.md @@ -63,7 +63,7 @@ Results must be ordered the same way in Python as they are in Safe-DS. Moreover, Since Python results do not have a name, the names of Safe-DS results can be arbitrary. Naturally, a name should be chosen that captures the purpose of the result. -[stub-language]: ../stub-language/README.md +[stub-language]: README.md [types]: types.md [types-python]: types.md#corresponding-python-code [callable-types]: types.md#callable-types diff --git a/docs/language/stub-language/type-parameters.md b/docs/stub-language/type-parameters.md similarity index 100% rename from docs/language/stub-language/type-parameters.md rename to docs/stub-language/type-parameters.md diff --git a/docs/language/common/types.md b/docs/stub-language/types.md similarity index 95% rename from docs/language/common/types.md rename to docs/stub-language/types.md index 2414695ad..c2cd66d17 100644 --- a/docs/language/common/types.md +++ b/docs/stub-language/types.md @@ -372,20 +372,20 @@ Getting the ` depends on the number of results. If there is only a [variance]: variance.md [parameters]: parameters.md [results]: results.md -[stub-language]: ../stub-language/README.md -[classes]: ../stub-language/classes.md -[subclassing]: ../stub-language/classes.md#subclassing -[enums]: ../stub-language/enumerations.md -[variants]: ../stub-language/enumerations.md#enum-variants -[type-parameters]: ../stub-language/type-parameters.md -[type-parameter-bounds]: ../stub-language/type-parameters.md#bounds -[declaration-site-variance]: ../stub-language/type-parameters.md#declaration-site-variance -[class-constructors]: ../stub-language/classes.md -[enum-variant-constructors]: ../stub-language/enumerations.md#constructors -[methods]: ../stub-language/classes.md#defining-methods -[global-functions]: ../stub-language/global-functions.md +[stub-language]: README.md +[classes]: classes.md +[subclassing]: classes.md#subclassing +[enums]: enumerations.md +[variants]: enumerations.md#enum-variants +[type-parameters]: type-parameters.md +[type-parameter-bounds]: type-parameters.md#bounds +[declaration-site-variance]: type-parameters.md#declaration-site-variance +[class-constructors]: classes.md +[enum-variant-constructors]: enumerations.md#constructors +[methods]: classes.md#defining-methods +[global-functions]: global-functions.md [member-accesses]: ../pipeline-language/expressions.md#member-access-of-enum-variants -[null-literal]: ../pipeline-language/expressions.md#null-literal +[null-literal]: ../pipeline-language/expressions.md#sds-null-literal [calls]: ../pipeline-language/expressions.md#calls [segments]: ../pipeline-language/segments.md [lambdas]: ../pipeline-language/expressions.md#lambdas diff --git a/docs/language/common/variance.md b/docs/stub-language/variance.md similarity index 95% rename from docs/language/common/variance.md rename to docs/stub-language/variance.md index 47ccfa9a8..a0c21ab5c 100644 --- a/docs/language/common/variance.md +++ b/docs/stub-language/variance.md @@ -77,7 +77,7 @@ The variance of a [type parameter][type-parameters] can only be declared at its [type-arguments]: types.md#type-arguments [parameters]: parameters.md [results]: results.md -[classes]: ../stub-language/classes.md -[methods]: ../stub-language/classes.md#defining-methods -[type-parameters]: ../stub-language/type-parameters.md -[declaration-site-variance]: ../stub-language/type-parameters.md#declaration-site-variance +[classes]: classes.md +[methods]: classes.md#defining-methods +[type-parameters]: type-parameters.md +[declaration-site-variance]: type-parameters.md#declaration-site-variance diff --git a/package.json b/package.json index 0a08e5542..11181140e 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,7 @@ "watch": "concurrently -n tsc,cli,lang,vscode,eda -c blue,yellow,red,green \"tsc -b tsconfig.json\" \"npm run watch -w=@safe-ds/cli\" \"npm run watch -w=@safe-ds/lang\" \"npm run watch -w=safe-ds\" \"npm run watch -w=@safe-ds/eda\"", "test": "vitest", "test-with-coverage": "vitest --coverage", - "docs:stdlib": "safe-ds document packages/safe-ds-lang/src/resources/builtins -o docs/stdlib" + "docs:api": "safe-ds document packages/safe-ds-lang/src/resources/builtins -o docs/api" }, "devDependencies": { "@lars-reimann/eslint-config-svelte": "^7.0.0", diff --git a/packages/safe-ds-vscode/README.md b/packages/safe-ds-vscode/README.md index a07a3f616..2c05ad1c7 100644 --- a/packages/safe-ds-vscode/README.md +++ b/packages/safe-ds-vscode/README.md @@ -3,18 +3,25 @@ Safely develop Data Science programs with a statically checked domain specific language (DSL) and integrated tools for data inspection. -![demo](https://github.com/Safe-DS/DSL/raw/main/docs/img/readme/demo.gif) +![demo](https://github.com/Safe-DS/DSL/raw/main/docs/img/home/demo.gif) ## 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 diff --git a/tsconfig.eslint.json b/tsconfig.eslint.json index fb7d69c87..5149f6585 100644 --- a/tsconfig.eslint.json +++ b/tsconfig.eslint.json @@ -4,7 +4,7 @@ "noEmit": true }, "include": [ - "docs/javascript/**/*", + "docs/src/javascript/**/*", "packages/safe-ds-cli/bin/cli.js", ".eslintrc.cjs", "release.config.cjs",