diff --git a/docs/reference/Pipfile b/docs/reference/Pipfile index 97bf2d4575e..37b688987f7 100644 --- a/docs/reference/Pipfile +++ b/docs/reference/Pipfile @@ -14,8 +14,10 @@ myst_parser = ">=2.0.0" sphinx-design = ">=0.5.0" sphinx-tabs = ">=3.4.5" sphinx-markdown-tables = ">=0.0.15" -furo = ">=2022.12.7" +sphinx_book_theme = ">=1.1.3" sphinxcontrib-jquery = ">=4.1" +sphinx-copybutton = ">=0.5.2" +linkify-it-py = ">=2.0.3" [requires] python_version = "3" diff --git a/docs/reference/_static/theme_tweak.css b/docs/reference/_static/theme_tweak.css index 8e6ce9239a3..5a67d7fa0d3 100644 --- a/docs/reference/_static/theme_tweak.css +++ b/docs/reference/_static/theme_tweak.css @@ -1,15 +1,26 @@ -.wy-table-responsive table td, -.wy-table-responsive table th { - white-space: normal; +html[data-theme="light"] { + body { + background-color:#fff; + background-position: top center; + background-repeat: no-repeat; + background-size: cover; + color: #151D21; + } } -.wy-table-responsive { - margin-bottom: 24px; - max-width: 100%; - overflow: visible; +html[data-theme="dark"] { + body { + background-color: #151D21; + background-image: url(https://slint.dev/assets/img/bg-dark.svg); + background-position: top center; + background-repeat: no-repeat; + background-size: cover; + color: #fff; + } + --pst-color-background: transparent; + --pst-color-on-background: transparent; } -img.logo { - max-height: 70px; - border-radius: 12% !important; -} +div.sidebar-primary-item:first-child { + text-align: center; +} \ No newline at end of file diff --git a/docs/reference/conf.py b/docs/reference/conf.py index 6f3ad1961f3..f4830526aa5 100644 --- a/docs/reference/conf.py +++ b/docs/reference/conf.py @@ -28,13 +28,14 @@ html_title = f'Slint {version} Reference' # Set title here, otherwise it will say "Slint Reference documentation" copyright = "SixtyFPS GmbH" author = "Slint Developers " +github_url = "https://github.com/slint-ui/slint" # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["myst_parser", "sphinx_markdown_tables", "sphinx.ext.autosectionlabel", "sphinxcontrib.jquery", "sphinx_tabs.tabs", "sphinx_design"] +extensions = ["myst_parser", "sphinx_markdown_tables", "sphinx.ext.autosectionlabel", "sphinxcontrib.jquery", "sphinx_tabs.tabs", "sphinx_design", "sphinx_copybutton"] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -56,43 +57,69 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "furo" - +html_theme = "sphinx_book_theme" +html_favicon = "https://slint.dev/favicon.svg" html_theme_options = { - "collapse_navigation": False, - "footer_icons": [ - { - "name": "Slint", - "url": "https://slint.dev", - "html": """ - - """, - "class": "", - }, - { - "name": "GitHub", - "url": "https://github.com/slint-ui/slint", - "html": """ - - - - """, - "class": "", - }, - ], + "repository_url": "https://github.com/slint-ui/slint", + "use_repository_button": True, + "use_issues_button": True, + "use_edit_page_button": True, + "use_download_button": False, + "use_fullscreen_button": False, + "home_page_in_toc": True, + "logo": { + "text": f'Slint {version} Reference', + "image_light": "https://slint.dev/logo/slint-logo-small-light.svg", + "image_dark": "https://slint.dev/logo/slint-logo-small-dark.svg", + "link": "https://slint.dev" + }, + "switcher": { + "json_url": "https://releases.slint.dev/versions.json", + "version_match": version, + }, + "extra_footer": "
https://slint.dev
", +} + +html_sidebars = { + "**": ["version-switcher", "navbar-logo.html", "search-button-field.html", "sbt-sidebar-nav.html"] } +# html_theme_options = { +# "collapse_navigation": False, +# "footer_icons": [ +# { +# "name": "Slint", +# "url": "https://slint.dev", +# "html": """ +# +# """, +# "class": "", +# }, +# { +# "name": "GitHub", +# "url": "https://github.com/slint-ui/slint", +# "html": """ +# +# +# +# """, +# "class": "", +# }, +# ], +# } + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] html_js_files = ['expand_tabs.js'] +html_css_files = [ + 'css/theme_tweak.css', +] html_show_sourcelink = False -html_logo = "https://slint.dev/logo/slint-logo-small-light.svg" - myst_enable_extensions = [ - "html_image", "colon_fence" + "html_image", "colon_fence", "linkify" ] myst_url_schemes = { diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 030fad1deb9..83a297c08f5 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -7,16 +7,48 @@ .. toctree:: :hidden: :maxdepth: 2 - :caption: Introduction + + SlintPad + Showcase + Blog + Video Tutorials + +.. toctree:: + :hidden: + :maxdepth: 2 + :caption: Setting Up src/introduction/index.rst - src/introduction/supported_platforms.md - src/quickstart/index.rst + src/introduction/embedded.rst + src/introduction/desktop.rst + src/introduction/mobile.rst + +.. toctree:: + :hidden: + :maxdepth: 2 + :caption: First Steps + + src/quickstart/getting_started.rst + src/quickstart/memory_tile.md + src/quickstart/polishing_the_tile.md + src/quickstart/from_one_to_multiple_tiles.md + src/quickstart/creating_the_tiles.md + src/quickstart/game_logic.md + src/quickstart/running_in_a_browser.md + src/quickstart/ideas_for_the_reader.md + src/quickstart/conclusion.md + +.. toctree:: + :hidden: + :maxdepth: 2 + :caption: Reference + + src/reference/syntax/index.rst .. toctree:: :hidden: :maxdepth: 2 - :caption: Language Reference + :caption: Language Reference (Old) src/language/index.rst src/language/concepts/index.rst @@ -27,14 +59,14 @@ .. toctree:: :hidden: :maxdepth: 2 - :caption: Recipes & Examples + :caption: Recipes & Examples (Old) src/recipes/recipes.md .. toctree:: :hidden: :maxdepth: 2 - :caption: Advanced Topics + :caption: Advanced Topics (Old) src/advanced/debugging_techniques.md src/advanced/style.md diff --git a/docs/reference/src/introduction/desktop.md b/docs/reference/src/introduction/desktop.md new file mode 100644 index 00000000000..4541d539c23 --- /dev/null +++ b/docs/reference/src/introduction/desktop.md @@ -0,0 +1,52 @@ + + +# Build Desktop Applications + +Slint runs on many desktop and embedded platforms and micro-controllers. + +The platform descriptions below cover what has been tested for deployment. For the development environment, +we recommend using a recent desktop operating system and compiler version. + +Contact [SixtyFPS GmbH](https://slint.dev/contact) if you need to support specific or older versions. + +## Desktop Platforms + +Generally, Slint runs on Windows, macOS, and popular Linux distributions. The following tables +cover versions that we specifically test. The general objective is to support the operating systems that +are supported by their vendors at the time of a Slint version release. + +### Windows + +| Operating System | Architecture | +| ---------------- | ------------ | +| Windows 10 | x86-64 | +| Windows 11 | x86-64 | + +### macOS + +| Operating System | Architecture | +| ----------------- | --------------- | +| macOS 12 Monterey | x86-64, aarch64 | +| macOS 13 Ventura | x86-64, aarch64 | +| macOS 14 Sonoma | x86-64, aarch64 | + +### Linux + +Linux desktop distribution present a diverse landscape, and Slint should run on any of them, provided that they +are using Wayland or X-Windows, glibc, and d-bus. If a Linux distribution provides Long Term Support (LTS), +Slint should run on the most recent LTS or newer, at the time of a Slint version release. + +## Embedded Platforms + +Slint runs on a variety of embedded platforms. Generally speaking, Slint requires a modern Linux userspace +with working OpenGL ES 2.0 (or newer) or Vulkan drivers. We've had success running Slint on + +- Yocto based distributions. For C++ applications see [meta-slint](https://github.com/slint-ui/meta-slint) for recipes. Rust application work out of the box with Yocto's rust support. +- BuildRoot based distributions. +- [TorizonCore](https://www.torizon.io/torizoncore-os). + +### Microcontrollers + +Slint's platform abstraction allows for integration into any Rust or C++ based Microcontroller development +environment. Developers need to implement functionality to feed input events such as touch or keyboard, as +well as displaying the pixels rendered by Slint into a frame- or linebuffer. diff --git a/docs/reference/src/introduction/embedded.md b/docs/reference/src/introduction/embedded.md new file mode 100644 index 00000000000..876f9578580 --- /dev/null +++ b/docs/reference/src/introduction/embedded.md @@ -0,0 +1,52 @@ + + +# Build Embedded Applications + +Slint runs on many desktop and embedded platforms and micro-controllers. + +The platform descriptions below cover what has been tested for deployment. For the development environment, +we recommend using a recent desktop operating system and compiler version. + +Contact [SixtyFPS GmbH](https://slint.dev/contact) if you need to support specific or older versions. + +## Desktop Platforms + +Generally, Slint runs on Windows, macOS, and popular Linux distributions. The following tables +cover versions that we specifically test. The general objective is to support the operating systems that +are supported by their vendors at the time of a Slint version release. + +### Windows + +| Operating System | Architecture | +| ---------------- | ------------ | +| Windows 10 | x86-64 | +| Windows 11 | x86-64 | + +### macOS + +| Operating System | Architecture | +| ----------------- | --------------- | +| macOS 12 Monterey | x86-64, aarch64 | +| macOS 13 Ventura | x86-64, aarch64 | +| macOS 14 Sonoma | x86-64, aarch64 | + +### Linux + +Linux desktop distribution present a diverse landscape, and Slint should run on any of them, provided that they +are using Wayland or X-Windows, glibc, and d-bus. If a Linux distribution provides Long Term Support (LTS), +Slint should run on the most recent LTS or newer, at the time of a Slint version release. + +## Embedded Platforms + +Slint runs on a variety of embedded platforms. Generally speaking, Slint requires a modern Linux userspace +with working OpenGL ES 2.0 (or newer) or Vulkan drivers. We've had success running Slint on + +- Yocto based distributions. For C++ applications see [meta-slint](https://github.com/slint-ui/meta-slint) for recipes. Rust application work out of the box with Yocto's rust support. +- BuildRoot based distributions. +- [TorizonCore](https://www.torizon.io/torizoncore-os). + +### Microcontrollers + +Slint's platform abstraction allows for integration into any Rust or C++ based Microcontroller development +environment. Developers need to implement functionality to feed input events such as touch or keyboard, as +well as displaying the pixels rendered by Slint into a frame- or linebuffer. diff --git a/docs/reference/src/introduction/index.md b/docs/reference/src/introduction/index.md index 6565027ec3f..fb3f59c8f0d 100644 --- a/docs/reference/src/introduction/index.md +++ b/docs/reference/src/introduction/index.md @@ -2,23 +2,138 @@ # Getting Started -Using Slint in your projects needs two components: +Slint is a toolkit for creating reactive and fluent user interfaces across a range of targets, from embedded devices with limited resources to powerful mobile devices and desktop machines. -1. `.slint` files, which contain a textual description of the user interface, written in the Slint language. -2. The programming language of the project where you embed the `.slint` files. +Slint features an easy-to-learn domain-specific language (DSL) that compiles into native code, optimizing for the target device's capabilities. It facilitates collaboration between designers and developers on shared projects and supports business logic development in Rust, C++, JavaScript, or Python. - - Slint supports C++, Rust, and JavaScript. +## Installation -There are three different pathways to get started with Slint: +### Prerequisites -1. [SlintPad](https://slint.dev/editor) - Use this browser-based tool to get a feel for the Slint language. -2. As a **UI Designer**, working with Slint files locally, we recommend the following combination of software tools: +::::{tab-set} +:::{tab-item} Cargo +:sync: rust +:selected: true - - [Visual Studio Code](https://code.visualstudio.com) - - [The Slint for Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=Slint.slint) +```sh +cargo add slint +``` -3. As a **Software Developer**, integrating Slint into a new or existing code base, [follow the quickstart](slint-qs:index.html) and then for more in-depth next steps read the language-specific documentation: +::: - - [C++](slint-cpp:index.html) - - [Rust](slint-rust:index.html) - - [JavaScript](slint-node:index.html) +:::{tab-item} GitHub +:sync: cpp + +```sh +git clone https://github.com/slint-ui/slint.git +``` + +::: + +:::{tab-item} NPM +:sync: nodejs + +```sh +npm init && npm install slint-ui +``` + +::: + +:::{tab-item} PIP +:sync: python + +```sh +pip install slint +``` + +::: + +:::: + +## Setting up Editors + +::::{tab-set} +:::{tab-item} JetBrains IDE + +1. Download and install VS Code +2. Install [Slint VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Slint.slint) + +::: + +:::{tab-item} Kate + +1. Download and install VS Code +2. Install [Slint VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Slint.slint) + +::: + +:::{tab-item} Qt Creator + +1. Download and install VS Code +2. Install [Slint VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Slint.slint) + +::: + +:::{tab-item} Sublime Text + +1. Download and install VS Code +2. Install [Slint VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Slint.slint) + +::: + +:::{tab-item} Vim + +1. Download and install VS Code +2. Install [Slint VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Slint.slint) + +::: + +:::{tab-item} Visual Studio Code +:selected: true + +1. Download and install VS Code +2. Install [Slint VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Slint.slint) + +::: + +:::{tab-item} Zed + +1. Download and install VS Code +2. Install [Slint VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Slint.slint) + +::: + +:::: + +## Start with a Template + +::::{tab-set} +:::{tab-item} C++ +:sync: cpp + +```sh +git clone https://github.com/slint-ui/slint.git +``` + +::: + +:::{tab-item} NodeJS +:sync: nodejs + +```sh +git clone https://github.com/slint-ui/slint.git +``` + +::: + +:::{tab-item} Rust +:sync: rust +:selected: true + +```sh +git clone https://github.com/slint-ui/slint.git +``` + +::: + +:::: diff --git a/docs/reference/src/introduction/supported_platforms.md b/docs/reference/src/introduction/mobile.md similarity index 98% rename from docs/reference/src/introduction/supported_platforms.md rename to docs/reference/src/introduction/mobile.md index 17d15bf9502..65f5fb0ce61 100644 --- a/docs/reference/src/introduction/supported_platforms.md +++ b/docs/reference/src/introduction/mobile.md @@ -1,6 +1,6 @@ -# Supported Platforms +# Build Mobile Applications Slint runs on many desktop and embedded platforms and micro-controllers. diff --git a/docs/reference/src/language/syntax/index.rst b/docs/reference/src/language/syntax/index.rst index 9f9b9990e9f..b2dc8265717 100644 --- a/docs/reference/src/language/syntax/index.rst +++ b/docs/reference/src/language/syntax/index.rst @@ -7,10 +7,8 @@ Syntax .. toctree:: :hidden: :maxdepth: 2 - :caption: Reference + :caption: Reference (Old) - comments.md - identifiers.md types.md properties.md expressions.md diff --git a/docs/reference/src/quickstart/getting_started.md b/docs/reference/src/quickstart/getting_started.md index e9c353b253d..e86a0ddfce0 100644 --- a/docs/reference/src/quickstart/getting_started.md +++ b/docs/reference/src/quickstart/getting_started.md @@ -1,12 +1,20 @@ -# Getting started +# Quickstart -This tutorial shows you how to use the languages that Slint supports as the host programming language. +This tutorial introduces you to the Slint framework in a playful way by implementing a memory game. It combines the Slint language for the graphics with the game rules implemented in C++, Rust, or NodeJS. -We recommend using [our editor integrations for Slint](https://github.com/slint-ui/slint/tree/master/editors) for following this tutorial. +The game consists of a grid of 16 rectangular tiles. Clicking on a tile uncovers an icon underneath. +There are 8 different icons in total, so each tile has a sibling somewhere in the grid with the +same icon. The objective is to locate all icon pairs. The player can uncover two tiles at the same time. If they +aren't the same, the game obscures the icons again. +If the player uncovers two tiles with the same icon, then they remain visible - they're solved. -Slint has application templates you can use to create a project with dependencies already set up that follows recommended best practices. +This is how the game looks in action: + + + + ## Prerequisites diff --git a/docs/reference/src/quickstart/index.rst b/docs/reference/src/quickstart/index.rst deleted file mode 100644 index 25e59a6a741..00000000000 --- a/docs/reference/src/quickstart/index.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. Copyright © SixtyFPS GmbH -.. SPDX-License-Identifier: MIT - -Quickstart -========== - -This tutorial introduces you to the Slint UI framework in a playful way by implementing a memory game. It combines the Slint language for the graphics with the game rules implemented in C++, Rust, or NodeJS. - -The game consists of a grid of 16 rectangular tiles. Clicking on a tile uncovers an icon underneath. -There are 8 different icons in total, so each tile has a sibling somewhere in the grid with the -same icon. The objective is to locate all icon pairs. The player can uncover two tiles at the same time. If they -aren't the same, the game obscures the icons again. -If the player uncovers two tiles with the same icon, then they remain visible - they're solved. - -This is how the game looks in action: - -.. raw:: html - - - -.. toctree:: - :hidden: - :maxdepth: 2 - :caption: Quickstart - - getting_started.md - memory_tile.md - polishing_the_tile.md - from_one_to_multiple_tiles.md - creating_the_tiles.md - game_logic.md - running_in_a_browser.md - ideas_for_the_reader.md - conclusion.md diff --git a/docs/reference/src/language/syntax/comments.md b/docs/reference/src/reference/syntax/comments.md similarity index 100% rename from docs/reference/src/language/syntax/comments.md rename to docs/reference/src/reference/syntax/comments.md diff --git a/docs/reference/src/language/syntax/identifiers.md b/docs/reference/src/reference/syntax/identifiers.md similarity index 100% rename from docs/reference/src/language/syntax/identifiers.md rename to docs/reference/src/reference/syntax/identifiers.md diff --git a/docs/reference/src/reference/syntax/index.rst b/docs/reference/src/reference/syntax/index.rst new file mode 100644 index 00000000000..1d8327f65dc --- /dev/null +++ b/docs/reference/src/reference/syntax/index.rst @@ -0,0 +1,13 @@ +.. Copyright © SixtyFPS GmbH +.. SPDX-License-Identifier: MIT + +Syntax +====== + +.. toctree:: + :hidden: + :maxdepth: 2 + :caption: Syntax + + comments.md + identifiers.md