From 0d0379504b4476d60275a61d0da1d6e053f67ab3 Mon Sep 17 00:00:00 2001 From: Kristóf Marussy Date: Wed, 10 Apr 2024 12:48:10 +0200 Subject: refactor(docs): URL structure --- subprojects/docs/build.gradle.kts | 2 +- subprojects/docs/docusaurus.config.ts | 31 ++-- subprojects/docs/src/develop/contributing.md | 51 ++++++ subprojects/docs/src/develop/index.md | 13 ++ subprojects/docs/src/develop/javadoc.md | 42 +++++ subprojects/docs/src/docs-api/contributing.md | 51 ------ subprojects/docs/src/docs-api/index.md | 13 -- subprojects/docs/src/docs-api/javadoc.md | 42 ----- subprojects/docs/src/docs/docker.md | 175 ------------------ subprojects/docs/src/docs/index.md | 11 -- subprojects/docs/src/docs/language/_category_.yml | 10 - subprojects/docs/src/docs/language/classes.md | 14 -- subprojects/docs/src/docs/tutorials/_category_.yml | 10 - .../docs/src/docs/tutorials/file-system/fig1.png | Bin 20110 -> 0 bytes .../docs/tutorials/file-system/fig1.png.license | 3 - .../docs/src/docs/tutorials/file-system/fig2.png | Bin 44020 -> 0 bytes .../docs/tutorials/file-system/fig2.png.license | 3 - .../docs/src/docs/tutorials/file-system/fig3.png | Bin 26950 -> 0 bytes .../docs/tutorials/file-system/fig3.png.license | 3 - .../docs/src/docs/tutorials/file-system/fig4.png | Bin 38143 -> 0 bytes .../docs/tutorials/file-system/fig4.png.license | 3 - .../docs/src/docs/tutorials/file-system/index.md | 201 --------------------- subprojects/docs/src/learn/docker.md | 175 ++++++++++++++++++ subprojects/docs/src/learn/index.md | 11 ++ subprojects/docs/src/learn/language/_category_.yml | 10 + subprojects/docs/src/learn/language/classes.md | 14 ++ .../docs/src/learn/tutorials/_category_.yml | 11 ++ .../docs/src/learn/tutorials/file-system/fig1.png | Bin 0 -> 20110 bytes .../learn/tutorials/file-system/fig1.png.license | 3 + .../docs/src/learn/tutorials/file-system/fig2.png | Bin 0 -> 44020 bytes .../learn/tutorials/file-system/fig2.png.license | 3 + .../docs/src/learn/tutorials/file-system/fig3.png | Bin 0 -> 26950 bytes .../learn/tutorials/file-system/fig3.png.license | 3 + .../docs/src/learn/tutorials/file-system/fig4.png | Bin 0 -> 38143 bytes .../learn/tutorials/file-system/fig4.png.license | 3 + .../docs/src/learn/tutorials/file-system/index.md | 201 +++++++++++++++++++++ subprojects/docs/src/pages/index.tsx | 4 +- 37 files changed, 558 insertions(+), 558 deletions(-) create mode 100644 subprojects/docs/src/develop/contributing.md create mode 100644 subprojects/docs/src/develop/index.md create mode 100644 subprojects/docs/src/develop/javadoc.md delete mode 100644 subprojects/docs/src/docs-api/contributing.md delete mode 100644 subprojects/docs/src/docs-api/index.md delete mode 100644 subprojects/docs/src/docs-api/javadoc.md delete mode 100644 subprojects/docs/src/docs/docker.md delete mode 100644 subprojects/docs/src/docs/index.md delete mode 100644 subprojects/docs/src/docs/language/_category_.yml delete mode 100644 subprojects/docs/src/docs/language/classes.md delete mode 100644 subprojects/docs/src/docs/tutorials/_category_.yml delete mode 100644 subprojects/docs/src/docs/tutorials/file-system/fig1.png delete mode 100644 subprojects/docs/src/docs/tutorials/file-system/fig1.png.license delete mode 100644 subprojects/docs/src/docs/tutorials/file-system/fig2.png delete mode 100644 subprojects/docs/src/docs/tutorials/file-system/fig2.png.license delete mode 100644 subprojects/docs/src/docs/tutorials/file-system/fig3.png delete mode 100644 subprojects/docs/src/docs/tutorials/file-system/fig3.png.license delete mode 100644 subprojects/docs/src/docs/tutorials/file-system/fig4.png delete mode 100644 subprojects/docs/src/docs/tutorials/file-system/fig4.png.license delete mode 100644 subprojects/docs/src/docs/tutorials/file-system/index.md create mode 100644 subprojects/docs/src/learn/docker.md create mode 100644 subprojects/docs/src/learn/index.md create mode 100644 subprojects/docs/src/learn/language/_category_.yml create mode 100644 subprojects/docs/src/learn/language/classes.md create mode 100644 subprojects/docs/src/learn/tutorials/_category_.yml create mode 100644 subprojects/docs/src/learn/tutorials/file-system/fig1.png create mode 100644 subprojects/docs/src/learn/tutorials/file-system/fig1.png.license create mode 100644 subprojects/docs/src/learn/tutorials/file-system/fig2.png create mode 100644 subprojects/docs/src/learn/tutorials/file-system/fig2.png.license create mode 100644 subprojects/docs/src/learn/tutorials/file-system/fig3.png create mode 100644 subprojects/docs/src/learn/tutorials/file-system/fig3.png.license create mode 100644 subprojects/docs/src/learn/tutorials/file-system/fig4.png create mode 100644 subprojects/docs/src/learn/tutorials/file-system/fig4.png.license create mode 100644 subprojects/docs/src/learn/tutorials/file-system/index.md (limited to 'subprojects') diff --git a/subprojects/docs/build.gradle.kts b/subprojects/docs/build.gradle.kts index 0c80e23a..e559ed3e 100644 --- a/subprojects/docs/build.gradle.kts +++ b/subprojects/docs/build.gradle.kts @@ -50,7 +50,7 @@ val docusaurusOutputDir = layout.buildDirectory.dir("docusaurus") val javadocsDir = layout.buildDirectory.dir("javadocs") -val javadocsDocsDir = javadocsDir.map { root -> root.dir("api/javadoc") } +val javadocsDocsDir = javadocsDir.map { root -> root.dir("develop/javadoc") } val configFiles: FileCollection = files( rootProject.file("yarn.lock"), diff --git a/subprojects/docs/docusaurus.config.ts b/subprojects/docs/docusaurus.config.ts index 47bf605e..00ef21b5 100644 --- a/subprojects/docs/docusaurus.config.ts +++ b/subprojects/docs/docusaurus.config.ts @@ -21,7 +21,6 @@ const markdownOptions = { export default { title: 'Refinery', tagline: 'An efficient graph solver for generating well-formed models', - titleDelimiter: '⚗️', url: 'https://refinery.tools', baseUrl: '/', baseUrlIssueBanner: false, @@ -31,9 +30,9 @@ export default { [ '@docusaurus/plugin-content-docs', { - id: 'docs', - path: 'src/docs', - routeBasePath: '/docs', + id: 'learn', + path: 'src/learn', + routeBasePath: '/learn', sidebarPath: undefined, ...markdownOptions, } satisfies DocsOptions, @@ -41,9 +40,9 @@ export default { [ '@docusaurus/plugin-content-docs', { - id: 'api', - path: 'src/docs-api', - routeBasePath: '/api', + id: 'develop', + path: 'src/develop', + routeBasePath: '/develop', sidebarPath: undefined, ...markdownOptions, } satisfies DocsOptions, @@ -81,11 +80,11 @@ export default { items: [ { label: 'Learn', - to: '/docs', + to: '/learn', }, { label: 'Develop', - to: '/api', + to: '/develop', }, { label: 'GitHub', @@ -107,19 +106,19 @@ export default { items: [ { label: 'Introduction', - to: '/docs', + to: '/learn', }, { label: 'Tutorials', - to: '/docs/category/tutorials', + to: '/learn/tutorials', }, { label: 'Langauge reference', - to: '/docs/category/language', + to: '/learn/language', }, { label: 'Run in Docker', - to: '/docs/docker', + to: '/learn/docker', }, ], }, @@ -128,15 +127,15 @@ export default { items: [ { label: 'Programming guide', - to: '/api', + to: '/develop', }, { label: 'Contributing', - to: '/api/contributing', + to: '/develop/contributing', }, { label: 'Javadoc', - to: '/api/javadoc', + to: '/develop/javadoc', }, ], }, diff --git a/subprojects/docs/src/develop/contributing.md b/subprojects/docs/src/develop/contributing.md new file mode 100644 index 00000000..4a135b81 --- /dev/null +++ b/subprojects/docs/src/develop/contributing.md @@ -0,0 +1,51 @@ +--- +SPDX-FileCopyrightText: 2021-2023 The Refinery Authors +SPDX-License-Identifier: EPL-2.0 +sidebar_position: 1 +sidebar_label: Contributing +--- + +# Contributing to Refinery + +## Setting up the development environment + +### With IntelliJ IDEA + +We prefer IntelliJ IDEA as a development environment. +No special preparations should be necessary for importing the project as a Gradle project into IDEA. + +However, you will need Eclipse to edit Xtext (`*.xtext`) and MWE2 (`*.mwe2`) files and Ecore class diagrams (`*.aird`, `*.ecore`, `*.genmodel`). +If you do not plan on making changes to such files, feel free to skip the Eclipse installation steps below. + +### With Eclipse IDE + +1. Download and install a _Java 21_ compatible JDK. For Windows, prefer OpenJDK builds from [Adoptium](https://adoptium.net/). + +2. Download and extract the [Eclipse IDE for Java and DSL Developers 2023-12](https://www.eclipse.org/downloads/packages/release/2023-12/r/eclipse-ide-java-and-dsl-developers) package. + +3. Launch Eclipse and create a new workspace. + +4. Open _Help > Eclipse Marketplace_ and install the following software: + * _EclEmma Java Code Coverage_ + * _EcoreTools : Ecore Diagram Editor_ + * _Sirius_ (ignore the warning during installation about the solution _Sirius_ not being available) + * _SonarLint_ + +5. Open _Window > Preferences_ and set the following preferences: + * _General > Workspace > Text file encoding_ should be _UTF-8_. + * _General > Workspace > New text file line delimiter_ should be _Unix_. + * Add the JDK 21 to _Java > Installed JREs_. + * Make sure JDK 21 is selected for _JavaSE-21_ at _Java > Installed JREs > Execution Environments_. + * Set _Gradle > Java home_ to the `JAVA_HOME` directory (the directory which contains the `bin` directory) of JDK 21. Here, Buildship will show a yellow warning sign, which can be safely ignored. + * Set _Java > Compiler > JDK Compliance > Compiler compliance level_ to _21_. + +6. Clone the project Git repository but do not import it into Eclipse yet. + +7. Open a new terminal an run `./gradlew prepareEclipse` (`.\gradlew prepareEclipse` on Windows) in the cloned repository. + * This should complete without any compilation errors. + * If you get any errors about the JVM version, check whether the `JAVA_HOME` environment variable is set to the location of JDK. You can query the variable with `echo $JAVA_HOME` on Linux and `echo $Env:JAVA_HOME` in PowerShell on Windows. To set it, use `export JAVA_HOME=/java/path/here` or `$Env:JAVA_HOME="C:\java\path\here"`, respectively. + * If the build fails with a `Host name must not be empty` error, you [might need to remove the empty proxy configuration from your global `gradle.properties` file](https://stackoverflow.com/a/62128323). + +8. Select _File > Import... > Gradle > Existing Gradle Project_ and import the cloned repository in Eclipse. + * Make sure to select the root of the repository (containing this file) as the _Project root directory_ and that the _Gradle distribution_ is _Gradle wrapper_. + * If you have previously imported the project into Eclipse, this step will likely fail. In that case, you should remove the projects from Eclipse, run `git clean -fxd` in the repository, and start over from step 8. diff --git a/subprojects/docs/src/develop/index.md b/subprojects/docs/src/develop/index.md new file mode 100644 index 00000000..4537889e --- /dev/null +++ b/subprojects/docs/src/develop/index.md @@ -0,0 +1,13 @@ +--- +SPDX-FileCopyrightText: 2024 The Refinery Authors +SPDX-License-Identifier: EPL-2.0 +sidebar_position: 0 +--- + +# Programming guide + +:::warning + +Under construction + +::: diff --git a/subprojects/docs/src/develop/javadoc.md b/subprojects/docs/src/develop/javadoc.md new file mode 100644 index 00000000..225e9de0 --- /dev/null +++ b/subprojects/docs/src/develop/javadoc.md @@ -0,0 +1,42 @@ +--- +SPDX-FileCopyrightText: 2024 The Refinery Authors +SPDX-License-Identifier: EPL-2.0 +description: API documentation for Refinery components automatically generated by Javadoc +sidebar_position: 999 +--- + +# Javadoc + +Here you can find API documentation for Refinery components automatically generated by Javadoc. We recommend reading the [Programming guide](/develop) first to understand how to use these components. + +# Refinery + +* [`tools.refinery:refinery-generator`](pathname://refinery-generator) +* [`tools.refinery:refinery-generator-cli`](pathname://refinery-generator-cli) +* [`tools.refinery:refinery-language`](pathname://refinery-language) +* [`tools.refinery:refinery-language-ide`](pathname://refinery-language-ide) +* [`tools.refinery:refinery-language-model`](pathname://refinery-language-model) +* [`tools.refinery:refinery-language-semantics`](pathname://refinery-language-semantics) +* [`tools.refinery:refinery-language-web`](pathname://refinery-language-web) +* [`tools.refinery:refinery-logic`](pathname://refinery-logic) +* [`tools.refinery:refinery-store`](pathname://refinery-store) +* [`tools.refinery:refinery-store-dse`](pathname://refinery-store-dse) +* [`tools.refinery:refinery-store-dse-visualization`](pathname://refinery-store-dse-visualization) +* [`tools.refinery:refinery-store-query`](pathname://refinery-store-query) +* [`tools.refinery:refinery-store-query-interpreter`](pathname://refinery-store-query-interpreter) +* [`tools.refinery:refinery-store-reasoning`](pathname://refinery-store-reasoning) +* [`tools.refinery:refinery-store-reasoning-scope`](pathname://refinery-store-reasoning-scope) +* [`tools.refinery:refinery-store-reasoning-smt`](pathname://refinery-store-reasoning-smt) + +# Interpreter + +:::note + +The _Refinery Interpreter_ is modified version of [VIATRA™](https://eclipse.dev/viatra/) specifically for use in Refinery. If you're interested in learning about [VIATRA™](https://eclipse.dev/viatra/), we recommend the [VIATRA™ documentation](https://eclipse.dev/viatra/documentation/index.html) and [source code](https://github.com/eclipse-viatra/org.eclipse.viatra) instead. Eclipse®, VIATRA™ and ‘Eclipse VIATRA™’ are trademarks of Eclipse Foundation, Inc. + +::: + +* [`tools.refinery.interpreter:refinery-interpreter`](pathname://refinery-interpreter) +* [`tools.refinery.interpreter:refinery-interpreter-localsearch`](pathname://refinery-interpreter-localsearch) +* [`tools.refinery.interpreter:refinery-interpreter-rete`](pathname://refinery-interpreter-rete) +* [`tools.refinery.interpreter:refinery-interpreter-rete-recipes`](pathname://refinery-interpreter-rete-recipes) diff --git a/subprojects/docs/src/docs-api/contributing.md b/subprojects/docs/src/docs-api/contributing.md deleted file mode 100644 index 4a135b81..00000000 --- a/subprojects/docs/src/docs-api/contributing.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -SPDX-FileCopyrightText: 2021-2023 The Refinery Authors -SPDX-License-Identifier: EPL-2.0 -sidebar_position: 1 -sidebar_label: Contributing ---- - -# Contributing to Refinery - -## Setting up the development environment - -### With IntelliJ IDEA - -We prefer IntelliJ IDEA as a development environment. -No special preparations should be necessary for importing the project as a Gradle project into IDEA. - -However, you will need Eclipse to edit Xtext (`*.xtext`) and MWE2 (`*.mwe2`) files and Ecore class diagrams (`*.aird`, `*.ecore`, `*.genmodel`). -If you do not plan on making changes to such files, feel free to skip the Eclipse installation steps below. - -### With Eclipse IDE - -1. Download and install a _Java 21_ compatible JDK. For Windows, prefer OpenJDK builds from [Adoptium](https://adoptium.net/). - -2. Download and extract the [Eclipse IDE for Java and DSL Developers 2023-12](https://www.eclipse.org/downloads/packages/release/2023-12/r/eclipse-ide-java-and-dsl-developers) package. - -3. Launch Eclipse and create a new workspace. - -4. Open _Help > Eclipse Marketplace_ and install the following software: - * _EclEmma Java Code Coverage_ - * _EcoreTools : Ecore Diagram Editor_ - * _Sirius_ (ignore the warning during installation about the solution _Sirius_ not being available) - * _SonarLint_ - -5. Open _Window > Preferences_ and set the following preferences: - * _General > Workspace > Text file encoding_ should be _UTF-8_. - * _General > Workspace > New text file line delimiter_ should be _Unix_. - * Add the JDK 21 to _Java > Installed JREs_. - * Make sure JDK 21 is selected for _JavaSE-21_ at _Java > Installed JREs > Execution Environments_. - * Set _Gradle > Java home_ to the `JAVA_HOME` directory (the directory which contains the `bin` directory) of JDK 21. Here, Buildship will show a yellow warning sign, which can be safely ignored. - * Set _Java > Compiler > JDK Compliance > Compiler compliance level_ to _21_. - -6. Clone the project Git repository but do not import it into Eclipse yet. - -7. Open a new terminal an run `./gradlew prepareEclipse` (`.\gradlew prepareEclipse` on Windows) in the cloned repository. - * This should complete without any compilation errors. - * If you get any errors about the JVM version, check whether the `JAVA_HOME` environment variable is set to the location of JDK. You can query the variable with `echo $JAVA_HOME` on Linux and `echo $Env:JAVA_HOME` in PowerShell on Windows. To set it, use `export JAVA_HOME=/java/path/here` or `$Env:JAVA_HOME="C:\java\path\here"`, respectively. - * If the build fails with a `Host name must not be empty` error, you [might need to remove the empty proxy configuration from your global `gradle.properties` file](https://stackoverflow.com/a/62128323). - -8. Select _File > Import... > Gradle > Existing Gradle Project_ and import the cloned repository in Eclipse. - * Make sure to select the root of the repository (containing this file) as the _Project root directory_ and that the _Gradle distribution_ is _Gradle wrapper_. - * If you have previously imported the project into Eclipse, this step will likely fail. In that case, you should remove the projects from Eclipse, run `git clean -fxd` in the repository, and start over from step 8. diff --git a/subprojects/docs/src/docs-api/index.md b/subprojects/docs/src/docs-api/index.md deleted file mode 100644 index 4537889e..00000000 --- a/subprojects/docs/src/docs-api/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -SPDX-FileCopyrightText: 2024 The Refinery Authors -SPDX-License-Identifier: EPL-2.0 -sidebar_position: 0 ---- - -# Programming guide - -:::warning - -Under construction - -::: diff --git a/subprojects/docs/src/docs-api/javadoc.md b/subprojects/docs/src/docs-api/javadoc.md deleted file mode 100644 index 7e39b9b9..00000000 --- a/subprojects/docs/src/docs-api/javadoc.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -SPDX-FileCopyrightText: 2024 The Refinery Authors -SPDX-License-Identifier: EPL-2.0 -description: API documentation for Refinery components automatically generated by Javadoc -sidebar_position: 999 ---- - -# Javadoc - -Here you can find API documentation for Refinery components automatically generated by Javadoc. We recommend reading the [Programming guide](/api) first to understand how to use these components. - -# Refinery - -* [`tools.refinery:refinery-generator`](pathname://refinery-generator) -* [`tools.refinery:refinery-generator-cli`](pathname://refinery-generator-cli) -* [`tools.refinery:refinery-language`](pathname://refinery-language) -* [`tools.refinery:refinery-language-ide`](pathname://refinery-language-ide) -* [`tools.refinery:refinery-language-model`](pathname://refinery-language-model) -* [`tools.refinery:refinery-language-semantics`](pathname://refinery-language-semantics) -* [`tools.refinery:refinery-language-web`](pathname://refinery-language-web) -* [`tools.refinery:refinery-logic`](pathname://refinery-logic) -* [`tools.refinery:refinery-store`](pathname://refinery-store) -* [`tools.refinery:refinery-store-dse`](pathname://refinery-store-dse) -* [`tools.refinery:refinery-store-dse-visualization`](pathname://refinery-store-dse-visualization) -* [`tools.refinery:refinery-store-query`](pathname://refinery-store-query) -* [`tools.refinery:refinery-store-query-interpreter`](pathname://refinery-store-query-interpreter) -* [`tools.refinery:refinery-store-reasoning`](pathname://refinery-store-reasoning) -* [`tools.refinery:refinery-store-reasoning-scope`](pathname://refinery-store-reasoning-scope) -* [`tools.refinery:refinery-store-reasoning-smt`](pathname://refinery-store-reasoning-smt) - -# Interpreter - -:::note - -The _Refinery Interpreter_ is modified version of [VIATRA™](https://eclipse.dev/viatra/) specifically for use in Refinery. If you're interested in learning about [VIATRA™](https://eclipse.dev/viatra/), we recommend the [VIATRA™ documentation](https://eclipse.dev/viatra/documentation/index.html) and [source code](https://github.com/eclipse-viatra/org.eclipse.viatra) instead. Eclipse®, VIATRA™ and ‘Eclipse VIATRA™’ are trademarks of Eclipse Foundation, Inc. - -::: - -* [`tools.refinery.interpreter:refinery-interpreter`](pathname://refinery-interpreter) -* [`tools.refinery.interpreter:refinery-interpreter-localsearch`](pathname://refinery-interpreter-localsearch) -* [`tools.refinery.interpreter:refinery-interpreter-rete`](pathname://refinery-interpreter-rete) -* [`tools.refinery.interpreter:refinery-interpreter-rete-recipes`](pathname://refinery-interpreter-rete-recipes) diff --git a/subprojects/docs/src/docs/docker.md b/subprojects/docs/src/docs/docker.md deleted file mode 100644 index c61c1457..00000000 --- a/subprojects/docs/src/docs/docker.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -SPDX-FileCopyrightText: 2024 The Refinery Authors -SPDX-License-Identifier: EPL-2.0 -sidebar_position: 100 -sidebar_label: Docker ---- - -# Running in Docker - -:::note - -Refinery can run as a cloud-based _Graph Solver as a Service_ without local installation. -If you're just looking to try Refinery, our [online demo](https://refinery.services/) provides a seamless experience without installation. - -::: - -:::info - -Installing Refinery as a Docker container can support more advanced use cases, such as when generating models with more resources or a longer timeout. - -::: - -To generate larger models with a longer timeout, you can use our [Docker container](https://github.com/graphs4value/refinery/pkgs/container/refinery) on either `amd64` or `arm64` machines: - -```shell -docker run --rm -it -p 8888:8888 ghcr.io/graphs4value/refinery -``` - -Once Docker pulls and starts the container, you can navigate to http://localhost:8888 to open the model generation interface and start editing. - -Alternatively, you can follow the [instructions to set up a local development environment](/api/contributing) and compile and run Refinery from source. - -## Updating - -To take advantage of the latest updates, you can simply re-pull our Docker container from the GitHub Container Registry: - -```shell -docker pull ghcr.io/graphs4value/refinery -``` - -Restart the container to make sure that you're running the last pulled version. - -## Environmental variables - -The Docker container supports the following environmental variables to customize its behavior. -Customizing these variable should only be needed if you want to _increase resource limits_ or _expose you Refinery instance over the network_ for others. - -Notes for **local-only instances** are highlighted with the :arrow_right: arrow emoji. - -Important security notices for **public instances** are highlighted with the :warning: warning emoji. - -### Networking - -#### `REFINERY_LISTEN_HOST` - -Hostname to listen at for incoming HTTP connections. - -**Default value:** `0.0.0.0` (accepts connections on any IP address) - -#### `REFINERY_LISTEN_PORT` - -TCP port to listen at for incoming HTTP connections. - -Refinery doesn't support HTTPS connections out of the box, so there's no point in setting this to `443`. Use a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) instead if you wish to expose Refinery to encrypted connections. - -If you change this value, don't forget to adjust the `-p 8888:8888` option of the `docker run` command to [expose](https://docs.docker.com/reference/cli/docker/container/run/#publish) the selected port. - -**Default value:** `8888` - -#### `REFINERY_PUBLIC_HOST` - -Publicly visible hostname of the Refinery instance. - -:arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty. - -:warning: You should set this to the publicly visible hostname of your Refinery instance if you wish to expose Refinery over the network. Most likely, this will be the hostname of a reverse proxy that terminates TLS connections. Our online demo sets this to [refinery.services](https://refinery.services/). - -**Default value:** _empty_ - -#### `REFINERY_PUBLIC_PORT` - -Publicly visible port of the Refinery instance. - -:arrow_right: For installations only accessed locally (i.e., `localhost:8888`), this value is ignored because `REFINERY_PUBLC_HOST` is not set. - -**Default value:** `443` - -#### `REFINERY_ALLOWED_ORIGINS` - -Comma-separated list of allowed origins for incoming WebSocket connections. If this variable is empty, all incoming WebSocket connections are accepted. - -:arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty. - -:warning: The value inferred from `REFINERY_PUBLIC_HOST` and `REFINERY_PUBLIC_PORT` should be suitable for instances exposed over the network. For security reasons, public instances should never leave this empty. - -**Default value:** equal to `REFINERY_PUBLIC_HOST:REFINERY_PUBLIC_PORT` if they are both set, _empty_ otherwise - -### Timeouts - -#### `REFINERY_SEMANTICS_TIMEOUT_MS` - -Timeout for partial model semantics calculation in milliseconds. - -:arrow_right: Increase this if you have a slower machine and the editor times out before showing a preview of your partial model in the _Graph_ or _Table_ views. - -:warning: Increasing this timeout may increase server load. Excessively large timeout may allow users to overload you server by entering extremely complex partial models. - -**Default value:** `1000` - -#### `REFINERY_SEMANTICS_WARMUP_TIMEOUT_MS` - -Timeout for partial model semantics calculation in milliseconds when the server first start. - -Due to various initialization tasks, the first partial model semantics generation may take longer the `REFINERY_SEMANTICS_TIMEOUT_MS` and display a timeout error. This setting increases the timeout for the first generation, leading to seamless use even after server start (especially in auto-scaling setups). - -**Default value:** equal to 2 × `REFINERY_SEMANTICS_TIMEOUT` - -#### `REFINERY_MODEL_GENERATION_TIMEOUT_SEC` - -Timeout for model generation in seconds. - -:arrow_right: Adjust this value if you're generating very large models (> 10000 nodes) and need more time to complete a generation. Note that some _unsatisfiable_ model generation problems cannot be detected by Refinery and will result in model generation running for an arbitrarily long time without producing any solution. - -:warning: Long running model generation will block a [_model generation thread_](#refinery_model_generation_thread_count). Try to balance the number of threads and the timeout to avoid exhausting system resources, but keep the wait time for a free model generation thread for users reasonably short. Auto-scaling to multiple instances may help with bursty demand. - -**Default value:** `600` (10 minutes) - -### Threading - -:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. - -#### `REFINERY_XTEXT_THREAD_COUNT` - -Number of threads used for non-blocking text editing operations. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. - -:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. - -**Default value:** `1` - -#### `REFINERY_XTEXT_LOCKING_THREAD_COUNT` - -Number of threads used for text editing operations that lock the document. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. - - -**Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` - -#### `REFINERY_XTEXT_SEMANTICS_THREAD_COUNT` - -Number of threads used for model semantics calculation. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. - -Must be at least as large as `REFINERY_XTEXT_THREAD_COUNT`. - -:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. - -**Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` - -#### `REFINERY_MODEL_GENERATION_THREAD_COUNT` - -Number of threads used for model semantics calculation. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. - -:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. Each model generation task may also demand a large amount of memory in addition to CPU time. - -**Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` - -### Libraries - -#### `REFINERY_LIBRARY_PATH` - -Modules (`.refinery` files) in this directory or colon-separated list of directories will be exposed to user via Refinery's `import` mechanism. - -:arrow_right: Use this in conjunction with the [mount volume (-v)](https://docs.docker.com/reference/cli/docker/container/run/#volume) option of `docker run` to work with multi-file projects in Refinery. - -:warning: Make sure you only expose files that you want to make public. It's best to expose a directory that contains nothing other that `.refinery` files to minimize potential information leaks. - -**Default value:** _empty_ (no directories are exposed) diff --git a/subprojects/docs/src/docs/index.md b/subprojects/docs/src/docs/index.md deleted file mode 100644 index bb28df57..00000000 --- a/subprojects/docs/src/docs/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -SPDX-FileCopyrightText: 2024 The Refinery Authors -SPDX-License-Identifier: EPL-2.0 -sidebar_position: 0 ---- - -# Introduction - -Various software and systems engineering scenarios rely on the systematic construction of consistent graph models. However, **automatically generating a diverse set of consistent graph models** for complex domain specifications is challenging. First, the graph generation problem must be specified with mathematical precision. Moreover, graph generation is a computationally complex task, which necessitates specialized logic solvers. - -**Refinery is a novel open-source software framework** to automatically synthesize a diverse set of consistent domain-specific graph models. The framework offers an expressive high-level specification language using partial models to succinctly formulate a wide range of graph generation challenges. It also provides a modern cloud-based architecture for a scalable _Graph Solver as a Service,_ which uses logic reasoning rules to efficiently synthesize a diverse set of solutions to graph generation problems by partial model refinement. Applications include system-level architecture synthesis, test generation for modeling tools or traffic scenario synthesis for autonomous vehicles. diff --git a/subprojects/docs/src/docs/language/_category_.yml b/subprojects/docs/src/docs/language/_category_.yml deleted file mode 100644 index 7060edf3..00000000 --- a/subprojects/docs/src/docs/language/_category_.yml +++ /dev/null @@ -1,10 +0,0 @@ -# SPDX-FileCopyrightText: 2024 The Refinery Authors -# -# SPDX-License-Identifier: EPL-2.0 - -position: 2 -label: Language reference -link: - type: generated-index - slug: /category/language - description: Learn more about the Refinery partial modeling language! diff --git a/subprojects/docs/src/docs/language/classes.md b/subprojects/docs/src/docs/language/classes.md deleted file mode 100644 index 7278dc35..00000000 --- a/subprojects/docs/src/docs/language/classes.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -SPDX-FileCopyrightText: 2024 The Refinery Authors -SPDX-License-Identifier: EPL-2.0 -description: Metamodeling in Refinery -sidebar_position: 0 ---- - -# Classes and references - -:::warning - -Under construction - -::: diff --git a/subprojects/docs/src/docs/tutorials/_category_.yml b/subprojects/docs/src/docs/tutorials/_category_.yml deleted file mode 100644 index 25a06d98..00000000 --- a/subprojects/docs/src/docs/tutorials/_category_.yml +++ /dev/null @@ -1,10 +0,0 @@ -# SPDX-FileCopyrightText: 2024 The Refinery Authors -# -# SPDX-License-Identifier: EPL-2.0 - -position: 1 -label: Tutorials -link: - type: generated-index - title: Tutorial overview - description: Try Refinery in practical partial modeling challenges! diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig1.png b/subprojects/docs/src/docs/tutorials/file-system/fig1.png deleted file mode 100644 index da30af3c..00000000 Binary files a/subprojects/docs/src/docs/tutorials/file-system/fig1.png and /dev/null differ diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig1.png.license b/subprojects/docs/src/docs/tutorials/file-system/fig1.png.license deleted file mode 100644 index ff75bc7c..00000000 --- a/subprojects/docs/src/docs/tutorials/file-system/fig1.png.license +++ /dev/null @@ -1,3 +0,0 @@ -SPDX-FileCopyrightText: 2023 The Refinery Authors - -SPDX-License-Identifier: EPL-2.0 diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig2.png b/subprojects/docs/src/docs/tutorials/file-system/fig2.png deleted file mode 100644 index f42e3d3e..00000000 Binary files a/subprojects/docs/src/docs/tutorials/file-system/fig2.png and /dev/null differ diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig2.png.license b/subprojects/docs/src/docs/tutorials/file-system/fig2.png.license deleted file mode 100644 index ff75bc7c..00000000 --- a/subprojects/docs/src/docs/tutorials/file-system/fig2.png.license +++ /dev/null @@ -1,3 +0,0 @@ -SPDX-FileCopyrightText: 2023 The Refinery Authors - -SPDX-License-Identifier: EPL-2.0 diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig3.png b/subprojects/docs/src/docs/tutorials/file-system/fig3.png deleted file mode 100644 index 9506417a..00000000 Binary files a/subprojects/docs/src/docs/tutorials/file-system/fig3.png and /dev/null differ diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig3.png.license b/subprojects/docs/src/docs/tutorials/file-system/fig3.png.license deleted file mode 100644 index ff75bc7c..00000000 --- a/subprojects/docs/src/docs/tutorials/file-system/fig3.png.license +++ /dev/null @@ -1,3 +0,0 @@ -SPDX-FileCopyrightText: 2023 The Refinery Authors - -SPDX-License-Identifier: EPL-2.0 diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig4.png b/subprojects/docs/src/docs/tutorials/file-system/fig4.png deleted file mode 100644 index cc012f24..00000000 Binary files a/subprojects/docs/src/docs/tutorials/file-system/fig4.png and /dev/null differ diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig4.png.license b/subprojects/docs/src/docs/tutorials/file-system/fig4.png.license deleted file mode 100644 index ff75bc7c..00000000 --- a/subprojects/docs/src/docs/tutorials/file-system/fig4.png.license +++ /dev/null @@ -1,3 +0,0 @@ -SPDX-FileCopyrightText: 2023 The Refinery Authors - -SPDX-License-Identifier: EPL-2.0 diff --git a/subprojects/docs/src/docs/tutorials/file-system/index.md b/subprojects/docs/src/docs/tutorials/file-system/index.md deleted file mode 100644 index 1d15512f..00000000 --- a/subprojects/docs/src/docs/tutorials/file-system/index.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -SPDX-FileCopyrightText: 2023-2024 The Refinery Authors -SPDX-License-Identifier: EPL-2.0 -description: Introduction to classes, references, and error predicates -sidebar_position: 0 -sidebar_label: File system ---- - -# File system tutorial - -The goal of this tutorial is to give a brief overview of the partial modeling and model generation features of the Refinery framework. The running example will be the modeling of files, directories, and repositories. - -## Partial models - -### Types and relations - -- First, let us introduce some basic types: `Dir`, `File`, and `FileSystem`, along with the relations between them: `element` and `root`. There is a `scope` expression at the end, which we will ignore for now. - -```refinery -class FileSystem { - contains File[1] root -} - -class File. - -class Dir extends File { - contains File[] element -} - -scope node = 10. -``` - -import Link from '@docusaurus/Link'; - -

- Try in Refinery -

- -- Notice that the syntax is essentially identical to [Xcore](https://wiki.eclipse.org/Xcore). -- Review the partial model visualization. You should get something like this: - -![Initial model](fig1.png) - -- Add some statements about a partial model: - -```refinery -class FileSystem { - contains File[1] root -} - -class File. - -class Dir extends File { - contains File[] element -} - -Dir(resources). -element(resources, img). -File(img). - -scope node = 10. -``` - -![Partial model extended with new facts](fig2.png) - -### Partial models - -- Notice that the instance model elements are coexisting with ```::new``` nodes representing the prototypes of newly created objects. - -- Check the disabled `equals` and `exist` predicates. check the visual annotation of those predicates in the visualization (dashed line, shadow). - -![Object existence and equality](fig3.png) - -### Information merging - -- For the object `img`, we didn't specify if it is a directory or not. Therefore, it will typically be a folder. - -- If we want to state that img is not a directory, we need to a negative statement: - -```refinery -!Dir(img). -``` - -- Statements are merged with respect to the refinement relation of 4-valued logic. - -- If we add, a statement both negatively and positively, it will create an inconsistency: - -```refinery -element(resources, img). -!element(resources, img). -``` - -- Inconsistent models parts in a partial model typically make the problem trivially unsatisfiable. - -![Inconsistent partial model](fig4.png) - -- However, the model can be saved if the inconsistent part may not exist... - -```refinery -!File(File::new). -``` - -### Default values - -- A large amount of statements can be expressed by using `*`. -- The `default` keyword defines lower priority statements that need to be considered unless other statement specifies otherwise. No information merging is happening. - -## Constraints - -Let's extend the metamodel with a new class `SymLink`: - -```refinery -class FileSystem { - contains File[1] root -} - -class File. - -class Dir extends File { - contains File[0..10] element -} - -class SymLink extends File { - File[1] target -} - -Dir(resources). -element(resources, img). -element(resources, link). -target(link, img). - -scope node = 10. -``` - -- Add some simple constraints: - -```refinery -% Simple constraints: -pred hasReference(f) <-> target(_, f). -error pred selfLoop(s) <-> target(s, s). -target(x,x). -``` - -- There are no empty directories in a git repository, so let's forbid them! - -```refinery -error pred emptyDir(d) <-> Dir(d), !element(d,_). -``` - -- End result: - -```refinery -class FileSystem { - contains File[1] root -} - -class File. - -class Dir extends File { - contains File[0..10] element -} - -class SymLink extends File { - File[1] target -} - -Dir(resources). -element(resources, img). -!Dir(img). -element(resources, link). -target(link,img). - -% Simple constraints: -pred hasReference(f) <-> target(_, f). -error pred selfLoop(s) <-> target(s, s). - -% Object equality with ==: -error pred emptyDir(d) <-> Dir(d), !element(d, _). -pred importantFile(f) <-> target(l1, f), target(l2, f), l1 != l2. - -% Transitive closure, and -pred containsFile(fs, file) <-> - FileSystem(fs), - root(fs, file) -; - FileSystem(fs), - root(fs, rootDir), - element+(rootDir, file). - -% Predicate reuse -error conflictBetweenTwoFileSystem(fs1, fs2, l, t) <-> - containsFile(fs1, l), - containsFile(fs2, t), - fs1 != fs2, - target(l, t). - -scope node = 40..50, FileSystem = 2, importantFile = 1..*. -``` diff --git a/subprojects/docs/src/learn/docker.md b/subprojects/docs/src/learn/docker.md new file mode 100644 index 00000000..0df87da8 --- /dev/null +++ b/subprojects/docs/src/learn/docker.md @@ -0,0 +1,175 @@ +--- +SPDX-FileCopyrightText: 2024 The Refinery Authors +SPDX-License-Identifier: EPL-2.0 +sidebar_position: 100 +sidebar_label: Docker +--- + +# Running in Docker + +:::note + +Refinery can run as a cloud-based _Graph Solver as a Service_ without local installation. +If you're just looking to try Refinery, our [online demo](https://refinery.services/) provides a seamless experience without installation. + +::: + +:::info + +Installing Refinery as a Docker container can support more advanced use cases, such as when generating models with more resources or a longer timeout. + +::: + +To generate larger models with a longer timeout, you can use our [Docker container](https://github.com/graphs4value/refinery/pkgs/container/refinery) on either `amd64` or `arm64` machines: + +```shell +docker run --rm -it -p 8888:8888 ghcr.io/graphs4value/refinery +``` + +Once Docker pulls and starts the container, you can navigate to http://localhost:8888 to open the model generation interface and start editing. + +Alternatively, you can follow the [instructions to set up a local development environment](/develop/contributing) and compile and run Refinery from source. + +## Updating + +To take advantage of the latest updates, you can simply re-pull our Docker container from the GitHub Container Registry: + +```shell +docker pull ghcr.io/graphs4value/refinery +``` + +Restart the container to make sure that you're running the last pulled version. + +## Environmental variables + +The Docker container supports the following environmental variables to customize its behavior. +Customizing these variable should only be needed if you want to _increase resource limits_ or _expose you Refinery instance over the network_ for others. + +Notes for **local-only instances** are highlighted with the :arrow_right: arrow emoji. + +Important security notices for **public instances** are highlighted with the :warning: warning emoji. + +### Networking + +#### `REFINERY_LISTEN_HOST` + +Hostname to listen at for incoming HTTP connections. + +**Default value:** `0.0.0.0` (accepts connections on any IP address) + +#### `REFINERY_LISTEN_PORT` + +TCP port to listen at for incoming HTTP connections. + +Refinery doesn't support HTTPS connections out of the box, so there's no point in setting this to `443`. Use a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) instead if you wish to expose Refinery to encrypted connections. + +If you change this value, don't forget to adjust the `-p 8888:8888` option of the `docker run` command to [expose](https://docs.docker.com/reference/cli/docker/container/run/#publish) the selected port. + +**Default value:** `8888` + +#### `REFINERY_PUBLIC_HOST` + +Publicly visible hostname of the Refinery instance. + +:arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty. + +:warning: You should set this to the publicly visible hostname of your Refinery instance if you wish to expose Refinery over the network. Most likely, this will be the hostname of a reverse proxy that terminates TLS connections. Our online demo sets this to [refinery.services](https://refinery.services/). + +**Default value:** _empty_ + +#### `REFINERY_PUBLIC_PORT` + +Publicly visible port of the Refinery instance. + +:arrow_right: For installations only accessed locally (i.e., `localhost:8888`), this value is ignored because `REFINERY_PUBLC_HOST` is not set. + +**Default value:** `443` + +#### `REFINERY_ALLOWED_ORIGINS` + +Comma-separated list of allowed origins for incoming WebSocket connections. If this variable is empty, all incoming WebSocket connections are accepted. + +:arrow_right: For installations only accessed locally (i.e., `localhost:8888`) without any reverse proxy, you can safely leave this empty. + +:warning: The value inferred from `REFINERY_PUBLIC_HOST` and `REFINERY_PUBLIC_PORT` should be suitable for instances exposed over the network. For security reasons, public instances should never leave this empty. + +**Default value:** equal to `REFINERY_PUBLIC_HOST:REFINERY_PUBLIC_PORT` if they are both set, _empty_ otherwise + +### Timeouts + +#### `REFINERY_SEMANTICS_TIMEOUT_MS` + +Timeout for partial model semantics calculation in milliseconds. + +:arrow_right: Increase this if you have a slower machine and the editor times out before showing a preview of your partial model in the _Graph_ or _Table_ views. + +:warning: Increasing this timeout may increase server load. Excessively large timeout may allow users to overload you server by entering extremely complex partial models. + +**Default value:** `1000` + +#### `REFINERY_SEMANTICS_WARMUP_TIMEOUT_MS` + +Timeout for partial model semantics calculation in milliseconds when the server first start. + +Due to various initialization tasks, the first partial model semantics generation may take longer the `REFINERY_SEMANTICS_TIMEOUT_MS` and display a timeout error. This setting increases the timeout for the first generation, leading to seamless use even after server start (especially in auto-scaling setups). + +**Default value:** equal to 2 × `REFINERY_SEMANTICS_TIMEOUT` + +#### `REFINERY_MODEL_GENERATION_TIMEOUT_SEC` + +Timeout for model generation in seconds. + +:arrow_right: Adjust this value if you're generating very large models (> 10000 nodes) and need more time to complete a generation. Note that some _unsatisfiable_ model generation problems cannot be detected by Refinery and will result in model generation running for an arbitrarily long time without producing any solution. + +:warning: Long running model generation will block a [_model generation thread_](#refinery_model_generation_thread_count). Try to balance the number of threads and the timeout to avoid exhausting system resources, but keep the wait time for a free model generation thread for users reasonably short. Auto-scaling to multiple instances may help with bursty demand. + +**Default value:** `600` (10 minutes) + +### Threading + +:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. + +#### `REFINERY_XTEXT_THREAD_COUNT` + +Number of threads used for non-blocking text editing operations. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. + +:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. + +**Default value:** `1` + +#### `REFINERY_XTEXT_LOCKING_THREAD_COUNT` + +Number of threads used for text editing operations that lock the document. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. + + +**Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` + +#### `REFINERY_XTEXT_SEMANTICS_THREAD_COUNT` + +Number of threads used for model semantics calculation. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. + +Must be at least as large as `REFINERY_XTEXT_THREAD_COUNT`. + +:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. + +**Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` + +#### `REFINERY_MODEL_GENERATION_THREAD_COUNT` + +Number of threads used for model semantics calculation. A value of `0` allows an _unlimited_ number of threads by running each semantics calculation in a new thread. + +:warning: Excessively large values may overload the server. Make sure that _all_ Refinery threads can run at the same time to avoid thread starvation. Each model generation task may also demand a large amount of memory in addition to CPU time. + +**Default value:** equal to `REFINERY_XTEXT_THREAD_COUNT` + +### Libraries + +#### `REFINERY_LIBRARY_PATH` + +Modules (`.refinery` files) in this directory or colon-separated list of directories will be exposed to user via Refinery's `import` mechanism. + +:arrow_right: Use this in conjunction with the [mount volume (-v)](https://docs.docker.com/reference/cli/docker/container/run/#volume) option of `docker run` to work with multi-file projects in Refinery. + +:warning: Make sure you only expose files that you want to make public. It's best to expose a directory that contains nothing other that `.refinery` files to minimize potential information leaks. + +**Default value:** _empty_ (no directories are exposed) diff --git a/subprojects/docs/src/learn/index.md b/subprojects/docs/src/learn/index.md new file mode 100644 index 00000000..bb28df57 --- /dev/null +++ b/subprojects/docs/src/learn/index.md @@ -0,0 +1,11 @@ +--- +SPDX-FileCopyrightText: 2024 The Refinery Authors +SPDX-License-Identifier: EPL-2.0 +sidebar_position: 0 +--- + +# Introduction + +Various software and systems engineering scenarios rely on the systematic construction of consistent graph models. However, **automatically generating a diverse set of consistent graph models** for complex domain specifications is challenging. First, the graph generation problem must be specified with mathematical precision. Moreover, graph generation is a computationally complex task, which necessitates specialized logic solvers. + +**Refinery is a novel open-source software framework** to automatically synthesize a diverse set of consistent domain-specific graph models. The framework offers an expressive high-level specification language using partial models to succinctly formulate a wide range of graph generation challenges. It also provides a modern cloud-based architecture for a scalable _Graph Solver as a Service,_ which uses logic reasoning rules to efficiently synthesize a diverse set of solutions to graph generation problems by partial model refinement. Applications include system-level architecture synthesis, test generation for modeling tools or traffic scenario synthesis for autonomous vehicles. diff --git a/subprojects/docs/src/learn/language/_category_.yml b/subprojects/docs/src/learn/language/_category_.yml new file mode 100644 index 00000000..f5a6f896 --- /dev/null +++ b/subprojects/docs/src/learn/language/_category_.yml @@ -0,0 +1,10 @@ +# SPDX-FileCopyrightText: 2024 The Refinery Authors +# +# SPDX-License-Identifier: EPL-2.0 + +position: 2 +label: Language reference +link: + type: generated-index + slug: /language + description: Learn more about the Refinery partial modeling language! diff --git a/subprojects/docs/src/learn/language/classes.md b/subprojects/docs/src/learn/language/classes.md new file mode 100644 index 00000000..7278dc35 --- /dev/null +++ b/subprojects/docs/src/learn/language/classes.md @@ -0,0 +1,14 @@ +--- +SPDX-FileCopyrightText: 2024 The Refinery Authors +SPDX-License-Identifier: EPL-2.0 +description: Metamodeling in Refinery +sidebar_position: 0 +--- + +# Classes and references + +:::warning + +Under construction + +::: diff --git a/subprojects/docs/src/learn/tutorials/_category_.yml b/subprojects/docs/src/learn/tutorials/_category_.yml new file mode 100644 index 00000000..adf8293f --- /dev/null +++ b/subprojects/docs/src/learn/tutorials/_category_.yml @@ -0,0 +1,11 @@ +# SPDX-FileCopyrightText: 2024 The Refinery Authors +# +# SPDX-License-Identifier: EPL-2.0 + +position: 1 +label: Tutorials +link: + type: generated-index + slug: /tutorials + title: Tutorial overview + description: Try Refinery in practical partial modeling challenges! diff --git a/subprojects/docs/src/learn/tutorials/file-system/fig1.png b/subprojects/docs/src/learn/tutorials/file-system/fig1.png new file mode 100644 index 00000000..da30af3c Binary files /dev/null and b/subprojects/docs/src/learn/tutorials/file-system/fig1.png differ diff --git a/subprojects/docs/src/learn/tutorials/file-system/fig1.png.license b/subprojects/docs/src/learn/tutorials/file-system/fig1.png.license new file mode 100644 index 00000000..ff75bc7c --- /dev/null +++ b/subprojects/docs/src/learn/tutorials/file-system/fig1.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2023 The Refinery Authors + +SPDX-License-Identifier: EPL-2.0 diff --git a/subprojects/docs/src/learn/tutorials/file-system/fig2.png b/subprojects/docs/src/learn/tutorials/file-system/fig2.png new file mode 100644 index 00000000..f42e3d3e Binary files /dev/null and b/subprojects/docs/src/learn/tutorials/file-system/fig2.png differ diff --git a/subprojects/docs/src/learn/tutorials/file-system/fig2.png.license b/subprojects/docs/src/learn/tutorials/file-system/fig2.png.license new file mode 100644 index 00000000..ff75bc7c --- /dev/null +++ b/subprojects/docs/src/learn/tutorials/file-system/fig2.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2023 The Refinery Authors + +SPDX-License-Identifier: EPL-2.0 diff --git a/subprojects/docs/src/learn/tutorials/file-system/fig3.png b/subprojects/docs/src/learn/tutorials/file-system/fig3.png new file mode 100644 index 00000000..9506417a Binary files /dev/null and b/subprojects/docs/src/learn/tutorials/file-system/fig3.png differ diff --git a/subprojects/docs/src/learn/tutorials/file-system/fig3.png.license b/subprojects/docs/src/learn/tutorials/file-system/fig3.png.license new file mode 100644 index 00000000..ff75bc7c --- /dev/null +++ b/subprojects/docs/src/learn/tutorials/file-system/fig3.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2023 The Refinery Authors + +SPDX-License-Identifier: EPL-2.0 diff --git a/subprojects/docs/src/learn/tutorials/file-system/fig4.png b/subprojects/docs/src/learn/tutorials/file-system/fig4.png new file mode 100644 index 00000000..cc012f24 Binary files /dev/null and b/subprojects/docs/src/learn/tutorials/file-system/fig4.png differ diff --git a/subprojects/docs/src/learn/tutorials/file-system/fig4.png.license b/subprojects/docs/src/learn/tutorials/file-system/fig4.png.license new file mode 100644 index 00000000..ff75bc7c --- /dev/null +++ b/subprojects/docs/src/learn/tutorials/file-system/fig4.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2023 The Refinery Authors + +SPDX-License-Identifier: EPL-2.0 diff --git a/subprojects/docs/src/learn/tutorials/file-system/index.md b/subprojects/docs/src/learn/tutorials/file-system/index.md new file mode 100644 index 00000000..1d15512f --- /dev/null +++ b/subprojects/docs/src/learn/tutorials/file-system/index.md @@ -0,0 +1,201 @@ +--- +SPDX-FileCopyrightText: 2023-2024 The Refinery Authors +SPDX-License-Identifier: EPL-2.0 +description: Introduction to classes, references, and error predicates +sidebar_position: 0 +sidebar_label: File system +--- + +# File system tutorial + +The goal of this tutorial is to give a brief overview of the partial modeling and model generation features of the Refinery framework. The running example will be the modeling of files, directories, and repositories. + +## Partial models + +### Types and relations + +- First, let us introduce some basic types: `Dir`, `File`, and `FileSystem`, along with the relations between them: `element` and `root`. There is a `scope` expression at the end, which we will ignore for now. + +```refinery +class FileSystem { + contains File[1] root +} + +class File. + +class Dir extends File { + contains File[] element +} + +scope node = 10. +``` + +import Link from '@docusaurus/Link'; + +

+ Try in Refinery +

+ +- Notice that the syntax is essentially identical to [Xcore](https://wiki.eclipse.org/Xcore). +- Review the partial model visualization. You should get something like this: + +![Initial model](fig1.png) + +- Add some statements about a partial model: + +```refinery +class FileSystem { + contains File[1] root +} + +class File. + +class Dir extends File { + contains File[] element +} + +Dir(resources). +element(resources, img). +File(img). + +scope node = 10. +``` + +![Partial model extended with new facts](fig2.png) + +### Partial models + +- Notice that the instance model elements are coexisting with ```::new``` nodes representing the prototypes of newly created objects. + +- Check the disabled `equals` and `exist` predicates. check the visual annotation of those predicates in the visualization (dashed line, shadow). + +![Object existence and equality](fig3.png) + +### Information merging + +- For the object `img`, we didn't specify if it is a directory or not. Therefore, it will typically be a folder. + +- If we want to state that img is not a directory, we need to a negative statement: + +```refinery +!Dir(img). +``` + +- Statements are merged with respect to the refinement relation of 4-valued logic. + +- If we add, a statement both negatively and positively, it will create an inconsistency: + +```refinery +element(resources, img). +!element(resources, img). +``` + +- Inconsistent models parts in a partial model typically make the problem trivially unsatisfiable. + +![Inconsistent partial model](fig4.png) + +- However, the model can be saved if the inconsistent part may not exist... + +```refinery +!File(File::new). +``` + +### Default values + +- A large amount of statements can be expressed by using `*`. +- The `default` keyword defines lower priority statements that need to be considered unless other statement specifies otherwise. No information merging is happening. + +## Constraints + +Let's extend the metamodel with a new class `SymLink`: + +```refinery +class FileSystem { + contains File[1] root +} + +class File. + +class Dir extends File { + contains File[0..10] element +} + +class SymLink extends File { + File[1] target +} + +Dir(resources). +element(resources, img). +element(resources, link). +target(link, img). + +scope node = 10. +``` + +- Add some simple constraints: + +```refinery +% Simple constraints: +pred hasReference(f) <-> target(_, f). +error pred selfLoop(s) <-> target(s, s). +target(x,x). +``` + +- There are no empty directories in a git repository, so let's forbid them! + +```refinery +error pred emptyDir(d) <-> Dir(d), !element(d,_). +``` + +- End result: + +```refinery +class FileSystem { + contains File[1] root +} + +class File. + +class Dir extends File { + contains File[0..10] element +} + +class SymLink extends File { + File[1] target +} + +Dir(resources). +element(resources, img). +!Dir(img). +element(resources, link). +target(link,img). + +% Simple constraints: +pred hasReference(f) <-> target(_, f). +error pred selfLoop(s) <-> target(s, s). + +% Object equality with ==: +error pred emptyDir(d) <-> Dir(d), !element(d, _). +pred importantFile(f) <-> target(l1, f), target(l2, f), l1 != l2. + +% Transitive closure, and +pred containsFile(fs, file) <-> + FileSystem(fs), + root(fs, file) +; + FileSystem(fs), + root(fs, rootDir), + element+(rootDir, file). + +% Predicate reuse +error conflictBetweenTwoFileSystem(fs1, fs2, l, t) <-> + containsFile(fs1, l), + containsFile(fs2, t), + fs1 != fs2, + target(l, t). + +scope node = 40..50, FileSystem = 2, importantFile = 1..*. +``` diff --git a/subprojects/docs/src/pages/index.tsx b/subprojects/docs/src/pages/index.tsx index 25884336..713223c2 100644 --- a/subprojects/docs/src/pages/index.tsx +++ b/subprojects/docs/src/pages/index.tsx @@ -34,7 +34,7 @@ function Hero() { Try online