Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Pre-release doc fixes #7283

Merged
merged 9 commits into from
Sep 16, 2024
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/explanation/api/callbacks.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The callback API in Panel is the lowest-level approach, affording the greatest amount of flexibility but also quickly growing in complexity because each new interactive behavior requires additional callbacks that can interact in complex ways. Nonetheless, callbacks are important to know about, and can often be used to complement the other approaches. For instance, one specific callback could be used in addition to the more reactive approaches the other APIs provide.

For more details on defining callbacks see the [linking how-to guides](../../how_to/links/index.md).
For more details on defining callbacks see the [linking how-to guides](../../how_to/links/index).

## Pros:

Expand Down
2 changes: 1 addition & 1 deletion doc/explanation/api/param.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Not only does the parameter hold the various metadata and validation options for

## References

The concept of a reference is crucial to using Panel effectively, as much of the [reactivity](reactivity.md) in Panel is built on top of the idea of reference binding. The other piece (i.e. the binding) is that parameters can be given a reference, which they will internally resolve and update whenever the reference updates. In param itself this has to be declared by declaring `allow_ref=True` on the parameter, in Panel effectively all parameters automatically enable this functionality and also allow support for `nested_refs=True` where possible.
The concept of a reference is crucial to using Panel effectively, as much of the [reactivity](reactivity) in Panel is built on top of the idea of reference binding. The other piece (i.e. the binding) is that parameters can be given a reference, which they will internally resolve and update whenever the reference updates. In param itself this has to be declared by declaring `allow_ref=True` on the parameter, in Panel effectively all parameters automatically enable this functionality and also allow support for `nested_refs=True` where possible.

Let us explore this with a simple example:

Expand Down
2 changes: 1 addition & 1 deletion doc/explanation/api/parameterized.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The [Param](http://param.holoviz.org) library allows expressing the parameters of a class (or a hierarchy of classes) completely independently of a GUI implementation. Panel and other libraries can then take those parameter declarations and turn them into a GUI to control the parameters. This approach allows the parameters controlling some computation to be captured specifically and explicitly (but as abstract parameters, not as widgets). Then thanks to the `@param.depends` decorator (similar to `@panel.depends` but for use in Parameterized classes without any dependency on Panel), it is then possible to directly express the dependencies between the parameters and the computation defined in some method on the class, all without ever importing Panel or any other GUI library. The resulting objects can then be used in both GUI and non-GUI contexts (batch computations, scripts, servers).

The parameterized approach is a powerful way to encapsulate computation in self-contained classes, taking advantage of object-oriented programming patterns. It also makes it possible to express a problem completely independently from Panel or any other GUI code, while still getting a GUI for free as a last step. For more detail on using this approach see the [how-to guides on declarative UIs with Param](../../how_to/param/index.md).
The parameterized approach is a powerful way to encapsulate computation in self-contained classes, taking advantage of object-oriented programming patterns. It also makes it possible to express a problem completely independently from Panel or any other GUI code, while still getting a GUI for free as a last step. For more detail on using this approach see the [how-to guides on declarative UIs with Param](../../how_to/param/index).

## Pros:

Expand Down
2 changes: 1 addition & 1 deletion doc/explanation/comparisons/compare_ipywidgets.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Both Panel and ipywidgets (aka Jupyter Widgets) allow Python users to work with custom widgets and create apps and dashboards from Python, both in Jupyter notebooks and in standalone servers (when paired with Voila. But Panel and ipywidgets are based on different, independently developed technologies for doing so, with some implications:

- Panel is based on Bokeh widgets and layouts, which were developed separately from the Jupyter ecosystem, and designed from the start for standalone deployments. Jupyter widgets, as the name suggests, were first developed specifically for the notebook environment, and only relatively recently (in 2019) adapted for standalone deployment (see [Voila](compare_voila.md)). Nowadays, both technologies have evolved to be well suited to both Jupyter and server contexts, but their different histories are still visible in the types of examples you typically see and in support for less-common operations for each library.
- Panel is based on Bokeh widgets and layouts, which were developed separately from the Jupyter ecosystem, and designed from the start for standalone deployments. Jupyter widgets, as the name suggests, were first developed specifically for the notebook environment, and only relatively recently (in 2019) adapted for standalone deployment (see [Voila](compare_voila)). Nowadays, both technologies have evolved to be well suited to both Jupyter and server contexts, but their different histories are still visible in the types of examples you typically see and in support for less-common operations for each library.

- Historically, ipywidgets exposed more of the underlying HTML/CSS styling options, allowing them to be customized more heavily than Bokeh widgets, but since Bokeh 3.0 and Panel 1.0 both types of widgets support similar types of styling.

Expand Down
2 changes: 1 addition & 1 deletion doc/explanation/comparisons/compare_streamlit.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,4 +22,4 @@ These videos from a dedicated Streamlit fan walk you through some of Streamlit's

## Code Examples

If you want to compare examples with code, check out the [How to Migrate From Streamlit Guide](../../how_to/streamlit_migration/index.md).
If you want to compare examples with code, check out the [How to Migrate From Streamlit Guide](../../how_to/streamlit_migration/index).
2 changes: 1 addition & 1 deletion doc/explanation/components/components_overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ The main objects that Panel provides, and that we are going to call *components*
- *Templates*: templates are components that render multiple Panel objects in an HTML document. The basic template, which you get when you serve an app without setting any template, is basically a blank canvas. Instead when you use one of the built-in templates you can easily improve the design and branding of your app, which will get for free a header, a sidebar, etc.
- *Notifications*: notifications are components that display so called "toasts", designed to mimic the push notifications that have been popularized by mobile and desktop operating systems.

All the Panel components can be visualized on the [Component Gallery](../../reference/index.rst).
All the Panel components can be visualized on the [Component Gallery](../../reference/index).

:::{tip}
Components usually have in their docstring a link to their documentation page, use `<component>?` in a notebook or your IDE inspection capabilities to access the link.
Expand Down
8 changes: 4 additions & 4 deletions doc/explanation/components/reactive_html_components.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,21 +35,21 @@ Slideshow(width=800, height=300)

## Alternatives

If you're looking for **simpler** alternatives to `ReactiveHTML`, Panel provides a `Viewer` class that allows you to combine existing Panel components using Python only. This approach is a great choice if you want to quickly create custom components without the need for writing HTML, CSS, or JavaScript. You can learn more about creating custom `Viewer` components in our guide [How-to > Combine Existing Components](../../how_to/custom_components/custom_viewer.md).
If you're looking for **simpler** alternatives to `ReactiveHTML`, Panel provides a `Viewer` class that allows you to combine existing Panel components using Python only. This approach is a great choice if you want to quickly create custom components without the need for writing HTML, CSS, or JavaScript. You can learn more about creating custom `Viewer` components in our guide [How-to > Combine Existing Components](../../how_to/custom_components/custom_viewer).

On the other hand, if you're looking for a **more advanced** approach that gives you full control over the design and functionality of your custom components, you can use *Bokeh Models*. With Bokeh Models, you can leverage the full power of your IDE, TypeScript and modern JavaScript development tools to build advanced and performant custom components. Many of the built-in Panel components are built using this approach. It provides flexibility and extensibility, allowing you to create highly customized and interactive components tailored to your specific needs. We expect detailed documentation on writing custom Bokeh models will be added to the documentation in the future.

## The Name

`ReactiveHTML` is named for its ability to enable reactive programming in HTML. Unlike the static HTML content that the [`HTML`](../../reference/panes/HTML.md) pane displays, `ReactiveHTML` components can update their view dynamically in response to changes in parameter values and other events.
`ReactiveHTML` is named for its ability to enable reactive programming in HTML. Unlike the static HTML content that the [`HTML`](../../reference/panes/HTML) pane displays, `ReactiveHTML` components can update their view dynamically in response to changes in parameter values and other events.

We could also have called the `ReactiveHTML` class for example `BaseComponent`, `HTMLComponent`, `SimpleComponent` or `AnyComponent` to give you the right associations.

It's worth noting that the name `ReactiveHTML` is not related to the JavaScript framework [React](https://react.dev/), although you can still use React with `ReactiveHTML` components.

## How-to Guides

To see `ReactiveHTML` in action and discover how to create your custom components, check out our detailed guide: [How-to > Create Custom Components with ReactiveHTML](../../how_to/custom_components/index.md#reactivehtml-components). It's packed with practical examples to help you get started quickly.
To see `ReactiveHTML` in action and discover how to create your custom components, check out our detailed guide: [How-to > Create Custom Components with ReactiveHTML](../../how_to/custom_components/index#reactivehtml-components). It's packed with practical examples to help you get started quickly.
philippjfr marked this conversation as resolved.
Show resolved Hide resolved

## API Guide

Expand Down Expand Up @@ -198,7 +198,7 @@ class CustomComponent(ReactiveHTML):
CustomComponent(value="A new value", width=500)
```

Check out the [How-to > Create Layouts With ReactiveHTML](../../how_to/custom_components/reactive_html/reactive_html_layout.md) guide for lots of Jinja2 examples.
Check out the [How-to > Create Layouts With ReactiveHTML](../../how_to/custom_components/reactive_html/reactive_html_layout) guide for lots of Jinja2 examples.

### Template variables vs Jinja2

Expand Down
2 changes: 1 addition & 1 deletion doc/explanation/dependencies/param.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,4 +276,4 @@ As you can see, *Parameters* offer a very generic mechanism for your Python code
## Related Resources

- See [Param's documentation](https://param.holoviz.org/)
- See [How-to > Declare UIs with Declarative API](../../how_to/param/index.md).
- See [How-to > Declare UIs with Declarative API](../../how_to/param/index).
14 changes: 7 additions & 7 deletions doc/explanation/develop_seamlessly.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ import panel as pn
pn.extension()
```

The extension ensures that the [`pyviz_comms`](https://github.com/holoviz/pyviz_comms) and all required Javascript and CSS resources are added to your notebook environment. If you are going to be using any custom extensions, such as [Vega](../reference/panes/Vega.md) or [Tabulator](../reference/widgets/Tabulator.md) you must ensure that you initialize these as well.
The extension ensures that the [`pyviz_comms`](https://github.com/holoviz/pyviz_comms) and all required Javascript and CSS resources are added to your notebook environment. If you are going to be using any custom extensions, such as [Vega](../reference/panes/Vega) or [Tabulator](../reference/widgets/Tabulator) you must ensure that you initialize these as well.

```{pyodide}
pn.extension('vega', 'tabulator')
Expand Down Expand Up @@ -157,12 +157,12 @@ The `--show` flag will open a browser tab with the live app and the `--dev` flag

### Tutorials

- [Develop in an Editor (Basic)](../tutorials/basic/develop_editor.md)
- [Develop in an Editor (Intermediate)](../tutorials/intermediate/develop_editor.md)¨
- [Develop in a Notebook (Basic)](../tutorials/basic/develop_notebook.md)
- [Develop in an Editor (Basic)](../tutorials/basic/develop_editor)
- [Develop in an Editor (Intermediate)](../tutorials/intermediate/develop_editor)
- [Develop in a Notebook (Basic)](../tutorials/basic/develop_notebook)

### How-to

- [Configure PyCharm](../how_to/editor/pycharm_configure.md)
- [Configure VS Code](../how_to/editor/vscode_configure.md)
- [Write apps in Markdown](../how_to/editor/markdown.md)
- [Configure PyCharm](../how_to/editor/pycharm_configure)
- [Configure VS Code](../how_to/editor/vscode_configure)
- [Write apps in Markdown](../how_to/editor/markdown)
4 changes: 2 additions & 2 deletions doc/how_to/authentication/basic.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ If you enter the valid password (i.e. `my_password`) it will look like

If you click the *Log out* button you will be sent back to the log in form.

In this mode the `username` is not authenticated. The `username` is provided as part of the [user info](user_info.md).
In this mode the `username` is not authenticated. The `username` is provided as part of the [user info](user_info).

## User credentials

Expand Down Expand Up @@ -66,7 +66,7 @@ When serving an application dynamically using `pn.serve` you can also provide a
## Custom templates

```{admonition} Prerequisites
For a more in-depth understanding of custom template take a look at the [how to > Build a Custom Template](../templates/template_custom.md) guide.
For a more in-depth understanding of custom template take a look at the [how to > Build a Custom Template](../templates/template_custom) guide.
```

If you want to customize the authentication template you can provide a custom template with the `--basic-login-template` CLI argument. The template needs to submit `username` and `password` to the `/login` endpoint of the Panel server, e.g. the form of the default template looks like this. Check out the default template [here](https://github.com/holoviz/panel/blob/main/panel/_templates/basic_login.html) for inspiration.
2 changes: 1 addition & 1 deletion doc/how_to/authentication/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The first step in configuring a OAuth is to specify a specific OAuth provider. P
* `password`: Generic password grant based OAuth Provider with configurable endpoints
* `auth_code`: Generic code challenge grant based OAuth Provider with configurable endpoints

We will go through the process of configuring each of these individually in [Providers](./providers.md) but for now all we need to know that the `oauth_provider` can be set on the commandline using the `--oauth-provider` CLI argument to `panel serve` or the `PANEL_OAUTH_PROVIDER` environment variable.
We will go through the process of configuring each of these individually in [Providers](providers) but for now all we need to know that the `oauth_provider` can be set on the commandline using the `--oauth-provider` CLI argument to `panel serve` or the `PANEL_OAUTH_PROVIDER` environment variable.

Examples:

Expand Down
2 changes: 1 addition & 1 deletion doc/how_to/authentication/user_info.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,4 @@ Please note that the user information above is only available to the users sessi

## Related Topics

- [Authorization Callbacks](authorization.md): Discover how to configure an authorization callback to perform custom authorization logic based on the user info such as redirects or error pages
- [Authorization Callbacks](authorization): Discover how to configure an authorization callback to perform custom authorization logic based on the user info such as redirects or error pages
2 changes: 1 addition & 1 deletion doc/how_to/callbacks/async.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,4 +118,4 @@ pn.Row(button, pane)

## Related Resources

- See the related [How-to > Link Parameters with Callbacks API](../links/index.md) guides, including [How to > Create Low-Level Python Links Using `.watch`](../links/watchers.md).
- See the related [How-to > Link Parameters with Callbacks API](../links/index) guides, including [How to > Create Low-Level Python Links Using `.watch`](../links/watchers).
4 changes: 2 additions & 2 deletions doc/how_to/callbacks/load.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@ layout.servable()

![panel-onload-example](https://assets.holoviz.org/panel/gifs/onload_callback.gif)

Note that `pn.state.onload` accepts both *sync* and *async* functions and also accepts a `threaded` argument, which, when combined with [enabling `config.nthreads`](../concurrency/threading.md) will run the callbacks concurrently on separate threads.
Note that `pn.state.onload` accepts both *sync* and *async* functions and also accepts a `threaded` argument, which, when combined with [enabling `config.nthreads`](../concurrency/threading) will run the callbacks concurrently on separate threads.

This example could also be implemented using a *bound and displayed function*. We recommend using that method together with `defer_load` when possible. See the [Defer Bound and Displayed Functions Guide](defer_load.md).
This example could also be implemented using a *bound and displayed function*. We recommend using that method together with `defer_load` when possible. See the [Defer Bound and Displayed Functions Guide](defer_load).

## Defer and Orchestrate Dependent Tasks

Expand Down
2 changes: 1 addition & 1 deletion doc/how_to/callbacks/periodic.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,4 +77,4 @@ pn.serve(panel_app)
```

## Related Resources
- See the related [How-to > Link Parameters with Callbacks API](../links/index.md) guides, including [How to > Create High-Level Python Links with `.link`](../links/links.md).
- See the related [How-to > Link Parameters with Callbacks API](../links/index) guides, including [How to > Create High-Level Python Links with `.link`](../links/links).
2 changes: 1 addition & 1 deletion doc/how_to/callbacks/schedule.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This guide addresses how to schedule tasks that run independently of any user vi

---

The `pn.state.schedule_task` functionality allows scheduling global tasks at certain times or on a specific schedule. This is distinct from [periodic callbacks](./periodic.md), which are scheduled per user session. Global tasks are useful for performing periodic actions like updating cached data, performing cleanup actions or other housekeeping tasks, while periodic callbacks should be reserved for making periodic updates to an application.
The `pn.state.schedule_task` functionality allows scheduling global tasks at certain times or on a specific schedule. This is distinct from [periodic callbacks](./periodic), which are scheduled per user session. Global tasks are useful for performing periodic actions like updating cached data, performing cleanup actions or other housekeeping tasks, while periodic callbacks should be reserved for making periodic updates to an application.

The different contexts in which global tasks and periodic callbacks run also has implications on how they should be scheduled. Scheduled task **must not** be declared in the application code itself, i.e. if you are serving `panel serve app.py` the callback you are scheduling must not be declared in the `app.py`. It must be defined in an external module or in a separate script declared as part of the `panel serve` invocation using the `--setup` commandline argument.

Expand Down
4 changes: 2 additions & 2 deletions doc/how_to/components/add_remove.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,5 +194,5 @@ gridspec

## Related Resources

- Learn more about Panes in [Explanation > Components](../../explanation/components/components_overview.md#panes).
- For more detail about `GridSpec` Panels, see the [Component Gallery > GridSpec](../reference/layouts/GridSpec.md).
- Learn more about Panes in [Explanation > Components](../../explanation/components/components_overview#panes).
philippjfr marked this conversation as resolved.
Show resolved Hide resolved
- For more detail about `GridSpec` Panels, see the [Component Gallery > GridSpec](../reference/layouts/GridSpec).
Loading
Loading