From 04ea0924cd7e51725826c07009cfeb777c49dd13 Mon Sep 17 00:00:00 2001 From: Philipp Rudiger Date: Mon, 6 Jun 2022 18:28:03 +0200 Subject: [PATCH] Convert installation guide to markdown --- doc/getting_started/build_app.md | 8 ++ .../{installation.rst => installation.md} | 105 +++++++++--------- 2 files changed, 62 insertions(+), 51 deletions(-) rename doc/getting_started/{installation.rst => installation.md} (53%) diff --git a/doc/getting_started/build_app.md b/doc/getting_started/build_app.md index 8d11b966dd..7e277db94d 100644 --- a/doc/getting_started/build_app.md +++ b/doc/getting_started/build_app.md @@ -1,5 +1,13 @@ # Build an app +At this point you should have [set up your environment and installed Panel](installation.rst) and been introduced some of the basic ideas and APIs behind Panel in the [Core Concepts](core_concepts.md) guide. + +However the easiest way to get started with Panel is to play around with it yourself. In this section we're going to be building a basic application using a public dataset and add some interactivity. The easiest way to follow along is to copy the examples and launch a Jupyter notebook session as described in the [installation guide](installation.rst]. + +:::{important} +This guide is written for an interactive environment such as Jupyter notebooks. The interactive widgets will not work in a static version of this documentation. +::: + ```{eval-rst} .. notebook:: panel ../../examples/getting_started/Introduction.ipynb ``` diff --git a/doc/getting_started/installation.rst b/doc/getting_started/installation.md similarity index 53% rename from doc/getting_started/installation.rst rename to doc/getting_started/installation.md index 8512019737..935dd98c14 100644 --- a/doc/getting_started/installation.rst +++ b/doc/getting_started/installation.md @@ -1,10 +1,11 @@ -Installation -============ +# Installation -|CondaPyViz|_ |CondaDefaults|_ |PyPI|_ |License|_ +[![conda pyviz badge](https://img.shields.io/conda/v/pyviz/panel.svg)](https://anaconda.org/pyviz/panel) +[![conda defaults badge](https://img.shields.io/conda/v/anaconda/panel.svg?label=conda%7Cdefaults)](https://anaconda.org/anaconda/panel) +[![PyPI badge](https://img.shields.io/pypi/v/panel.svg)](https://pypi.python.org/pypi/panel) +[![License badge](https://img.shields.io/pypi/l/panel.svg)](https://github.com/holoviz/panel/blob/master/LICENSE.txt) -Prerequisites -------------- +## Prerequisites Before you can get started with Panel you are going to need a couple of things: @@ -12,84 +13,86 @@ Before you can get started with Panel you are going to need a couple of things: 2. Python 3.7 - Python 3.10 -3. `pip `_ or `conda `_ +3. [pip](https://pip.pypa.io/en/stable/installation/) or [conda](https://conda.pydata.org/docs/) -Setting up Python ------------------- +## Setting up Python -The recommended way to install Panel on all operating systems is using the `conda `_ command provided by `Anaconda `_ or `Miniconda `_. If you are not familiar with command line interfaces we recommend you use the `Anaconda `_ installer and use `Anaconda Navigator `_. +The recommended way to install Panel on all operating systems is using the [conda](https://conda.pydata.org/docs/)_ command provided by [Anaconda](http://docs.continuum.io/anaconda/install) or [Miniconda](http://conda.pydata.org/miniconda.html). If you are not familiar with command line interfaces we recommend you use the [Anaconda](http://docs.continuum.io/anaconda/install) installer and use [Anaconda Navigator](https://docs.anaconda.com/anaconda/navigator). Alternatively you can also set up your own Python installation and manage your environment using a different environment management tool such as: - - `pipenv `_ - - `poetry `_ - - `virtualenv `_ +- [pipenv](https://pipenv-fork.readthedocs.io/en/latest/) +- [poetry](https://python-poetry.org/) +- [virtualenv](https://virtualenv.pypa.io/en/latest/) -Installing Panel ----------------- +## Installing Panel -Once you have set up Python and chosen an environment management tool install Panel using either ``conda``:: +Once you have set up Python and chosen an environment management tool install Panel using either ``conda``: - conda install -c pyviz panel +```bash +conda install -c pyviz panel +``` -or using ``pip``:: +or using ``pip``: - pip install panel +```bash +pip install panel +``` -Developing in different editors -------------------------------- +## Getting the examples -Editor + Server -^^^^^^^^^^^^^^^ +Most guides and examples that are rendered as part of the documentation are in fact written as Jupyter notebooks. We recommend that if you want to follow along with the examples you copy the examples to a local path, e.g. to copy to the current path use: -You can edit your Panel code as a ``.py`` file in any text editor, marking the objects you want to render as ``.servable()``, then launch a server with:: +```bash +panel examples --path ./ +``` - panel serve my_script.py --show --autoreload +Once the examples are copied switch to the directory you copied them to and launch a Jupyter notebook, e.g. with: + +```bash +jupyter lab +``` + +Now you can navigate through the getting started and user guides and the various (reference) gallery examples. + +## Developing in different editors + +### Editor + Server + +You can edit your Panel code as a ``.py`` file in any text editor, marking the objects you want to render as ``.servable()``, then launch a server with: + +```bash +panel serve my_script.py --show --autoreload`` +``` to open a browser tab showing your app or dashboard and backed by a live Python process. The ``--autoreload`` flag ensures that the app reloads whenever you make a change to the Python source. -JupyterLab and Classic notebook -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### JupyterLab and Classic notebook In the classic Jupyter notebook environment and JupyterLab, first make sure to load the ``pn.extension()``. Panel objects will then render themselves if they are the last item in a notebook cell. For versions of ``jupyterlab>=3.0`` the necessary extension is automatically bundled in the ``pyviz_comms`` package, which must be >=2.0. However note that for version of ``jupyterlab<3.0`` you must also manually install the JupyterLab extension with:: +g +``` +jupyter labextension install @pyviz/jupyterlab_pyviz +``` - jupyter labextension install @pyviz/jupyterlab_pyviz - -Google Colab -^^^^^^^^^^^^ +### Google Colab In the Google Colaboratory notebook, first make sure to load the `pn.extension()`. Panel objects will then render themselves if they are the last item in a notebook cell. Please note that in Colab rendering for each notebook cell is isolated, which means that every cell must reload the Panel extension code separately. This will result in somewhat slower and larger notebook than with other notebook technologies. -VSCode notebook -^^^^^^^^^^^^^^^ +### VSCode notebook Visual Studio Code (VSCode) versions 2020.4.74986 and later support ipywidgets, and Panel objects can be used as ipywidgets since Panel 0.10 thanks to `jupyter_bokeh`, which means that you can now use Panel components interactively in VSCode. Ensure you install `jupyter_bokeh` with `pip install jupyter_bokeh` or `conda install -c bokeh jupyter_bokeh` and then enable the extension with `pn.extension()`. -nteract and other ipywidgets notebooks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### nteract and other ipywidgets notebooks In other notebook environments that support rendering ipywidgets interactively, such as nteract, you can use the same underlying ipywidgets support as for vscode: Install ``jupyter_bokeh`` and then use ``pn.extension(comms='ipywidgets')``. -Other environments -^^^^^^^^^^^^^^^^^^ +### Other environments If your development environment offers embedded Python processes but does not support ipywidgets or Jupyter "comms" (communication channels), you will notice that some or all interactive functionality is missing. Some widgets that operate only in JavaScript will work fine, but others require communication channels between JavaScript and Python. In such cases you can either request ipywidgets or Panel support from the editor or environment, or else use the Editor + Server approach above. -Get help --------- - -If you get stuck for any reason come join our `helpful community Discourse forum `_ and someone will come to your aid. - -.. |CondaPyViz| image:: https://img.shields.io/conda/v/pyviz/panel.svg -.. _CondaPyViz: https://anaconda.org/pyviz/panel - -.. |CondaDefaults| image:: https://img.shields.io/conda/v/anaconda/panel.svg?label=conda%7Cdefaults -.. _CondaDefaults: https://anaconda.org/anaconda/panel - -.. |PyPI| image:: https://img.shields.io/pypi/v/panel.svg -.. _PyPI: https://pypi.python.org/pypi/panel +## Get help -.. |License| image:: https://img.shields.io/pypi/l/panel.svg -.. _License: https://github.com/pyviz/panel/blob/master/LICENSE.txt +If you get stuck for any reason come join our [helpful community Discourse forum](https://discourse.holoviz.org/c/panel/5) and someone will come to your aid.