From dc567f7df93f2e0f9aca07e4f39c0e9d8349f283 Mon Sep 17 00:00:00 2001 From: Iisakki Rotko Date: Mon, 15 Jan 2024 12:34:46 +0100 Subject: [PATCH] fix: links --- CHANGELOG.md | 2 +- CONTRIBUTING.md | 2 +- README.md | 8 +- .../solara_enterprise/auth/components.py | 2 +- solara/__init__.py | 8 +- solara/checks.html | 2 +- solara/components/applayout.py | 8 +- solara/components/button.py | 8 +- solara/components/card.py | 3 +- solara/components/cross_filter.py | 13 +- solara/components/datatable.py | 5 +- solara/components/head.py | 3 +- solara/components/head_tag.py | 5 +- solara/components/link.py | 3 +- solara/components/meta.py | 2 +- solara/components/misc.py | 14 +- solara/hooks/use_reactive.py | 2 +- solara/lab/components/tabs.py | 8 +- solara/reactive.py | 2 +- solara/routing.py | 9 +- solara/website/pages/__init__.py | 2 +- .../website/pages/apps/multipage/__init__.py | 2 +- solara/website/pages/changelog/changelog.md | 2 +- .../pages/docs/content/00-introduction.md | 121 ++++++++++++++++++ .../advanced/content/10-howto/10-multipage.md | 6 +- .../advanced/content/10-howto/20-layout.md | 42 +++--- .../advanced/content/10-howto/40-embed.md | 2 +- .../content/20-understanding/06-ipyvuetify.md | 2 +- .../20-understanding/12-reacton-basics.md | 2 +- .../content/20-understanding/15-anatomy.md | 2 +- .../content/20-understanding/18-containers.md | 6 +- .../content/20-understanding/40-routing.md | 18 +-- .../content/30-enterprise/10-oauth.md | 4 +- .../content/40-development/00-overview.md | 0 .../content/40-development/01-contribute.md | 10 +- .../content/40-development/10-setup.md | 4 +- .../pages/documentation/api/hooks/use_memo.md | 2 +- .../documentation/components/status/error.py | 6 +- .../documentation/components/status/info.py | 6 +- .../components/status/success.py | 6 +- .../components/status/warning.py | 6 +- .../examples/general/deploy_model.py | 6 +- .../examples/general/login_oauth.py | 2 +- .../examples/general/vue_component.py | 3 +- .../examples/libraries/altair.py | 5 +- .../examples/utilities/countdown_timer.py | 2 +- .../examples/visualization/plotly.py | 3 +- .../getting_started/content/00-quickstart.md | 4 +- .../content/01-introduction.md | 30 ++--- .../getting_started/content/02-installing.md | 2 +- .../content/04-tutorials/00-overview.md | 10 +- .../content/04-tutorials/20-web-app.md | 8 +- .../content/04-tutorials/30-ipywidgets.md | 18 +-- .../content/04-tutorials/40-streamlit.md | 26 ++-- .../content/04-tutorials/50-dash.md | 6 +- .../content/05-fundamentals/00-overview.md | 4 +- .../content/05-fundamentals/10-components.md | 4 +- .../05-fundamentals/50-state-management.md | 6 +- .../content/06-reference/41-asset-files.md | 2 +- .../06-reference/60-static-site-generation.md | 2 +- .../content/06-reference/70-search.md | 2 +- .../content/06-reference/80-reloading.md | 6 +- .../content/06-reference/95-caching.md | 2 +- .../content/07-deploying/00-overview.md | 2 +- .../content/07-deploying/10-self-hosted.md | 6 +- solara/website/pages/showcase/solara_dev.py | 2 +- 66 files changed, 316 insertions(+), 207 deletions(-) create mode 100644 solara/website/pages/docs/content/00-introduction.md create mode 100644 solara/website/pages/documentation/advanced/content/40-development/00-overview.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d92b5226..7df3da97e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,5 @@ -This is the old changelog, check the [Solara website](https://solara.dev/docs/changelog) for the up to date changelog. +This is the old changelog, check the [Solara website](https://solara.dev/changelog) for the up to date changelog. ## Changelog for solara v1.22 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b7ac4d2f..909938d82 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1 @@ -Please go to https://solara.dev/docs/howto/contribute for more information. +Please go to https://solara.dev/documentation/advanced/development/contribute for more information. diff --git a/README.md b/README.md index 744c036b4..1b7d1ae12 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Run: pip install solara ``` -Or follow the [Installation instructions](https://solara.dev/docs/installing) for more detailed instructions. +Or follow the [Installation instructions](https://solara.dev/documentation/getting_started/installing) for more detailed instructions. ## First script @@ -73,7 +73,7 @@ Solara server is starting at http://localhost:8765 Or copy-paste this to a Jupyter notebook cell and execute it (the `Page()` expression at the end will cause it to automatically render the component in the notebook). -See this snippet run live at https://solara.dev/docs/quickstart +See this snippet run live at https://solara.dev/documentation/getting_started ## Demo @@ -100,7 +100,7 @@ By building on top of ipywidgets, we automatically leverage an existing ecosyste Visit our main website or jump directly to the introduction -[![Introduction](https://dabuttonfactory.com/button.png?t=Introduction&f=Open+Sans-Bold&ts=20&tc=fff&hp=45&vp=12&c=8&bgt=unicolored&bgc=f19f41)](https://solara.dev/docs) -[![Quickstart](https://dabuttonfactory.com/button.png?t=Quickstart&f=Open+Sans-Bold&ts=20&tc=fff&hp=45&vp=12&c=8&bgt=unicolored&bgc=f19f41)](https://solara.dev/docs/quickstart) +[![Introduction](https://dabuttonfactory.com/button.png?t=Introduction&f=Open+Sans-Bold&ts=20&tc=fff&hp=45&vp=12&c=8&bgt=unicolored&bgc=f19f41)](https://solara.dev/documentation) +[![Quickstart](https://dabuttonfactory.com/button.png?t=Quickstart&f=Open+Sans-Bold&ts=20&tc=fff&hp=45&vp=12&c=8&bgt=unicolored&bgc=f19f41)](https://solara.dev/documentation/getting_started) *Note that the solara.dev website is created using Solara* diff --git a/packages/solara-enterprise/solara_enterprise/auth/components.py b/packages/solara-enterprise/solara_enterprise/auth/components.py index f6b4e4a49..acc7589a5 100644 --- a/packages/solara-enterprise/solara_enterprise/auth/components.py +++ b/packages/solara-enterprise/solara_enterprise/auth/components.py @@ -28,7 +28,7 @@ def Page(): solara.Button("Logout", icon_name="mdi-logout", href=auth.get_logout_url()) ``` - Note that a common use case is to put the avatar in the [AppBar](/api/app_bar). + Note that a common use case is to put the avatar in the [AppBar](/documentation/components/layout/app_bar). ```solara import solara from solara_enterprise import auth diff --git a/solara/__init__.py b/solara/__init__.py index 73984e642..b3ab5cb1f 100644 --- a/solara/__init__.py +++ b/solara/__init__.py @@ -77,10 +77,10 @@ def display(*objs, **kwargs): However, if you require callback functions, use the specific Solara components, e.g.: - * [Plotly](/api/plotly) - * [Altair](/api/altair) - * [Matplotlib](/api/matplotlib) - * [Dataframe](/api/dataframe) + * [Plotly](/documentation/components/viz/plotly) + * [Altair](/documentation/components/viz/altair) + * [Matplotlib](/documentation/components/viz/matplotlib) + * [Dataframe](/documentation/components/viz/dataframe) ```solara import solara diff --git a/solara/checks.html b/solara/checks.html index fa327ef95..062c39b8f 100644 --- a/solara/checks.html +++ b/solara/checks.html @@ -60,7 +60,7 @@ const div = document.createElement("div") const div2 = document.createElement("div") div.innerHTML = `Run ${jupyter_python_executable} -m pip install ${needsInstall.join(" ")}. Refresh the page after installation.` - div2.innerHTML = `Visit https://solara/dev/docs/troubleshoot for more information.` + div2.innerHTML = `Visit https://solara/dev/documentation/getting_started/troubleshoot for more information.` rootEl.appendChild(div) rootEl.appendChild(div2) } diff --git a/solara/components/applayout.py b/solara/components/applayout.py index 1a9f9b1da..5a40ee498 100644 --- a/solara/components/applayout.py +++ b/solara/components/applayout.py @@ -90,7 +90,7 @@ def AppBar(children=[]): This component does not need to be a direct child of the AppLayout, it can be at any level in your component tree. - If a [Tabs](/api/tabs) component is used as direct child of the app bar, it will be shown under the app bar. + If a [Tabs](/documentation/components/lab/tabs) component is used as direct child of the app bar, it will be shown under the app bar. ## Example showing an app bar ```solara @@ -204,8 +204,8 @@ def AppLayout( ): """The default layout for Solara apps. It consists of an toolbar bar, a sidebar and a main content area. - * The title of the app is set using the [Title](/api/title) component. - * The sidebar content is set using the [Sidebar](/api/sidebar) component. + * The title of the app is set using the [Title](/documentation/components/page/title) component. + * The sidebar content is set using the [Sidebar](/documentation/components/layout/sidebar) component. * The content is set by the `Page` component provided by the user. This component is usually not used directly, but rather through via the [Layout system](/documentation/advanced/howto/layout). @@ -224,7 +224,7 @@ def AppLayout( * `children`: The children of the AppLayout. The first child is used as the sidebar content, the rest as the main content. * `sidebar_open`: Whether the sidebar is open or not. - * `title`: The title of the app shown in the app bar, can also be set using the [Title](/api/title) component. + * `title`: The title of the app shown in the app bar, can also be set using the [Title](/documentation/components/page/title) component. * `toolbar_dark`: Whether the toolbar should be dark or not. * `navigation`: Whether the navigation tabs based on routing should be shown. * `color`: The color of the toolbar. diff --git a/solara/components/button.py b/solara/components/button.py index dd9a2a219..d2225760c 100644 --- a/solara/components/button.py +++ b/solara/components/button.py @@ -1,10 +1,9 @@ from typing import Callable, Dict, List, Optional, Union -from reacton import ipyvue -from reacton import ipyvuetify as v - import solara import solara.util +from reacton import ipyvue +from reacton import ipyvuetify as v @solara.component @@ -51,7 +50,8 @@ def Page(): - `disabled`: Whether the button is disabled. - `text`: Whether the button should be displayed as text, it has no shadow and no background. - `outlined`: Whether the button should be displayed as outlined, it has no background. - - `value`: (Optional) When used as a child of a ToggleButtons component, the value of the selected button, see [ToggleButtons](/api/togglebuttons). + - `value`: (Optional) When used as a child of a ToggleButtons component, the value of the selected button, see + [ToggleButtons](/documentation/components/input/togglebuttons). - `classes`: Additional CSS classes to apply. - `style`: CSS style to apply. diff --git a/solara/components/card.py b/solara/components/card.py index 3d6570b76..f61253054 100644 --- a/solara/components/card.py +++ b/solara/components/card.py @@ -1,7 +1,6 @@ from typing import Dict, List, Optional, Union import reacton.ipyvuetify as v - import solara from solara.util import _combine_classes @@ -79,7 +78,7 @@ def Page(): def CardActions(children: List[solara.Element] = []): """Container for actions in a card. - See [Card](/api/card) for an example. + See [Card](/documentation/components/layout/card) for an example. # Arguments diff --git a/solara/components/cross_filter.py b/solara/components/cross_filter.py index e39f0ef77..8ce8407ce 100644 --- a/solara/components/cross_filter.py +++ b/solara/components/cross_filter.py @@ -3,9 +3,8 @@ import ipyvuetify import reacton.ipyvuetify as v -import traitlets - import solara +import traitlets from solara import CellAction, ColumnAction from ..lab.hooks.dataframe import use_df_column_names @@ -55,7 +54,7 @@ def CrossFilterSelect( ): """A Select widget that will cross filter a DataFrame. - See [use_cross_filter](/api/use_cross_filter) for more information about how to use cross filtering. + See [use_cross_filter](/documentation/api/hooks/use_cross_filter) for more information about how to use cross filtering. ## Arguments @@ -170,7 +169,7 @@ def CrossFilterReport(df, classes: List[str] = []): Shows number of rows filtered, and the total number of rows. - See [use_cross_filter](/api/use_cross_filter) for more information about how to use cross filtering. + See [use_cross_filter](/documentation/api/hooks/use_cross_filter) for more information about how to use cross filtering. ## Arguments @@ -214,7 +213,7 @@ def CrossFilterSlider( ): """A Slider widget that will cross filter a DataFrame. - See [use_cross_filter](/api/use_cross_filter) for more information about how to use cross filtering. + See [use_cross_filter](/documentation/api/hooks/use_cross_filter) for more information about how to use cross filtering. ## Arguments @@ -318,9 +317,9 @@ def update_filter(): def CrossFilterDataFrame(df, items_per_page=20, column_actions: List[ColumnAction] = [], cell_actions: List[CellAction] = [], scrollable=False): """Display a DataFrame with filters applied from the cross filter. - This component wraps [DataFrame](/api/dataframe). + This component wraps [DataFrame](/documentation/components/data/dataframe). - See [use_cross_filter](/api/use_cross_filter) for more information about how to use cross filtering. + See [use_cross_filter](/documentation/api/hooks/use_cross_filter) for more information about how to use cross filtering. # Arguments diff --git a/solara/components/datatable.py b/solara/components/datatable.py index 07fefe0d8..5c04d1133 100644 --- a/solara/components/datatable.py +++ b/solara/components/datatable.py @@ -6,11 +6,10 @@ import ipyvuetify as v import ipywidgets -import traitlets - import solara import solara.hooks.dataframe import solara.lab +import traitlets from solara.lab.hooks.dataframe import use_df_column_names from solara.lab.utils.dataframe import df_type @@ -208,7 +207,7 @@ def Page(): * `cell_actions` - Triggered via clicking on the triple dot icon in the cell (visible when hovering). * `on_column_header_hover` - Optional callback when the user hovers over the triple dot icon on a header. * `column_header_info` - Element to display in the column menu popup (visible when hovering), provide an - empty container element (like [Column](/api/column)) to force showing the trigle dot icon (see example). + empty container element (like [Column](/documentation/components/layout/column)) to force showing the trigle dot icon (see example). """ return DataTable( diff --git a/solara/components/head.py b/solara/components/head.py index 466fe5469..2d82f4664 100644 --- a/solara/components/head.py +++ b/solara/components/head.py @@ -1,7 +1,6 @@ from typing import List import reacton - import solara @@ -9,7 +8,7 @@ def Head(children: List[reacton.core.Element] = []): """A component that manager the "head" tag of the page to avoid duplicate tags, such as titles. - Currently only supports the [title](/api/title) tag as child, e.g.: + Currently only supports the [title](/documentation/components/page/title) tag as child, e.g.: ```python import solara diff --git a/solara/components/head_tag.py b/solara/components/head_tag.py index d478b7a7e..59b9c2fe7 100644 --- a/solara/components/head_tag.py +++ b/solara/components/head_tag.py @@ -2,9 +2,8 @@ import ipyvuetify as vy import reacton.core -import traitlets - import solara +import traitlets class HeadTagWidget(vy.VuetifyTemplate): @@ -19,7 +18,7 @@ class HeadTagWidget(vy.VuetifyTemplate): def HeadTag(tagname: str, key=None, attributes: Optional[dict] = None): """Add a child element to head element, or replace a meta tag with the same tagname and key. - This component should be used inside a [Head](/api/head) component, e.g.: + This component should be used inside a [Head](/documentation/components/page/head) component, e.g.: ```python import solara diff --git a/solara/components/link.py b/solara/components/link.py index 82942d7b5..2b8b0a5ca 100644 --- a/solara/components/link.py +++ b/solara/components/link.py @@ -2,7 +2,6 @@ import ipyvue as vue import reacton.ipyvue as vuer - import solara @@ -32,7 +31,7 @@ def Link( ## Arguments * path_or_route: the path or route to navigate to. Paths should be absolute, e.g. '/fruit/banana'. - If a route is given, [`resolve_path`](/api/resolve_path)] will be used to resolve to the absolute path. + If a route is given, [`resolve_path`](/documentation/api/routing/resolve_path)] will be used to resolve to the absolute path. * children: the children of the link. If a child is clicked, the link will be followed. * nofollow: If True, the link will not be followed by web crawlers (such as google). * style: CSS styles to apply to the HTML link element. Either a string or a dictionary. diff --git a/solara/components/meta.py b/solara/components/meta.py index 02a11e89b..381bdcaf9 100644 --- a/solara/components/meta.py +++ b/solara/components/meta.py @@ -9,7 +9,7 @@ def Meta(name: Optional[str] = None, property: Optional[str] = None, content: Optional[str] = None): """Add a meta tag to the head element, or replace a meta tag with the same name and or property. - This component should be used inside a [Head](/api/head) component, e.g.: + This component should be used inside a [Head](/documentation/components/page/head) component, e.g.: ```python import solara diff --git a/solara/components/misc.py b/solara/components/misc.py index 5419783a7..83ac41f51 100644 --- a/solara/components/misc.py +++ b/solara/components/misc.py @@ -3,7 +3,6 @@ import reacton import reacton.ipyvuetify as v - import solara import solara.widgets from solara.util import _combine_classes @@ -159,7 +158,7 @@ def HBox(children=[], grow=True, align_items="stretch", classes: List[str] = []) def Row(children=[], gap="12px", justify="start", margin: int = 0, classes: List[str] = [], style: Union[str, Dict[str, str], None] = None): """Lays out children in a row, side by side, with the given gap between them. - See also [Column](/api/column). + See also [Column](/documentation/components/layout/column). Example with three children side by side: @@ -200,7 +199,7 @@ def Page(): def Column(children=[], gap="12px", align="stretch", margin: int = 0, classes: List[str] = [], style: Union[str, Dict[str, str], None] = None): """Lays out children in a column on top of each other, with the given gap between them. - See also [Row](/api/row). + See also [Row](/documentation/components/layout/row). Example with three children on top of each other: @@ -287,17 +286,14 @@ def on_points_callback(data): "plotly_hover": on_hover, "plotly_unhover": on_unhover, "plotly_selected": on_selection, - "plotly_deselect": on_deselect + "plotly_deselect": on_deselect, } - + callback = event_mapping.get(event_type) if callback: callback(data) - fig_element = FigureWidget.element( - on__js2py_pointsCallback=on_points_callback, - on__js2py_relayout=on_relayout - ) + fig_element = FigureWidget.element(on__js2py_pointsCallback=on_points_callback, on__js2py_relayout=on_relayout) def update_data(): fig_widget: FigureWidget = solara.get_widget(fig_element) diff --git a/solara/hooks/use_reactive.py b/solara/hooks/use_reactive.py index fa70a7743..2bfc0778c 100644 --- a/solara/hooks/use_reactive.py +++ b/solara/hooks/use_reactive.py @@ -92,7 +92,7 @@ def MyComponent(value: Union[T, solara.Reactive[T]], except RuntimeError as e: raise RuntimeError( "use_reactive must be called from a component function, inside the render function.\n" - "Do not call it top level, use [solara.reactive()](https://solara.dev/api/reactive) instead." + "Do not call it top level, use [solara.reactive()](https://solara.dev/documentation/api/utilities/reactive) instead." ) from e on_change_ref.current = on_change diff --git a/solara/lab/components/tabs.py b/solara/lab/components/tabs.py index d6c8422ff..dd58c116b 100644 --- a/solara/lab/components/tabs.py +++ b/solara/lab/components/tabs.py @@ -19,7 +19,7 @@ def Tab( (*Note: [This component is experimental and its API may change in the future](documentation/getting_started/lab).*) - Should be a direct child of a [Tabs](/api/tabs). + Should be a direct child of a [Tabs](/documentation/components/lab/tabs). ## Arguments * `label`: The label of the tab. @@ -64,10 +64,10 @@ def Tabs( (*Note: [This component is experimental and its API may change in the future](documentation/getting_started/lab).*) - Note that if Tabs are used as a child of the [AppBar](/api/appbar) component, the tabs + Note that if Tabs are used as a child of the [AppBar](/documentation/components/layout/app_bar) component, the tabs will be placed under the app bar. See our [authorization app](/apps/authorization) for an example. - If the children [Tab](/api/tab) elements are passed a `path_or_route` argument, the active tab + If the children [Tab](/documentation/components/lab/tab) elements are passed a `path_or_route` argument, the active tab will be based on the path of the current page. @@ -89,7 +89,7 @@ def Page(): ### Tabs with content - This is usually only used when the tabs are placed in the [AppBar](/api/appbar) component. + This is usually only used when the tabs are placed in the [AppBar](/documentation/components/layout/app_bar) component. ```solara import solara diff --git a/solara/reactive.py b/solara/reactive.py index 4da960070..6ecb0558d 100644 --- a/solara/reactive.py +++ b/solara/reactive.py @@ -14,7 +14,7 @@ def reactive(value: T) -> Reactive[T]: Solara web applications. They provide an easy-to-use mechanism for keeping track of the changing state of data and for propagating those changes to the appropriate UI components. For managing local or component-specific - state, consider using the [`solara.use_state()`](/api/use_state) function. + state, consider using the [`solara.use_state()`](/documentation/api/hooks/use_state) function. Reactive variables can be accessed using the `.value` attribute. To modify diff --git a/solara/routing.py b/solara/routing.py index 50a2ed6a0..d393bd9c1 100644 --- a/solara/routing.py +++ b/solara/routing.py @@ -123,7 +123,7 @@ def Page(): router = solara.use_router() def redirect(): - router.push(f"/api/use_route") + router.push(f"/documentation/api/routing/use_route") solara.Button("Navigate using an event", on_click=redirect) ``` @@ -166,9 +166,10 @@ def use_route( Note that all routes are relative, since a component does not know if it is embedded into a larger application, which may also do routing. Therefore you should never use the `route.path` for navigation since the route object has no knowledge of the full url - (e.g. `/api/use_route/fruit/banana`) but only knows its small piece of the pathname (e.g. `banana`) + (e.g. `/documentation/api/routing/use_route/fruit/banana`) but only knows its small piece of the pathname (e.g. `banana`) - Use [`resolve_path`](/api/resolve_path) to request the full url for navigation, or simply use the `Link` component that can do this for us. + Use [`resolve_path`](/documentation/api/routing/resolve_path) to request the full url for navigation, + or simply use the `Link` component that can do this for us. If the current route has children, any child component that calls `use_route` will return the matched route and its siblings of our children. @@ -229,7 +230,7 @@ def resolve_path(path_or_route: Union[str, solara.Route], level=0) -> str: ## Arguments - * path_or_route: a path string or a [`solara.Route`](/api/route) object to resolve. + * path_or_route: a path string or a [`solara.Route`](/documentation/api/routing/route) object to resolve. ## See also diff --git a/solara/website/pages/__init__.py b/solara/website/pages/__init__.py index 415fa6266..bdcb6b14e 100644 --- a/solara/website/pages/__init__.py +++ b/solara/website/pages/__init__.py @@ -126,7 +126,7 @@ def Layout(children=[]): ) with solara.HBox(): with solara.Link("/documentation"): - solara.Button(label="Read more", class_="ma-1 homepage-button", href="/docs", color="primary", dark=True) + solara.Button(label="Read more", class_="ma-1 homepage-button", href="/documentation", color="primary", dark=True) with solara.Link("/documentation/getting_started/quickstart"): solara.Button(label="Quickstart", class_="ma-1 homepage-button", color="primary", dark=True) # with rv.Col(md=4, sm=5): diff --git a/solara/website/pages/apps/multipage/__init__.py b/solara/website/pages/apps/multipage/__init__.py index 2fe8debea..e5387949b 100644 --- a/solara/website/pages/apps/multipage/__init__.py +++ b/solara/website/pages/apps/multipage/__init__.py @@ -12,7 +12,7 @@ def SharedComponent(): f""" This component will be used on each page. - It uses the `app_state` [reactive variable](https://solara.dev/api/reactive) + It uses the `app_state` [reactive variable](https://solara.dev/documentation/api/utilities/reactive) so that the state outlives each page diff --git a/solara/website/pages/changelog/changelog.md b/solara/website/pages/changelog/changelog.md index 1cb430bd0..971c4b00c 100644 --- a/solara/website/pages/changelog/changelog.md +++ b/solara/website/pages/changelog/changelog.md @@ -123,7 +123,7 @@ ### Highlights * Feature: Solara now has a production mode (enabled by passing in `--production`) which will load optimized CSS and JS and disable hot reloading. - Our [Solara server](https://solara.dev/docs/understanding/solara-server) page contains more information about it. If you used `--reload` or + Our [Solara server](https://solara.dev/documentation/advanced/understanding/solara-server) page contains more information about it. If you used `--reload` or `--dev` before you can now use the `-a/--auto-restart` flat. The `--dev` and `--reload` flags are kept for backwards compatibility. * Feature: All `Input` components expose the `style` and `classes` arguments for custom styling. * Feature: New component: [`InputDate` and `InputDateRange`](https://solara.dev/api/input_date) which use a datepicker in a menu. (#326) diff --git a/solara/website/pages/docs/content/00-introduction.md b/solara/website/pages/docs/content/00-introduction.md new file mode 100644 index 000000000..175c5f6bb --- /dev/null +++ b/solara/website/pages/docs/content/00-introduction.md @@ -0,0 +1,121 @@ +# Introduction + + +## What is Solara? + +Solara is an Open Source library that lets you use and build data-focused web apps (data apps) using reusable UI components. Your app will work in the Jupyter notebook and production-grade web frameworks (FastAPI, Starlette, Flask, ...). + +Solara uses proven technologies and mature standards. Grow from a one-off experiment in the Jupyter notebook to a dynamic data portal in production. Built on top of [Reacton](/documentation/advanced/understanding/reacton) to keep your code complexity under control and [IPywidgets](/documentation/advanced/understanding/ipywidgets) to access a rich set of UI libraries without having to write Javascript or CSS. + +We care about developer experience. Solara will give your hot code reloading and type hints for faster development. + +## Why is Solara created? + +How much time have you wasted investing in a web framework only to find out that what you need is impossible to do? + +Many frameworks only solve a specific set of problems. Once you step outside of the paved path, you get stuck. + +On the other extreme, you might be working with a library with no clear patterns that let you do anything. You may only be weeks away from a total code complexity nightmare, which slowly kills your project. + +At the same time, starting a new framework from scratch would be unwise. We prefer to build on top of solid, battle-tested libraries, such as [IPywidgets](/documentation/advanced/understanding/ipywidgets). + +## Why use Solara? + +Instead of inventing a new API with an unknown track record, we take a different approach. We look at the JavaScript world. React is a technology that has proven itself for many years. It has shown to be a good all-around model for building complex UIs. + +[Reacton](/documentation/advanced/understanding/reacton) is the equivalent of ReactJS for Python (and IPywidgets). It allows us to use the same reusable components and hooks as in the ReactJS ecosystem. Using Reacton, we build web/data applications without suffering from complex code bases. + +Looking again at the JavaScript world, we see software such as NextJS is putting a framework around ReactJS. NextJS is more opinionated than ReactJS and adds more "batteries" such as routing. + +Solara plays a similar role as NextJS. It builds on top of Reacton but handles things like routing for you. + +But Solara is also different and is even more opinionated than NextJS. The reason for this is its focus on the data-heavy Python ecosystem. For this reason, it comes with many components and hooks that make building beautiful data apps easier (see our [Documentation](/documentation)). + +Solara is a clear, systematic, Python-based web framework using industry-trusted technology. Smooth developer experience and enforced code modularity will allow you to build a data app at any scale while maintaining simple code. + +## A quick Solara example + +For your understanding, it might be good just to run an example. + +Follow the [installation instructions](/documentation/getting_started/installing) or do the TLDR: + + $ pip install solara + + +Create a file `myapp.py`, or put the following code in the Jupyter notebook: + +```solara +import solara + +clicks = solara.reactive(0) + + +@solara.component +def Page(): + def increase_clicks(): + clicks.value += 1 + + solara.Button(label=f"Clicked {clicks} times", on_click=increase_clicks) + +# in the Jupyter notebook, uncomment the next line: +# display(Page()) +``` + +*Note that the above output is __live__, you can click the button and see the behaviour*. + +Run solara-server (if *not* using the Jupyter notebook) + + $ solara run myapp.py + Solara server is starting at http://localhost:8765 + +The browser should open http://127.0.0.1:8765 + + + + +## How does Solara fit into the big picture? + +Solara is actually two things. + +### Solara server +[Solara server](/documentation/advanced/understanding/solara-server) renders ipywidgets in the browser in a very efficient manner and takes care of many other things +such as [routing](/documentation/advanced/understanding/routing) and [Static Site Generation](/documentation/getting_started/reference/static-site-generation). + +### Solara UI + +The UI part is built on top of [Reacton](/documentation/advanced/understanding/reacton), which uses the existing IPyWidgets stack. It gives a consistent set +of modern UI components with the Material Design look, as well as a set of routines to make application development of data heavy web apps +easier. + + +### Overview +If you use Jupyter, then you probably use the Jupyter notebook, Lab, or [Voila](/documentation/advanced/understanding/voila) to get your widgets into the browser. You may not care about [Solara server](/documentation/advanced/understanding/solara-server) and can focus on just the UI part. + +If you don't use Jupyter, don't know what it is, or are an ML Ops, Dev Ops, or Sys Admin, you are probably more interested in the Solara server. + +![Solara stack](https://dxhl76zpt6fap.cloudfront.net/public/docs/solara-stack.webp) + +## How do I learn Solara? + +We recommend going through the documentation linearly following the arrows on the bottom, meaning you will go through: + + * [Installing](/documentation/getting_started/installing) + * [Quick start](/documentation/getting_started) + * [Tutorials](/documentation/getting_started/tutorials) + +If you want to know more about specific parts, you can go through the [How-to section](/documentation/advanced/howto) to learn more. Feel free to skip chapters, and go back to topics when you need to. + + +If you want to know what components or hooks are available, or want to know more about a specific component, check out the [Documentation](/documentation) which includes live code examples. Other reference documentation can be found at the [reference section](/documentation/getting_started/reference) + +If you feel like you miss some basic understanding and want to give a bit deeper into the what and why feel free to explore the [Understanding section](/documentation/advanced/understanding). + + +[Our examples](/examples) may help you see how particular problems can be solved using Solara, or as inspiration. If you want to contribute an example, contact us on GitHub or directly open a [Pull Request](https://github.com/widgetti/solara/). + + +## Where can I hire an expert? + +If you need consulting, training or development, you can reach us at: + +contact@solara.dev diff --git a/solara/website/pages/documentation/advanced/content/10-howto/10-multipage.md b/solara/website/pages/documentation/advanced/content/10-howto/10-multipage.md index b71623c2d..c6842c96c 100644 --- a/solara/website/pages/documentation/advanced/content/10-howto/10-multipage.md +++ b/solara/website/pages/documentation/advanced/content/10-howto/10-multipage.md @@ -1,6 +1,6 @@ # Multi-page support -In the [Web App tutorial](/docs/tutorial/web-app), we created an application consisting of a single page. Web applications generally have multiple pages, and Solara supports this as well. +In the [Web App tutorial](/documentation/getting_started/tutorials/web-app), we created an application consisting of a single page. Web applications generally have multiple pages, and Solara supports this as well. ## Multiple scripts @@ -148,7 +148,7 @@ routes = [ ] ``` -See more details in the [Route section](/docs/understanding/routing). +See more details in the [Route section](/documentation/advanced/understanding/routing). ## Dynamic pages @@ -189,4 +189,4 @@ By giving the name argument a default value of `"foo"`, Solara will also accept # What next? - * Also check out the [Multipage example](/apps/multipage) for more inspiration. + * Also check out the [Multipage example](/documentation/examples/fullscreen/multipage) for more inspiration. diff --git a/solara/website/pages/documentation/advanced/content/10-howto/20-layout.md b/solara/website/pages/documentation/advanced/content/10-howto/20-layout.md index df33ac5af..1842812ad 100644 --- a/solara/website/pages/documentation/advanced/content/10-howto/20-layout.md +++ b/solara/website/pages/documentation/advanced/content/10-howto/20-layout.md @@ -33,29 +33,29 @@ def Page(): solara.Info("two per column on small screens, three per column on large screens") ``` -[Navigate here to watch this layout in a full browser window](/apps/layout-demo) +[Navigate here to watch this layout in a full browser window](/documentation/examples/fullscreen/layout_demo) The key takeaways are: - * By default, Solara will wrap your component in an [AppLayout](/api/app_layout), which will give you: - * Room for a sidebar, that you can populate using the [Sidebar](/api/sidebar) component. - * A toolbar showing the [Title](/api/title). - * Not visible here: In the case of [multiple pages](/docs/howto/multipage) will include page navigation tabs. See [The multipage demo app](/app/multipage) for an example. - * Use [Card](/api/card) to put related components together with a title. - * Use [Column](/api/column) to simply layout components under each other. - * Use [Columns](/api/columns) if you want to have a few columns with relative sizes next to each other. - * Use [ColumnsResponsive](/api/columns_responsive) to have the column widths respond to screen size. + * By default, Solara will wrap your component in an [AppLayout](/documentation/components/layout/app_layout), which will give you: + * Room for a sidebar, that you can populate using the [Sidebar](/documentation/components/layout/sidebar) component. + * A toolbar showing the [Title](/documentation/components/page/title). + * Not visible here: In the case of [multiple pages](/documentation/advanced/howto/multipage) will include page navigation tabs. See [The multipage demo app](/documentation/examples/fullscreen/multipage) for an example. + * Use [Card](/documentation/components/layout/card) to put related components together with a title. + * Use [Column](/documentation/components/layout/column) to simply layout components under each other. + * Use [Columns](/documentation/components/layout/columns) if you want to have a few columns with relative sizes next to each other. + * Use [ColumnsResponsive](/documentation/components/layout/columns_responsive) to have the column widths respond to screen size. ## Changing the default layout -While [AppLayout](/api/app_layout) may be sufficient in 80% of the cases. Solara provides a way to change this default layout in [Solara server](/docs/understanding/solara-server). +While [AppLayout](/documentation/components/layout/app_layout) may be sufficient in 80% of the cases. Solara provides a way to change this default layout in [Solara server](/documentation/advanced/understanding/solara-server). You can define your own `Layout` component in the `__init__.py` file in the same directory of your app script. -For instance, putting the following `Layout` component in `__init__.py` will give you effectively the same [AppLayout](/api/app_layout): +For instance, putting the following `Layout` component in `__init__.py` will give you effectively the same [AppLayout](/documentation/components/layout/app_layout): ```python @solara.component def Layout(children=[]): @@ -80,7 +80,7 @@ This layout leaves every page responsible for creating its own header, footer, a ### Layout with navigation In case you want to set up your own layout system, which sets up navigation as well, this example may get you started. It may help -to [understand routing](/docs/understanding/routing). +to [understand routing](/documentation/advanced/understanding/routing). ```python @solara.component def Layout(children=[]): @@ -108,13 +108,13 @@ This is useful for larger apps where each subdirectory may add a bit of layout/c ## Components -The following [Container components](/docs/understanding/containers) can be used to define the layout of you app. +The following [Container components](/documentation/advanced/understanding/containers) can be used to define the layout of you app. - * [Row](/api/row) - * [Column](/api/column) - * [ColumnsResponsive](/api/columns_responsive) - * [GridFixed](/api/gridfixed) - * [GridDraggable](/api/griddraggable) - * [VBox](/api/vbox) (kept for ipywidgets compatibility, please use Column) - * [HBox](/api/hbox) (kept for ipywidgets compatibility, please use Row) - * [AppLayout](/api/app_layout) Not often used directly, since Solara will already wrap your page in it. Sometimes re-used in a new `Layout` component. + * [Row](/documentation/components/layout/row) + * [Column](/documentation/components/layout/column) + * [ColumnsResponsive](/documentation/components/layout/columns_responsive) + * [GridFixed](/documentation/components/layout/gridfixed) + * [GridDraggable](/documentation/components/layout/griddraggable) + * [VBox](/documentation/components/layout/vbox) (kept for ipywidgets compatibility, please use Column) + * [HBox](/documentation/components/layout/hbox) (kept for ipywidgets compatibility, please use Row) + * [AppLayout](/documentation/components/layout/app_layout) Not often used directly, since Solara will already wrap your page in it. Sometimes re-used in a new `Layout` component. diff --git a/solara/website/pages/documentation/advanced/content/10-howto/40-embed.md b/solara/website/pages/documentation/advanced/content/10-howto/40-embed.md index e76cd2b10..59f20e3fb 100644 --- a/solara/website/pages/documentation/advanced/content/10-howto/40-embed.md +++ b/solara/website/pages/documentation/advanced/content/10-howto/40-embed.md @@ -40,4 +40,4 @@ Solara uses a cookie to implement sessions. To support cookies settings in an if ## Embed into an existing page -If embedding into an iframe does not suit your needs (for example, dialogs not being fullscreen), [please contact us](/docs/contact) and we can discuss other options. +If embedding into an iframe does not suit your needs (for example, dialogs not being fullscreen), [please contact us](/contact) and we can discuss other options. diff --git a/solara/website/pages/documentation/advanced/content/20-understanding/06-ipyvuetify.md b/solara/website/pages/documentation/advanced/content/20-understanding/06-ipyvuetify.md index 1ef39d369..f37f4f608 100644 --- a/solara/website/pages/documentation/advanced/content/20-understanding/06-ipyvuetify.md +++ b/solara/website/pages/documentation/advanced/content/20-understanding/06-ipyvuetify.md @@ -11,7 +11,7 @@ material design based widgets. ## Reacton and ipyvuetify -We consider ipyvuetify one of the most essential ipywidget libraries, and that is the reason why [Reacton](/docs/understanding/reacton) ships with +We consider ipyvuetify one of the most essential ipywidget libraries, and that is the reason why [Reacton](/documentation/advanced/understanding/reacton) ships with generated ipyvuetify components to make your app type safe. ```solara diff --git a/solara/website/pages/documentation/advanced/content/20-understanding/12-reacton-basics.md b/solara/website/pages/documentation/advanced/content/20-understanding/12-reacton-basics.md index 82e07c62b..0de513ffe 100644 --- a/solara/website/pages/documentation/advanced/content/20-understanding/12-reacton-basics.md +++ b/solara/website/pages/documentation/advanced/content/20-understanding/12-reacton-basics.md @@ -90,7 +90,7 @@ In words 1. Solara create `el = ButtonClick()` from your component. 1. The `display(el)` triggers the call to Reacton. 1. The render call enters the render phase, which will call the function body (which we call render function) of the `ButtonClick` component. - 1. Our ButtonClick render function calls [`use_state`](/api/use_state). Because this is our first render phase, this returns the initial value (0). + 1. Our ButtonClick render function calls [`use_state`](/documentation/api/hooks/use_state). Because this is our first render phase, this returns the initial value (0). 1. The ButtonClick render function returns a Button element (not a widget!) with `description="Clicked: 0 times"`. 1. The Reacton render call is done with the render phase, and enters the reconciliation phase, where it looks at the difference between the real widgets and the virtual widgets tree (represented by the Reacton elements). We find there is no previous widget associated with the virtual widget (or element) and decide to create a widget. 1. Asynchronously via the Jupyter protocol, a widget model and view are created and displayed to the user in the browser. diff --git a/solara/website/pages/documentation/advanced/content/20-understanding/15-anatomy.md b/solara/website/pages/documentation/advanced/content/20-understanding/15-anatomy.md index 231e835ea..93ddb698f 100644 --- a/solara/website/pages/documentation/advanced/content/20-understanding/15-anatomy.md +++ b/solara/website/pages/documentation/advanced/content/20-understanding/15-anatomy.md @@ -9,7 +9,7 @@ As a reference, we provide this "anatomy" image of our favorite `ClickButton` co * Import `solara` and you also get the `reacton` namespace with it (saves typing, and finding/remembering which hooks is in which packages) * Add a `@solara.component` decorator to turn your function into a component. - * Start with `use_state` hooks and other hooks. This avoids issues with [conditional hooks](/docs/understanding/rules-of-hooks) or hooks in loops. + * Start with `use_state` hooks and other hooks. This avoids issues with [conditional hooks](/documentation/advanced/understanding/rules-of-hooks) or hooks in loops. * Data/state flows down (to children) * Information (events, data) flows up from children via events and callbacks (`on_=my_callback`). * If you need multiple components, use a [parent container component](/api#layout) as context manager. A good default name to give this context manager is `main`. Don't forget to return it in your render function! diff --git a/solara/website/pages/documentation/advanced/content/20-understanding/18-containers.md b/solara/website/pages/documentation/advanced/content/20-understanding/18-containers.md index b44b586a5..83b0b4112 100644 --- a/solara/website/pages/documentation/advanced/content/20-understanding/18-containers.md +++ b/solara/website/pages/documentation/advanced/content/20-understanding/18-containers.md @@ -51,7 +51,7 @@ Page = FancyClickButton ``` -Here we use an [HBox](/api/hbox) to lay out two child components horizontally. +Here we use an [HBox](/documentation/components/layout/hbox) to lay out two child components horizontally. ## Cleaner way to add children to containers @@ -96,7 +96,7 @@ with some_named_context_manager() as this_is_my_name: print("some other code") ``` -Where the last example assigns the context manager to a variable. In Solara we only need to do that to the top context manager, since we need to return that in our [render function](/docs/understanding/anatomy). +Where the last example assigns the context manager to a variable. In Solara we only need to do that to the top context manager, since we need to return that in our [render function](/documentation/advanced/understanding/anatomy). All Reacton or Solara components return elements that can be used as context managers. Context managers allow for code to be executed before and after your code block inside of the context manager. This allows us to capture all elements created inside of the context manager. If you want to know more about context managers, consult the Python documentation since this is not Solara specific. @@ -138,7 +138,7 @@ Page = FancyClickButton Instead of returning the main container, Solara also allows you to not have a return value (or return `None`). If that is the case, Solara will look at what elements you created. If you created one, that element will be taken as a return value instead. If you make more than one element, those elements will be automatically wrapped by -a [Column](/api/column). The only benefit of returning an element, is that we can infer the correct return type, +a [Column](/documentation/components/layout/column). The only benefit of returning an element, is that we can infer the correct return type, which can be useful for testing purposes. Users should probably never return an element, but use the automatic container feature. diff --git a/solara/website/pages/documentation/advanced/content/20-understanding/40-routing.md b/solara/website/pages/documentation/advanced/content/20-understanding/40-routing.md index 743395b4c..5d6db05e4 100644 --- a/solara/website/pages/documentation/advanced/content/20-understanding/40-routing.md +++ b/solara/website/pages/documentation/advanced/content/20-understanding/40-routing.md @@ -13,15 +13,15 @@ Setting up routing can be repetitive, and therefore Solara comes also with a mor ### Based on a directory -Using [`generate_routes_directory(path: Path) -> List[solara.Route]:`](/api/generate_routes_directory) we can request Solara to give us a list of +Using [`generate_routes_directory(path: Path) -> List[solara.Route]:`](/documentation/api/routing/generate_routes_directory) we can request Solara to give us a list of routes by scanning a directory for Python scripts, Notebooks and Markdown files. -This function is being used by Solara if you run solara server with a directory as argument name, as used in [our Multi Page guide](/docs/howto/multipage). More details can be found there. +This function is being used by Solara if you run solara server with a directory as argument name, as used in [our Multi Page guide](/documentation/advanced/howto/multipage). More details can be found there. ### Based on a Python package -Similar to the previous section [`generate_routes(module: ModuleType) -> List[solara.Route]:`](/api/generate_routes) will return a list of routes by scanning a Python package or module for `Page` components, or `app` elements. Again, more information can be found at [our Multi Page guide](/docs/howto/multipage). +Similar to the previous section [`generate_routes(module: ModuleType) -> List[solara.Route]:`](/documentation/api/routing/generate_routes) will return a list of routes by scanning a Python package or module for `Page` components, or `app` elements. Again, more information can be found at [our Multi Page guide](/documentation/advanced/howto/multipage). ## Manually defining routes @@ -59,7 +59,7 @@ routes = [ ### Defining route components -If you do define a `Page` component, you are fully responsible for how routing is done, but we recommend using [use_route](/api/use_route). +If you do define a `Page` component, you are fully responsible for how routing is done, but we recommend using [use_route](/documentation/api/routing/use_route). An example route definition could be something like this: @@ -180,9 +180,9 @@ routes = [ ] ``` -In the case where you did not specify a `Page` component, label is used for the [Title](/api/title) component. +In the case where you did not specify a `Page` component, label is used for the [Title](/documentation/components/page/title) component. -If you need to store more data in the route, you are free to put whatever you want in the `data` attribute, see also [Route](/api/route). +If you need to store more data in the route, you are free to put whatever you want in the `data` attribute, see also [Route](/documentation/api/routing/route). @@ -194,14 +194,14 @@ Note that all routes are relative, since a component does not know if it is embe Therefore you should never use the `route.path` for navigation since the route object has no knowledge of the full url (e.g. `/docs/basics/ipywigets`) but only knows its small piece of the pathname (e.g. `ipywidgets`) -Using [`resolve_path`](/api/resolve_path) we can request the full url for navigation. +Using [`resolve_path`](/documentation/api/routing/resolve_path) we can request the full url for navigation. ```python def resolve_path(path_or_route: Union[str, solara.Route], level=0) -> str: ... ``` -We can pass this full URL to the [`solara.Link`](/api/link) component, e.g. like: +We can pass this full URL to the [`solara.Link`](/documentation/components/advanced/link) component, e.g. like: ```python @solara.component @@ -217,7 +217,7 @@ def LinkToIpywidgets(): ## Fully manual routing -If you want to do routing fully manually, you can use the [`solara.use_router`](/api/use_router) hook, and use the `.path` attribute. +If you want to do routing fully manually, you can use the [`solara.use_router`](/documentation/api/routing/use_router) hook, and use the `.path` attribute. ```python import solara diff --git a/solara/website/pages/documentation/advanced/content/30-enterprise/10-oauth.md b/solara/website/pages/documentation/advanced/content/30-enterprise/10-oauth.md index eec9ada17..dc0d68629 100644 --- a/solara/website/pages/documentation/advanced/content/30-enterprise/10-oauth.md +++ b/solara/website/pages/documentation/advanced/content/30-enterprise/10-oauth.md @@ -152,8 +152,8 @@ ZgrzSLUyft-JvnNMNJ2LgbCFVqcxPOatANAQhMD5EYU Solara provides two convenient components for creating a user interface for login and logout: - 1. [Avatar](/api/avatar): This component shows the user's avatar. - 2. [AvatarMenu](/api/avatar_menu): This component shows a menu with the user's avatar and a logout button. + 1. [Avatar](/documentation/components/enterprise/avatar): This component shows the user's avatar. + 2. [AvatarMenu](/documentation/components/enterprise/avatar_menu): This component shows a menu with the user's avatar and a logout button. ## Python version support diff --git a/solara/website/pages/documentation/advanced/content/40-development/00-overview.md b/solara/website/pages/documentation/advanced/content/40-development/00-overview.md new file mode 100644 index 000000000..e69de29bb diff --git a/solara/website/pages/documentation/advanced/content/40-development/01-contribute.md b/solara/website/pages/documentation/advanced/content/40-development/01-contribute.md index 01f9fe2a0..5672321b2 100644 --- a/solara/website/pages/documentation/advanced/content/40-development/01-contribute.md +++ b/solara/website/pages/documentation/advanced/content/40-development/01-contribute.md @@ -7,8 +7,8 @@ You do not need to be a developer to contribute to Solara. We welcome all contri We use [GitHub to manage issues](https://github.com/widgetti/solara/issues/new) and you should not hesitate to report any bug you find. Please include as much information as possible for us to be able to reproduce the bug. Yes, reporting a bug/issue is a contribution! -It might take a while for us to get back to you. If the bug is urgent, and you are able to provide financial support for its rapid resolution, please [contact us](/docs/contact). -If you can fix the bug yourself, please consider submitting a pull request instead, see [the development guide](/docs/development) for more information. +It might take a while for us to get back to you. If the bug is urgent, and you are able to provide financial support for its rapid resolution, please [contact us](/contact). +If you can fix the bug yourself, please consider submitting a pull request instead, see [the development guide](/documentation/advanced/development/setup) for more information. If you are unable to address the bug yourself and find it challenging to provide financial support, please be assured we are still committed to rectifying bugs and resolving issues. However, please understand that our ability to address these issues may be impacted by our resources at hand, as sustaining this project also entails financial obligations. Your patience and understanding in this matter is highly appreciated 🙇. @@ -16,7 +16,7 @@ If you are unable to address the bug yourself and find it challenging to provide The documentation is mostly written in Markdown, and can be found at [in the main repository](https://github.com/widgetti/solara/tree/master/solara/website/pages). -You can use the GitHub web interface to edit the files, or clone the repository and edit them locally. See [the development guide](/docs/development) for more information. +You can use the GitHub web interface to edit the files, or clone the repository and edit them locally. See [the development guide](/documentation/advanced/development/setup) for more information. If you locally want to render the documentation, run: @@ -26,10 +26,10 @@ $ solara run solara.website.pages ## Examples or showcase -If you have a complete program you want to share, and you think it would be cool to be listed at [our showcase page](/showcase), [please contact us](/docs/contact). +If you have a complete program you want to share, and you think it would be cool to be listed at [our showcase page](/showcase), [please contact us](/contact). If you want to show a particular way of using Solara that you think is very useful -for others, but it is not a complete program, consider adding to [the examples](/docs/examples). See [the development guide](/docs/development) for more information. +for others, but it is not a complete program, consider adding to [the examples](/documentation/examples/). See [the development guide](/documentation/advanced/development/setup) for more information. ## Share your experiences and ideas diff --git a/solara/website/pages/documentation/advanced/content/40-development/10-setup.md b/solara/website/pages/documentation/advanced/content/40-development/10-setup.md index b16739ae3..936919129 100644 --- a/solara/website/pages/documentation/advanced/content/40-development/10-setup.md +++ b/solara/website/pages/documentation/advanced/content/40-development/10-setup.md @@ -1,9 +1,9 @@ # Development -See also [the contributing guide](/docs/howto/contribute) for more information on how to contribute to Solara. +See also [the contributing guide](/documentation/advanced/howto/contribute) for more information on how to contribute to Solara. ## Development setup -Assuming you have created a virtual environment as described in [the installation guide](/docs/installing), you can install a development install of Solara using: +Assuming you have created a virtual environment as described in [the installation guide](/documentation/getting_started/installing), you can install a development install of Solara using: $ git clone git@github.com:widgetti/solara.git $ cd solara diff --git a/solara/website/pages/documentation/api/hooks/use_memo.md b/solara/website/pages/documentation/api/hooks/use_memo.md index b824293fb..231a45d7c 100644 --- a/solara/website/pages/documentation/api/hooks/use_memo.md +++ b/solara/website/pages/documentation/api/hooks/use_memo.md @@ -11,6 +11,6 @@ def use_memo( `use_memo` stores ([memoize](https://en.wikipedia.org/wiki/Memoization)) the function return on first render, and then excludes it from being re-executed, except when one of the `dependencies` changes. `dependencies` can take the value `None`, in which case dependencies are automatically obtained from nonlocal variables. If an empty list is passed as `dependencies` instead, the function is only executed once over the entire lifetime of the component. -Not to be confused with [memorize](https://solara.dev/api/memoize) which can cache multiple return values and which can be used outside of component. +Not to be confused with [memorize](https://solara.dev/documentation/api/utilities/memoize) which can cache multiple return values and which can be used outside of component. See also the [Reacton docs](https://reacton.solara.dev/en/latest/api/#use_memo). diff --git a/solara/website/pages/documentation/components/status/error.py b/solara/website/pages/documentation/components/status/error.py index f41b34e80..69f90543c 100644 --- a/solara/website/pages/documentation/components/status/error.py +++ b/solara/website/pages/documentation/components/status/error.py @@ -2,9 +2,9 @@ Solara has 4 types of alerts: - * [Success](/api/success) - * [Info](/api/info) - * [Warning](/api/warning) + * [Success](/documentation/components/status/success) + * [Info](/documentation/components/status/info) + * [Warning](/documentation/components/status/warning) * Error (this page) diff --git a/solara/website/pages/documentation/components/status/info.py b/solara/website/pages/documentation/components/status/info.py index 6b5db6caf..cac0cf272 100644 --- a/solara/website/pages/documentation/components/status/info.py +++ b/solara/website/pages/documentation/components/status/info.py @@ -2,10 +2,10 @@ Solara has 4 types of alerts: - * [Success](/api/success) + * [Success](/documentation/components/status/success) * Info (this page) - * [Warning](/api/warning) - * [Error](/api/error) + * [Warning](/documentation/components/status/warning) + * [Error](/documentation/components/status/error) diff --git a/solara/website/pages/documentation/components/status/success.py b/solara/website/pages/documentation/components/status/success.py index a07d8ae9c..6525d84bc 100644 --- a/solara/website/pages/documentation/components/status/success.py +++ b/solara/website/pages/documentation/components/status/success.py @@ -3,9 +3,9 @@ Solara has 4 types of alerts: * Success (this page) - * [Info](/api/info) - * [Warning](/api/warning) - * [Error](/api/error) + * [Info](/documentation/components/status/info) + * [Warning](/documentation/components/status/warning) + * [Error](/documentation/components/status/error) diff --git a/solara/website/pages/documentation/components/status/warning.py b/solara/website/pages/documentation/components/status/warning.py index 6a42f0e10..6ecd79467 100644 --- a/solara/website/pages/documentation/components/status/warning.py +++ b/solara/website/pages/documentation/components/status/warning.py @@ -2,10 +2,10 @@ Solara has 4 types of alerts: - * [Success](/api/success) - * [Info](/api/info) + * [Success](/documentation/components/status/success) + * [Info](/documentation/components/status/info) * Warning (this page) - * [Error](/api/error) + * [Error](/documentation/components/status/error) diff --git a/solara/website/pages/documentation/examples/general/deploy_model.py b/solara/website/pages/documentation/examples/general/deploy_model.py index 38e642250..40d11afe4 100644 --- a/solara/website/pages/documentation/examples/general/deploy_model.py +++ b/solara/website/pages/documentation/examples/general/deploy_model.py @@ -1,7 +1,8 @@ """# Deploy model demo -This show off a combination of [solara.lab.Menu](/api/menu) and [solara.lab.ConfirmationDialog](/api/confirmation_dialog) -and [solara.use_thread](/api/use_thread) to demonstrate how to tune, fit and deploy a model. +This show off a combination of [solara.lab.Menu](/documentation/components/lab/menu) and + [solara.lab.ConfirmationDialog](/documentation/components/lab/confirmation_dialog) +and [solara.use_thread](/documentation/api/hooks/use_thread) to demonstrate how to tune, fit and deploy a model. The actually deployment is not real, but simulated by a thread that returns a boolean value on success and sleep for a while to similate the deployment taking time. @@ -15,7 +16,6 @@ import numpy as np import pandas as pd import plotly.express as px - import solara import solara.lab diff --git a/solara/website/pages/documentation/examples/general/login_oauth.py b/solara/website/pages/documentation/examples/general/login_oauth.py index 138c686a0..5cbabd0c4 100644 --- a/solara/website/pages/documentation/examples/general/login_oauth.py +++ b/solara/website/pages/documentation/examples/general/login_oauth.py @@ -54,7 +54,7 @@ def Page(): This is the raw user data from the auth provider. - We use the `picture` field to display an avatar in the [AppBar](/api/appbar). + We use the `picture` field to display an avatar in the [AppBar](/documentation/components/layout/app_bar). """ ) sl.Preformatted(pprint.pformat(auth.user.value)) diff --git a/solara/website/pages/documentation/examples/general/vue_component.py b/solara/website/pages/documentation/examples/general/vue_component.py index 6aa5cf011..10862caf1 100644 --- a/solara/website/pages/documentation/examples/general/vue_component.py +++ b/solara/website/pages/documentation/examples/general/vue_component.py @@ -4,7 +4,7 @@ It can also be beneficial for performance, since instead of creating many widgets from the Python side we only send data to the frontend. If event handling is also done on the frontend, this reduces latency and makes you app feel much smoother. -See [the API documentation on component_vue](/api/component_vue) for more information. +See [the API documentation on component_vue](/documentation/api/utilities/component_vue) for more information. This example is based on [the vuetify docs](https://v2.vuetifyjs.com/en/components/sparklines/#custom-labels), Note that the "Go to report" button does not do anything yet. @@ -14,7 +14,6 @@ from typing import Callable import numpy as np - import solara seed = solara.reactive(42) diff --git a/solara/website/pages/documentation/examples/libraries/altair.py b/solara/website/pages/documentation/examples/libraries/altair.py index be33dc1b0..e1f0e75b7 100644 --- a/solara/website/pages/documentation/examples/libraries/altair.py +++ b/solara/website/pages/documentation/examples/libraries/altair.py @@ -2,16 +2,15 @@ [Altair](https://altair-viz.github.io/index.html) is a declarative statistical visualization library for Python. -This example show how to use the [on_click handler](/api/altair) to display data for a specific day in the chart. +This example show how to use the [on_click handler](/documentation/components/viz/altair) to display data for a specific day in the chart. Based on [an Altair example](https://altair-viz.github.io/gallery/annual_weather_heatmap.html) """ import altair as alt import pandas as pd -from vega_datasets import data - import solara +from vega_datasets import data # title = "Altair visualization" source = data.seattle_weather() diff --git a/solara/website/pages/documentation/examples/utilities/countdown_timer.py b/solara/website/pages/documentation/examples/utilities/countdown_timer.py index d6e01a976..fc94b92ee 100644 --- a/solara/website/pages/documentation/examples/utilities/countdown_timer.py +++ b/solara/website/pages/documentation/examples/utilities/countdown_timer.py @@ -1,6 +1,6 @@ """# Countdown timer. -This example shows how to use [use_thread](/api/use_thread) to create a countdown timer. +This example shows how to use [use_thread](/documentation/api/hooks/use_thread) to create a countdown timer. The UI code demonstrates a lot of conditional rendering. diff --git a/solara/website/pages/documentation/examples/visualization/plotly.py b/solara/website/pages/documentation/examples/visualization/plotly.py index 8ecb7d36f..d837350fb 100644 --- a/solara/website/pages/documentation/examples/visualization/plotly.py +++ b/solara/website/pages/documentation/examples/visualization/plotly.py @@ -8,12 +8,11 @@ ## Note Solara supports plotly and plotly express. Create your figure (not a figure widget) -and pass it to the [FigurePlotly](/api/plotly) component. +and pass it to the [FigurePlotly](/documentation/components/viz/plotly) component. """ import pandas as pd import plotly.express as px - import solara title = "Scatter plot using Plotly" diff --git a/solara/website/pages/documentation/getting_started/content/00-quickstart.md b/solara/website/pages/documentation/getting_started/content/00-quickstart.md index ffb5fb6b1..7c52b7d6c 100644 --- a/solara/website/pages/documentation/getting_started/content/00-quickstart.md +++ b/solara/website/pages/documentation/getting_started/content/00-quickstart.md @@ -7,12 +7,12 @@ This 1-minute quickstart will get you to: * Run your script using Solara server. * (Optional) Reuse your code in the Jupyter notebook. -If you are an existing ipywidget user and do not want to learn the component based method, you might want to skip the quickstart and directly go to the [IPywidgets user tutorial](/docs/tutorial/ipywidgets). +If you are an existing ipywidget user and do not want to learn the component based method, you might want to skip the quickstart and directly go to the [IPywidgets user tutorial](/documentation/getting_started/tutorials/ipywidgets). ## Installation -Run `pip install solara`, or follow the [Installation instructions](/docs/installing) for more detailed instructions. +Run `pip install solara`, or follow the [Installation instructions](/documentation/getting_started/installing) for more detailed instructions. ## First script diff --git a/solara/website/pages/documentation/getting_started/content/01-introduction.md b/solara/website/pages/documentation/getting_started/content/01-introduction.md index dca354820..175c5f6bb 100644 --- a/solara/website/pages/documentation/getting_started/content/01-introduction.md +++ b/solara/website/pages/documentation/getting_started/content/01-introduction.md @@ -5,7 +5,7 @@ Solara is an Open Source library that lets you use and build data-focused web apps (data apps) using reusable UI components. Your app will work in the Jupyter notebook and production-grade web frameworks (FastAPI, Starlette, Flask, ...). -Solara uses proven technologies and mature standards. Grow from a one-off experiment in the Jupyter notebook to a dynamic data portal in production. Built on top of [Reacton](/docs/understanding/reacton) to keep your code complexity under control and [IPywidgets](/docs/understanding/ipywidgets) to access a rich set of UI libraries without having to write Javascript or CSS. +Solara uses proven technologies and mature standards. Grow from a one-off experiment in the Jupyter notebook to a dynamic data portal in production. Built on top of [Reacton](/documentation/advanced/understanding/reacton) to keep your code complexity under control and [IPywidgets](/documentation/advanced/understanding/ipywidgets) to access a rich set of UI libraries without having to write Javascript or CSS. We care about developer experience. Solara will give your hot code reloading and type hints for faster development. @@ -17,19 +17,19 @@ Many frameworks only solve a specific set of problems. Once you step outside of On the other extreme, you might be working with a library with no clear patterns that let you do anything. You may only be weeks away from a total code complexity nightmare, which slowly kills your project. -At the same time, starting a new framework from scratch would be unwise. We prefer to build on top of solid, battle-tested libraries, such as [IPywidgets](/docs/understanding/ipywidgets). +At the same time, starting a new framework from scratch would be unwise. We prefer to build on top of solid, battle-tested libraries, such as [IPywidgets](/documentation/advanced/understanding/ipywidgets). ## Why use Solara? Instead of inventing a new API with an unknown track record, we take a different approach. We look at the JavaScript world. React is a technology that has proven itself for many years. It has shown to be a good all-around model for building complex UIs. -[Reacton](/docs/understanding/reacton) is the equivalent of ReactJS for Python (and IPywidgets). It allows us to use the same reusable components and hooks as in the ReactJS ecosystem. Using Reacton, we build web/data applications without suffering from complex code bases. +[Reacton](/documentation/advanced/understanding/reacton) is the equivalent of ReactJS for Python (and IPywidgets). It allows us to use the same reusable components and hooks as in the ReactJS ecosystem. Using Reacton, we build web/data applications without suffering from complex code bases. Looking again at the JavaScript world, we see software such as NextJS is putting a framework around ReactJS. NextJS is more opinionated than ReactJS and adds more "batteries" such as routing. Solara plays a similar role as NextJS. It builds on top of Reacton but handles things like routing for you. -But Solara is also different and is even more opinionated than NextJS. The reason for this is its focus on the data-heavy Python ecosystem. For this reason, it comes with many components and hooks that make building beautiful data apps easier (see our [API](/api)). +But Solara is also different and is even more opinionated than NextJS. The reason for this is its focus on the data-heavy Python ecosystem. For this reason, it comes with many components and hooks that make building beautiful data apps easier (see our [Documentation](/documentation)). Solara is a clear, systematic, Python-based web framework using industry-trusted technology. Smooth developer experience and enforced code modularity will allow you to build a data app at any scale while maintaining simple code. @@ -37,7 +37,7 @@ Solara is a clear, systematic, Python-based web framework using industry-trusted For your understanding, it might be good just to run an example. -Follow the [installation instructions](/docs/installing) or do the TLDR: +Follow the [installation instructions](/documentation/getting_started/installing) or do the TLDR: $ pip install solara @@ -78,18 +78,18 @@ The browser should open http://127.0.0.1:8765 Solara is actually two things. ### Solara server -[Solara server](/docs/understanding/solara-server) renders ipywidgets in the browser in a very efficient manner and takes care of many other things -such as [routing](/docs/understanding/routing) and [Static Site Generation](/docs/reference/static-site-generation). +[Solara server](/documentation/advanced/understanding/solara-server) renders ipywidgets in the browser in a very efficient manner and takes care of many other things +such as [routing](/documentation/advanced/understanding/routing) and [Static Site Generation](/documentation/getting_started/reference/static-site-generation). ### Solara UI -The UI part is built on top of [Reacton](/docs/understanding/reacton), which uses the existing IPyWidgets stack. It gives a consistent set +The UI part is built on top of [Reacton](/documentation/advanced/understanding/reacton), which uses the existing IPyWidgets stack. It gives a consistent set of modern UI components with the Material Design look, as well as a set of routines to make application development of data heavy web apps easier. ### Overview -If you use Jupyter, then you probably use the Jupyter notebook, Lab, or [Voila](/docs/understanding/voila) to get your widgets into the browser. You may not care about [Solara server](/docs/understanding/solara-server) and can focus on just the UI part. +If you use Jupyter, then you probably use the Jupyter notebook, Lab, or [Voila](/documentation/advanced/understanding/voila) to get your widgets into the browser. You may not care about [Solara server](/documentation/advanced/understanding/solara-server) and can focus on just the UI part. If you don't use Jupyter, don't know what it is, or are an ML Ops, Dev Ops, or Sys Admin, you are probably more interested in the Solara server. @@ -99,16 +99,16 @@ If you don't use Jupyter, don't know what it is, or are an ML Ops, Dev Ops, or S We recommend going through the documentation linearly following the arrows on the bottom, meaning you will go through: - * [Installing](/docs/installing) - * [Quick start](/docs/quickstart) - * [Tutorials](/docs/tutorial) + * [Installing](/documentation/getting_started/installing) + * [Quick start](/documentation/getting_started) + * [Tutorials](/documentation/getting_started/tutorials) -If you want to know more about specific parts, you can go through the [How-to section](/docs/howto) to learn more. Feel free to skip chapters, and go back to topics when you need to. +If you want to know more about specific parts, you can go through the [How-to section](/documentation/advanced/howto) to learn more. Feel free to skip chapters, and go back to topics when you need to. -If you want to know what components or hooks are available, or want to know more about a specific component, check out the [API](/api) which includes live code examples. Other reference documentation can be found at the [reference section](/docs/reference) +If you want to know what components or hooks are available, or want to know more about a specific component, check out the [Documentation](/documentation) which includes live code examples. Other reference documentation can be found at the [reference section](/documentation/getting_started/reference) -If you feel like you miss some basic understanding and want to give a bit deeper into the what and why feel free to explore the [Understanding section](/docs/understanding). +If you feel like you miss some basic understanding and want to give a bit deeper into the what and why feel free to explore the [Understanding section](/documentation/advanced/understanding). [Our examples](/examples) may help you see how particular problems can be solved using Solara, or as inspiration. If you want to contribute an example, contact us on GitHub or directly open a [Pull Request](https://github.com/widgetti/solara/). diff --git a/solara/website/pages/documentation/getting_started/content/02-installing.md b/solara/website/pages/documentation/getting_started/content/02-installing.md index 1c34c8b07..074e26f5b 100644 --- a/solara/website/pages/documentation/getting_started/content/02-installing.md +++ b/solara/website/pages/documentation/getting_started/content/02-installing.md @@ -44,7 +44,7 @@ solara @ https://github.com/widgetti/solara/package/archive/master.tar.gz ``` -If you want to do development on Solara, read the [development documentation](/docs/development). +If you want to do development on Solara, read the [development documentation](/documentation/advanced/development/setup). ## Air-gapped installation / Firewalled network diff --git a/solara/website/pages/documentation/getting_started/content/04-tutorials/00-overview.md b/solara/website/pages/documentation/getting_started/content/04-tutorials/00-overview.md index aca1e4801..fb9032c67 100644 --- a/solara/website/pages/documentation/getting_started/content/04-tutorials/00-overview.md +++ b/solara/website/pages/documentation/getting_started/content/04-tutorials/00-overview.md @@ -2,8 +2,8 @@ Instead of having one tutorial, we have tutorials for different audiences. - * [Jupyter Dashboard](/docs/tutorial/jupyter-dashboard-part1): Learn to create a dashboard in the Jupyter notebook. - * [Data science](/docs/tutorial/data-science): In this tutorial, we will introduce Solara from the perspective of a data scientist or when you are thinking of using Solara for a data science app. - * [Web app](/docs/tutorial/web-app): You are not a data scientist, but you are interested in using Solara to create a web app using Pure Python. - * [IPywidgets user](/docs/tutorial/ipywidgets): If you are already using [ipywidgets](/docs/understanding/ipywidgets) you will learn how to use the [Solara server](/docs/understanding/solara-server) to render your regular ipywidget applications. - * [Streamlit](/docs/tutorial/streamlit): If you are an existing Streamlit user, this might appeal more to you. + * [Jupyter Dashboard](/documentation/getting_started/tutorials/jupyter-dashboard-part1): Learn to create a dashboard in the Jupyter notebook. + * [Data science](/documentation/getting_started/tutorials/data-science): In this tutorial, we will introduce Solara from the perspective of a data scientist or when you are thinking of using Solara for a data science app. + * [Web app](/documentation/getting_started/tutorials/web-app): You are not a data scientist, but you are interested in using Solara to create a web app using Pure Python. + * [IPywidgets user](/documentation/getting_started/tutorials/ipywidgets): If you are already using [ipywidgets](/documentation/advanced/understanding/ipywidgets) you will learn how to use the [Solara server](/documentation/advanced/understanding/solara-server) to render your regular ipywidget applications. + * [Streamlit](/documentation/getting_started/tutorials/streamlit): If you are an existing Streamlit user, this might appeal more to you. diff --git a/solara/website/pages/documentation/getting_started/content/04-tutorials/20-web-app.md b/solara/website/pages/documentation/getting_started/content/04-tutorials/20-web-app.md index 898bc4138..6788402ec 100644 --- a/solara/website/pages/documentation/getting_started/content/04-tutorials/20-web-app.md +++ b/solara/website/pages/documentation/getting_started/content/04-tutorials/20-web-app.md @@ -5,7 +5,7 @@ In this tutorial, you will learn how to use Solara to create a tiny web app usin ## You should know This tutorial will assume you have successfully installed Solara. -If not, please follow the [Installation guide](/docs/installing). +If not, please follow the [Installation guide](/documentation/getting_started/installing). ## Generate a script file The simplest way to get started is to run the command @@ -40,7 +40,7 @@ def Page(): ## Run the script -Using [Solara server](/docs/understanding/solara-server), we can now run our Python script using: +Using [Solara server](/documentation/advanced/understanding/solara-server), we can now run our Python script using: ```bash $ solara run sol.py @@ -50,7 +50,7 @@ Solara server is starting at http://localhost:8765 If you open the URL in your browser ([or click here](http://localhost:8765)), you should see the same example as above. Solara will run your script once, and will look for the `Page` component. Solara expects this component to exist -and be a [Reacton](/docs/understanding/reacton) component. (See the [IPywidget tutorial](/docs/tutorial/ipywidgets) to learn how to render a regular ipywidget). +and be a [Reacton](/documentation/advanced/understanding/reacton) component. (See the [IPywidget tutorial](/documentation/getting_started/tutorials/ipywidgets) to learn how to render a regular ipywidget). Since your script is only run once, you could put in the main body of your script code that only needs to run once (e.g. loading data from disk) @@ -68,7 +68,7 @@ Lets modify the script a little bit, possibly in this way: ``` If we save the script, Solara will automatically reload your script and update -your browser (we call this feature [hot reloading](/docs/reference/reloading)). +your browser (we call this feature [hot reloading](/documentation/getting_started/reference/reloading)). Note that Solara will remember your state (e.g., the number of buttons clicked) when the app reloads. diff --git a/solara/website/pages/documentation/getting_started/content/04-tutorials/30-ipywidgets.md b/solara/website/pages/documentation/getting_started/content/04-tutorials/30-ipywidgets.md index b3a59dfaa..37751baa7 100644 --- a/solara/website/pages/documentation/getting_started/content/04-tutorials/30-ipywidgets.md +++ b/solara/website/pages/documentation/getting_started/content/04-tutorials/30-ipywidgets.md @@ -1,15 +1,15 @@ # Tutorial: IPywidgets -If you are already using [ipywidgets](/docs/understanding/ipywidgets) in the notebook, possibly using [Voila](/docs/understanding/voila), you might be pleased to know that you -can also use the [Solara server](/docs/understanding/solara-server) to render your regular ipywidget application. +If you are already using [ipywidgets](/documentation/advanced/understanding/ipywidgets) in the notebook, possibly using [Voila](/documentation/advanced/understanding/voila), you might be pleased to know that you +can also use the [Solara server](/documentation/advanced/understanding/solara-server) to render your regular ipywidget application. -We recommend you learn how to write applications using [Reacton](/docs/understanding/reacton). However, if you have already written an application in -pure [ipywidgets](/docs/understanding/ipywidgets), this approach will let you gradually move from pure ipywidgets to Reacton. +We recommend you learn how to write applications using [Reacton](/documentation/advanced/understanding/reacton). However, if you have already written an application in +pure [ipywidgets](/documentation/advanced/understanding/ipywidgets), this approach will let you gradually move from pure ipywidgets to Reacton. ## You should know This tutorial will assume you have successfully installed Solara. -If not, please follow the [Installation guide](/docs/installing). +If not, please follow the [Installation guide](/documentation/getting_started/installing). ## Your first ipywidget based Solara app @@ -70,10 +70,10 @@ Try making the following code change (remove the first, add the last), and watch ## Using Solara components -There are a lot of [valuable components in Solara](/api), but they are written as [Reacton/Solara components](/docs/understanding/reacton-basics), not +There are a lot of [valuable components in Solara](/documentation/components), but they are written as [Reacton/Solara components](/documentation/advanced/understanding/reacton-basics), not classic ipywidgets. -Use the [.widget(...)](/api/widget) method on a component to create a widget that can be used in your existing classic ipywidget application. +Use the [.widget(...)](/documentation/api/utilities/widget) method on a component to create a widget that can be used in your existing classic ipywidget application. ```python @@ -111,10 +111,10 @@ Note that we did not include the `:page` here, since solara will automatically l ## What you have learned - * [Solara server](/docs/understanding/solara-server) can render [ipywidgets](/docs/understanding/ipywidgets). + * [Solara server](/documentation/advanced/understanding/solara-server) can render [ipywidgets](/documentation/advanced/understanding/ipywidgets). * Running `$ solara run filename.py:variablename` tells Solara which script to execute and which variable name from the script to render. * The script is executed: * Once, when the solara server starts. * On each page request. * For each open browser page/tab, when the script is saved (hot reloading). - * Using the [.widget(...)](/api/widget) method we can start using Solara components in classic ipywidget app. + * Using the [.widget(...)](/documentation/api/utilities/widget) method we can start using Solara components in classic ipywidget app. diff --git a/solara/website/pages/documentation/getting_started/content/04-tutorials/40-streamlit.md b/solara/website/pages/documentation/getting_started/content/04-tutorials/40-streamlit.md index 926ee22c6..73548f034 100644 --- a/solara/website/pages/documentation/getting_started/content/04-tutorials/40-streamlit.md +++ b/solara/website/pages/documentation/getting_started/content/04-tutorials/40-streamlit.md @@ -18,8 +18,8 @@ st.markdown(f"{x} squared = {x_squared}") ## Translated to Solara -We now translate this to the equivalent in Solara. The largest difference is we need to explicitly create (application) state using [`solara.reactive`](/api/reactive). By passing the -reactive variable to the [SliderInt](/api/slider) via `value=x` we set up a two way binding between the component and the reactive variable. The generated text is passed down to the [Markdown](/api/markdown) component. +We now translate this to the equivalent in Solara. The largest difference is we need to explicitly create (application) state using [`solara.reactive`](/documentation/api/utilities/reactive). By passing the +reactive variable to the [SliderInt](/documentation/components/input/slider) via `value=x` we set up a two way binding between the component and the reactive variable. The generated text is passed down to the [Markdown](/documentation/components/output/markdown) component. ```solara @@ -49,7 +49,7 @@ You will see: Because we do some styling and because the sidebar is already used up, our preview on this page looks slightly different. -[Navigate to /apps/tutorial-streamlit](/apps/tutorial-streamlit) to see this app fullscreen. +[Navigate to /apps/tutorial-streamlit](/documentation/examples/fullscreen/tutorial_streamlit) to see this app fullscreen. ### Running this example in the notebook @@ -61,7 +61,7 @@ Again, slightly different for a different environment. ## Hot reloading -If you are using [Solara server](/docs/understanding/solara-server), try editing `sol.py`, and watch the page reload automatically after you save your file. Notebook users can simply edit and re-run. +If you are using [Solara server](/documentation/advanced/understanding/solara-server), try editing `sol.py`, and watch the page reload automatically after you save your file. Notebook users can simply edit and re-run. (*Note: Upgrade to solara 1.14.0 for a fix in hot reloading using `pip install "solara>=1.14.0"`*) @@ -69,13 +69,13 @@ If you are using [Solara server](/docs/understanding/solara-server), try editing ### Execution model As the introduction says, Solara does not re-execute your whole script after user interactions. -The main script is executed only once. With Solara you can use your main script to read large dataframes, or do some pre-calculations without the need for [caching](/docs/reference/caching). +The main script is executed only once. With Solara you can use your main script to read large dataframes, or do some pre-calculations without the need for [caching](/documentation/getting_started/reference/caching). -When a user navigates to a Solara server, the `Page` component (basically a function) will get executed. The `Page` component will call (lazily) new components like [solara.Markdown](/api/markdown) to build up the page. If state changes due to user input, Solara will trigger a cascade of re-excecutions of components which inputs or state changed, but never your whole script, nor every component. +When a user navigates to a Solara server, the `Page` component (basically a function) will get executed. The `Page` component will call (lazily) new components like [solara.Markdown](/documentation/components/output/markdown) to build up the page. If state changes due to user input, Solara will trigger a cascade of re-excecutions of components which inputs or state changed, but never your whole script, nor every component. ### State -With Solara (and [Reacton](/docs/understanding/reacton)) state does not live in a UI component (like a slider). Application state created with [`solara.reactive`](/api/reactive) lives on its own. Connecting the state to the UI component (in this case a slider) is a separate step, done via `value=x` in the above example. In general we recommend organising your components -similarly as in the example: [First use_state and other hooks, then calculations, at last the UI components](/docs/understanding/anatomy). +With Solara (and [Reacton](/documentation/advanced/understanding/reacton)) state does not live in a UI component (like a slider). Application state created with [`solara.reactive`](/documentation/api/utilities/reactive) lives on its own. Connecting the state to the UI component (in this case a slider) is a separate step, done via `value=x` in the above example. In general we recommend organising your components +similarly as in the example: [First use_state and other hooks, then calculations, at last the UI components](/documentation/advanced/understanding/anatomy). For complex situations, it is important to separate the state and the UI. Especially when you need the state of a UI component as input of the UI component itself, you can get stuck with streamlit. In Solara this follows naturally. @@ -83,8 +83,8 @@ For complex situations, it is important to separate the state and the UI. Especi ## Creating a reusable component -A big advantage of Solara is that you can create reusable components. A single component can be seen as the equivalent of a single streamlit script. However, in that case, we need to modify our component to have its own state, rather than using global application state, for this you can use the [`use_reactive`](/api/use_reactive), or [`use_state`](/api/use_state) hook. -Read more about state management in the [state management](/docs/fundamentals/state-management) section. +A big advantage of Solara is that you can create reusable components. A single component can be seen as the equivalent of a single streamlit script. However, in that case, we need to modify our component to have its own state, rather than using global application state, for this you can use the [`use_reactive`](/documentation/api/hooks/use_reactive), or [`use_state`](/documentation/api/hooks/use_state) hook. +Read more about state management in the [state management](/documentation/getting_started/fundamentals/state-management) section. ```solara import solara @@ -129,8 +129,8 @@ Changing that "y" to "x" will lead to an error, however. If this is a problem in ### Long running function -In Streamlit, it is normal for your main script to block execution. In Solara, the functions bodies of your components ([called render functions](/docs/understanding/anatomy)) should not block. Functions that block, or take a long time to execute, should be executed in a thread, such that rendering can continue. Using threads may sound scary, but using the -[use_thread](/api/use_thread) hook will help a lot. +In Streamlit, it is normal for your main script to block execution. In Solara, the functions bodies of your components ([called render functions](/documentation/advanced/understanding/anatomy)) should not block. Functions that block, or take a long time to execute, should be executed in a thread, such that rendering can continue. Using threads may sound scary, but using the +[use_thread](/documentation/api/hooks/use_thread) hook will help a lot. ## What you have learned @@ -138,4 +138,4 @@ In Streamlit, it is normal for your main script to block execution. In Solara, t * Solara will re-execute components instead, only what needs to. * State in Solara is separate from the UI components, unlike streamlit, where they are strongly linked. * State can be on the application level (global) for simplicity or on the component level (local) for creating reusable components. - * Solara should not block the render loop. Long-running functions should be executed in a thread using [use_thread](/api/use_thread). + * Solara should not block the render loop. Long-running functions should be executed in a thread using [use_thread](/documentation/api/hooks/use_thread). diff --git a/solara/website/pages/documentation/getting_started/content/04-tutorials/50-dash.md b/solara/website/pages/documentation/getting_started/content/04-tutorials/50-dash.md index 241fb1b6f..2fb55a588 100644 --- a/solara/website/pages/documentation/getting_started/content/04-tutorials/50-dash.md +++ b/solara/website/pages/documentation/getting_started/content/04-tutorials/50-dash.md @@ -36,7 +36,7 @@ This small app creates a dropdown (what we call Select in Solara), and some mark ## Translated to Solara -In Solara, we need to explicitly create application state using [`solara.reactive`](/api/reactive). We wire this up with the [Select][/api/select] via `value=color` and pass the color value down to the [Markdown](/api/markdown) component. +In Solara, we need to explicitly create application state using [`solara.reactive`](/documentation/api/utilities/reactive). We wire this up with the [Select][/documentation/components/input/select] via `value=color` and pass the color value down to the [Markdown](/documentation/components/output/markdown) component. ```solara import solara @@ -50,7 +50,7 @@ def Page(): solara.Markdown("## Hello World", style={"color": color.value}) ``` -Since this component combines two components, we have to put them together in a [container](/docs/understanding/containers) component, here implicitly a [Column](/api/column). +Since this component combines two components, we have to put them together in a [container](/documentation/advanced/understanding/containers) component, here implicitly a [Column](/documentation/components/layout/column). ## Making a re-usable component @@ -115,7 +115,7 @@ if __name__ == "__main__": ### In Solara -A big advantage of Solara is that components are reusable by default. However, we need to modify our component to have its own state, rather than using global application state. Creating local component state with [`use_reactive`](/api/use_reactive), or [`use_state`](/api/use_state) hook. Read more about state management in the [state management](/docs/fundamentals/state-management) section. +A big advantage of Solara is that components are reusable by default. However, we need to modify our component to have its own state, rather than using global application state. Creating local component state with [`use_reactive`](/documentation/api/hooks/use_reactive), or [`use_state`](/documentation/api/hooks/use_state) hook. Read more about state management in the [state management](/documentation/getting_started/fundamentals/state-management) section. We will rename (from `Page` to `MarkdownWithColor`) the component, add local state, and put in the markdown text as an argument. diff --git a/solara/website/pages/documentation/getting_started/content/05-fundamentals/00-overview.md b/solara/website/pages/documentation/getting_started/content/05-fundamentals/00-overview.md index 8ef50dabd..ff2da10d1 100644 --- a/solara/website/pages/documentation/getting_started/content/05-fundamentals/00-overview.md +++ b/solara/website/pages/documentation/getting_started/content/05-fundamentals/00-overview.md @@ -2,6 +2,6 @@ If you want to dive deeper into Solara, this section is for you. We will cover the following topics: - * [Components](/docs/fundamentals/components) + * [Components](/documentation/getting_started/fundamentals/components) * Hooks (soon) - * [State management](/docs/fundamentals/state-management) + * [State management](/documentation/getting_started/fundamentals/state-management) diff --git a/solara/website/pages/documentation/getting_started/content/05-fundamentals/10-components.md b/solara/website/pages/documentation/getting_started/content/05-fundamentals/10-components.md index 9052bbfda..f1b8f24ee 100644 --- a/solara/website/pages/documentation/getting_started/content/05-fundamentals/10-components.md +++ b/solara/website/pages/documentation/getting_started/content/05-fundamentals/10-components.md @@ -19,9 +19,9 @@ In Solara, there are two main types of components: Widget Components and Functio Widget Components correspond to ipywidgets and are responsible for rendering visual elements in the browser, such as buttons, sliders, or performing layout tasks. These components are the foundation of your user interface and provide the essential building blocks for creating interactive applications. -Solara mainly uses the [ipyvuetify library](/docs/understanding/ipyvuetify) for its widget components. It provides a set of high-level components that can be used to create rich, interactive user interfaces. +Solara mainly uses the [ipyvuetify library](/documentation/advanced/understanding/ipyvuetify) for its widget components. It provides a set of high-level components that can be used to create rich, interactive user interfaces. -See the [API docs](/docs/api) for a complete list of basic UI components. +See the [components page](/documentation/components) for a complete list of basic UI components. ## Function Components diff --git a/solara/website/pages/documentation/getting_started/content/05-fundamentals/50-state-management.md b/solara/website/pages/documentation/getting_started/content/05-fundamentals/50-state-management.md index c6e867068..ae5766d7b 100644 --- a/solara/website/pages/documentation/getting_started/content/05-fundamentals/50-state-management.md +++ b/solara/website/pages/documentation/getting_started/content/05-fundamentals/50-state-management.md @@ -1,12 +1,12 @@ # Introduction -State management is a crucial aspect of building data-focused web applications with Solara. By effectively managing state, you can create interactive and responsive applications that react to changes in data and user input. In Solara, there are two primary ways to define state: global application state using [`solara.reactive`](/api/reactive) and local component state using [`solara.use_state`](/api/use_state) or [`solara.use_reactive`](/api/use_reactive). This article will discuss these two approaches and provide examples of how to use them in your Solara applications. +State management is a crucial aspect of building data-focused web applications with Solara. By effectively managing state, you can create interactive and responsive applications that react to changes in data and user input. In Solara, there are two primary ways to define state: global application state using [`solara.reactive`](/documentation/api/utilities/reactive) and local component state using [`solara.use_state`](/documentation/api/hooks/use_state) or [`solara.use_reactive`](/documentation/api/hooks/use_reactive). This article will discuss these two approaches and provide examples of how to use them in your Solara applications. ## Two main ways of defining state in Solara ### Global application state using solara.reactive -Using [`solara.reactive`](/api/reactive) allows you to create global state variables that can be accessed and modified from any component within your application. This approach is useful when you need to manage state that is shared across multiple components or when you want to maintain consistency throughout your application. +Using [`solara.reactive`](/documentation/api/utilities/reactive) allows you to create global state variables that can be accessed and modified from any component within your application. This approach is useful when you need to manage state that is shared across multiple components or when you want to maintain consistency throughout your application. Example: @@ -30,7 +30,7 @@ In this case, the `SomeAppSpecificComponent` is not reusable in the sense that a ## Local component state using solara.use_state -[`solara.use_state`](/api/use_state) is a hook that allows you to manage local state within a specific component. This approach is beneficial when you want to encapsulate state within a component, making it self-contained and modular. Local state management is suitable for situations where state changes only affect the component and do not need to be shared across the application. +[`solara.use_state`](/documentation/api/hooks/use_state) is a hook that allows you to manage local state within a specific component. This approach is beneficial when you want to encapsulate state within a component, making it self-contained and modular. Local state management is suitable for situations where state changes only affect the component and do not need to be shared across the application. Example: ```solara diff --git a/solara/website/pages/documentation/getting_started/content/06-reference/41-asset-files.md b/solara/website/pages/documentation/getting_started/content/06-reference/41-asset-files.md index 1e8f5739f..27de66f67 100644 --- a/solara/website/pages/documentation/getting_started/content/06-reference/41-asset-files.md +++ b/solara/website/pages/documentation/getting_started/content/06-reference/41-asset-files.md @@ -29,4 +29,4 @@ All assets files are served under `/static/assets/`, but how the asset Putting the `assets` directory 1 level higher than the `pages` directory avoids name collision with pages. -Although the `assets` directory can be used for serving arbitrary files, we recommend using the [static files](/docs/reference/static-files) directory instead, to avoid name collisions. +Although the `assets` directory can be used for serving arbitrary files, we recommend using the [static files](/documentation/getting_started/reference/static-files) directory instead, to avoid name collisions. diff --git a/solara/website/pages/documentation/getting_started/content/06-reference/60-static-site-generation.md b/solara/website/pages/documentation/getting_started/content/06-reference/60-static-site-generation.md index 5959968e4..78e2c473e 100644 --- a/solara/website/pages/documentation/getting_started/content/06-reference/60-static-site-generation.md +++ b/solara/website/pages/documentation/getting_started/content/06-reference/60-static-site-generation.md @@ -29,7 +29,7 @@ Using the command $ solara ssg your.awesome.app ``` -Will run the solara server and use playwright to fetch all known pages and save them to the `../build` directory. Solara knows about your pages because of its [routing support](/docs/understanding/routing). +Will run the solara server and use playwright to fetch all known pages and save them to the `../build` directory. Solara knows about your pages because of its [routing support](/documentation/advanced/understanding/routing). All HTML files in the `../build` will be used to pre-populate the HTML served to the user. diff --git a/solara/website/pages/documentation/getting_started/content/06-reference/70-search.md b/solara/website/pages/documentation/getting_started/content/06-reference/70-search.md index e84789902..08ef850d9 100644 --- a/solara/website/pages/documentation/getting_started/content/06-reference/70-search.md +++ b/solara/website/pages/documentation/getting_started/content/06-reference/70-search.md @@ -1,6 +1,6 @@ # Search -Solara can provide search, if [SSG](/docs/reference/static-site-generation) is enabled. This allows you to add a search box to you website, which performs a full-text search to provide quick access to pages. The solara website itself uses the +Solara can provide search, if [SSG](/documentation/getting_started/reference/static-site-generation) is enabled. This allows you to add a search box to you website, which performs a full-text search to provide quick access to pages. The solara website itself uses the search feature as well in the toolbar. ## Using Solara's Search feature. diff --git a/solara/website/pages/documentation/getting_started/content/06-reference/80-reloading.md b/solara/website/pages/documentation/getting_started/content/06-reference/80-reloading.md index 7ab26e15b..e387b7c0a 100644 --- a/solara/website/pages/documentation/getting_started/content/06-reference/80-reloading.md +++ b/solara/website/pages/documentation/getting_started/content/06-reference/80-reloading.md @@ -13,18 +13,18 @@ When a `.vue` file is saved, the widgets get updated automatically, without need ## Reloading of .vue files -The [Style component](/api/style) accepts a Path as argument, when that is used and the server is in development mode (the default), also +The [Style component](/documentation/components/advanced/style) accepts a Path as argument, when that is used and the server is in development mode (the default), also CSS files will be hot reloaded. ## Restarting the server after changes to the solara packages -You don't need to care about this feature if you only use solara, this is only relevant for development on solara itself, [see also development instructions](/docs/development). +You don't need to care about this feature if you only use solara, this is only relevant for development on solara itself, [see also development instructions](/documentation/advanced/development/setup). If the `--auto-restart/-a` flag is passed to solara-server and any changes occur in the `solara` package (excluding `solara.webpage`), solara-server will restart. This speeds up development on `solara-server` for developers since you do not need to manually restart the server in the terminal. ## Disabling reloading -In production mode (pass the `--production` argument to `solara run`) watching of files is disabled, and no reloading of files or vue templates will occur. If you run solara integrated in flask or uvicorn as laid out in [deployment documentation](https://solara.dev/docs/deploying/self-hosted) +In production mode (pass the `--production` argument to `solara run`) watching of files is disabled, and no reloading of files or vue templates will occur. If you run solara integrated in flask or uvicorn as laid out in [deployment documentation](https://solara.dev/documentation/getting_started/deploying/self-hosted) diff --git a/solara/website/pages/documentation/getting_started/content/06-reference/95-caching.md b/solara/website/pages/documentation/getting_started/content/06-reference/95-caching.md index 5b4f9d0d5..16cfa8fbd 100644 --- a/solara/website/pages/documentation/getting_started/content/06-reference/95-caching.md +++ b/solara/website/pages/documentation/getting_started/content/06-reference/95-caching.md @@ -11,7 +11,7 @@ assert "my-key" in solara.cache.storage Note that at any time later on, the key may be removed from this object, as a cache always has a limited capacity. -The `solara.cache.storage` cache object is used by [memoize](/api/memoize), if no storage argument is passed to this decorator. +The `solara.cache.storage` cache object is used by [memoize](/documentation/api/utilities/memoize), if no storage argument is passed to this decorator. ## Types of cache diff --git a/solara/website/pages/documentation/getting_started/content/07-deploying/00-overview.md b/solara/website/pages/documentation/getting_started/content/07-deploying/00-overview.md index 00affea62..4a719842b 100644 --- a/solara/website/pages/documentation/getting_started/content/07-deploying/00-overview.md +++ b/solara/website/pages/documentation/getting_started/content/07-deploying/00-overview.md @@ -1,3 +1,3 @@ # Deploying a solara app -A Solara app can be [self hosted](/docs/deploying/self-hosted) or [cloud hosted](/docs/deploying/cloud-hosted). +A Solara app can be [self hosted](/documentation/getting_started/deploying/self-hosted) or [cloud hosted](/documentation/getting_started/deploying/cloud-hosted). diff --git a/solara/website/pages/documentation/getting_started/content/07-deploying/10-self-hosted.md b/solara/website/pages/documentation/getting_started/content/07-deploying/10-self-hosted.md index 10c7a26c1..196fdc2b8 100644 --- a/solara/website/pages/documentation/getting_started/content/07-deploying/10-self-hosted.md +++ b/solara/website/pages/documentation/getting_started/content/07-deploying/10-self-hosted.md @@ -48,7 +48,7 @@ Instead, start your chosen web framework as directed by their documentation and $ export SOLARA_APP=sol.py # run flask or starlette -or look at the examples below for more detailed instructions per web framework. Note that when solara is used this way it [by default runs in production mode](https://solara.dev/docs/understanding/solara-server). +or look at the examples below for more detailed instructions per web framework. Note that when solara is used this way it [by default runs in production mode](https://solara.dev/documentation/advanced/understanding/solara-server). ## Flask @@ -180,7 +180,7 @@ display(element) Or consider using [Voila-vuetify](https://github.com/voila-dashboards/voila-vuetify). -Solara apps in Voila do not have support for [routing](/docs/understanding/routing)/[multipage](/docs/howto/multipage). +Solara apps in Voila do not have support for [routing](/documentation/advanced/understanding/routing)/[multipage](/documentation/advanced/howto/multipage). ## Panel @@ -211,7 +211,7 @@ For development/testing purposes, run this script as: $ panel serve solara_in_panel.py -Solara apps in Panel do not have support for [routing](/docs/understanding/routing)/[multipage](/docs/howto/multipage). +Solara apps in Panel do not have support for [routing](/documentation/advanced/understanding/routing)/[multipage](/documentation/advanced/howto/multipage). ## Nginx diff --git a/solara/website/pages/showcase/solara_dev.py b/solara/website/pages/showcase/solara_dev.py index 4fe159cd5..e678211cf 100644 --- a/solara/website/pages/showcase/solara_dev.py +++ b/solara/website/pages/showcase/solara_dev.py @@ -22,7 +22,7 @@ def Page(): Solara.dev is designed to be responsive, working seamlessly on both desktop and mobile devices. On smaller screens, the top navigation bar is replaced with a drawer for easy navigation. - The [`ColumnsResponsive`](/api/columns_responsive) component can be used to create responsive content layouts. + The [`ColumnsResponsive`](/documentation/components/layout/columns_responsive) component can be used to create responsive content layouts. """ )