Update documentation and small Pixi improvements (#6200)

holoviz · May 3, 2024 · b1fe1cf · b1fe1cf
1 parent 1dbea2c
commit b1fe1cf
Show file tree

Hide file tree

Showing 38 changed files with 508 additions and 589 deletions.
diff --git a/.gitattributes b/.gitattributes
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -44,6 +44,7 @@ jobs:
         with:
           environments: "build"
           download-data: false
+          install: false
       - name: conda build
         run: pixi run -e build build-conda
       - uses: actions/upload-artifact@v4
@@ -91,6 +92,7 @@ jobs:
         with:
           environments: "build"
           download-data: false
+          install: false
       - name: Build package
         run: pixi run -e build build-pip
       - uses: actions/upload-artifact@v4
@@ -114,8 +116,12 @@ jobs:
           path: dist/
       - name: Install package
         run: python -m pip install dist/*.whl
-      - name: Test package
+      - name: Import package
         run: python -c "import $PACKAGE; print($PACKAGE.__version__)"
+      - name: Install test dependencies
+        run: python -m pip install "$(ls dist/*whl)[tests]"
+      - name: Test package
+        run: python -m pytest --pyargs $PACKAGE --color=yes
 
   pip_publish:
     name: Publish PyPI

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -20,28 +20,27 @@ on:
   schedule:
     - cron: "0 14 * * SUN"
 
+defaults:
+  run:
+    shell: bash -el {0}
+
 jobs:
   pixi_lock:
     name: Pixi lock
     runs-on: ubuntu-latest
     steps:
       - uses: holoviz-dev/holoviz_tasks/pixi_lock@pixi
 
-  build_docs:
-    name: Documentation
+  docs_build:
+    name: Build Documentation
     needs: [pixi_lock]
-    runs-on: "ubuntu-latest"
-    timeout-minutes: 120
-    defaults:
-      run:
-        shell: bash -el {0}
+    runs-on: "macos-latest"
+    timeout-minutes: 180
+    outputs:
+      tag: ${{ steps.vars.outputs.tag }}
     env:
-      DESC: "Documentation build"
       MPLBACKEND: "Agg"
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-      AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION }}
       MOZ_HEADLESS: 1
       PANEL_EMBED: "true"
       PANEL_EMBED_JSON: "true"
@@ -51,22 +50,44 @@ jobs:
       - uses: holoviz-dev/holoviz_tasks/pixi_install@pixi
         with:
           environments: docs
+      - name: Build documentation
+        run: pixi run -e docs docs-build
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: docs
+          if-no-files-found: error
+          path: builtdocs
       - name: Set output
         id: vars
         run: echo "tag=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
-      - name: Build documentation
-        run: pixi run -e docs docs-build
+
+  docs_publish:
+    name: Publish Documentation
+    runs-on: "ubuntu-latest"
+    needs: [docs_build]
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+      AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: builtdocs/
+      - name: Set output
+        id: vars
+        run: echo "tag=${{ needs.docs_build.outputs.tag }}" >> $GITHUB_OUTPUT
       - name: upload dev
         if: |
           (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'dev') ||
           (github.event_name == 'push' && (contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc')))
         run: |
-          pipx install awscli
           aws s3 sync --quiet ./builtdocs s3://dev.holoviews.org/
       - name: upload main
         if: |
           (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'main') ||
           (github.event_name == 'push' && !(contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc')))
         run: |
-          pipx install awscli
           aws s3 sync --quiet ./builtdocs s3://holoviews.org/
diff --git a/.github/workflows/nightly_lock.yaml b/.github/workflows/nightly_lock.yaml
@@ -8,7 +8,15 @@ jobs:
   pixi_lock:
     name: Pixi lock
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: holoviz-dev/holoviz_tasks/pixi_lock@pixi
-
-  # TODO: Upload the lock-file
+      - name: Upload lock-file to S3
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_DEFAULT_REGION: "eu-west-1"
+          PACKAGE: "holoviews"
+        run: |
+          cp pixi.lock $(date +%Y-%m-%d)-pixi.lock
+          aws s3 cp ./$(date +%Y-%m-%d)-pixi.lock s3://assets.holoviz.org/lock/$PACKAGE/
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -37,6 +37,7 @@ env:
   PYTHONIOENCODING: "utf-8"
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   DASK_DATAFRAME__QUERY_PLANNING: false
+  COV: "--cov=./holoviews --cov-report=xml"
 
 jobs:
   pre_commit:
@@ -83,16 +84,16 @@ jobs:
         if: env.MATRIX_OPTION == 'default'
         run: |
           MATRIX=$(jq -nsc '{
-              "os": ["ubuntu-latest", "macos-14", "windows-latest"],
+              "os": ["ubuntu-latest", "macos-latest", "windows-latest"],
               "environment": ["test-39", "test-312"]
           }')
           echo "MATRIX=$MATRIX" >> $GITHUB_ENV
       - name: Set test matrix with 'full' option
         if: env.MATRIX_OPTION == 'full'
         run: |
           MATRIX=$(jq -nsc '{
-              "os": ["ubuntu-latest", "macos-14", "windows-latest"],
-              "environment": ["test-39", "test-310", "test311", "test312"]
+              "os": ["ubuntu-latest", "macos-latest", "windows-latest"],
+              "environment": ["test-39", "test-310", "test-311", "test-312"]
           }')
           echo "MATRIX=$MATRIX" >> $GITHUB_ENV
       - name: Set test matrix with 'downstream' option
@@ -132,7 +133,7 @@ jobs:
       - name: Test Unit
         if: needs.setup.outputs.code_change == 'true'
         run: |
-          pixi run -e ${{ matrix.environment }} test-unit --cov=./holoviews --cov-report=xml
+          pixi run -e ${{ matrix.environment }} test-unit $COV
       - name: Test Examples
         if: needs.setup.outputs.code_change == 'true'
         run: |
@@ -162,7 +163,17 @@ jobs:
       - name: Test UI
         if: needs.setup.outputs.code_change == 'true'
         run: |
-          pixi run -e ${{ matrix.environment }} test-ui --cov=./holoviews --cov-report=xml
+          # Create a .uicoveragerc file to set the concurrency library to greenlet
+          # https://github.com/microsoft/playwright-python/issues/313
+          echo "[run]\nconcurrency = greenlet" > .uicoveragerc
+          FAIL="--screenshot only-on-failure --full-page-screenshot --output ui_screenshots --tracing retain-on-failure"
+          pixi run -e ${{ matrix.environment }} test-ui $COV --cov-config=.uicoveragerc $FAIL
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: ui_screenshots_${{ runner.os }}
+          path: ./ui_screenshots
+          if-no-files-found: ignore
       - uses: codecov/codecov-action@v4
         if: needs.setup.outputs.code_change == 'true'
         with:

diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ itself.**
 | Downloads | ![https://pypistats.org/packages/holoviews](https://img.shields.io/pypi/dm/holoviews?label=pypi) ![https://anaconda.org/pyviz/holoviews](https://pyviz.org/_static/cache/holoviews_conda_downloads_badge.svg)
 | Build Status | [![Build Status](https://github.com/holoviz/holoviews/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/holoviz/holoviews/actions/workflows/test.yaml?query=branch%3Amain) |
 | Coverage | [![codecov](https://codecov.io/gh/holoviz/holoviews/branch/main/graph/badge.svg)](https://codecov.io/gh/holoviz/holoviews) |
-| Latest dev release | [![Github tag](https://img.shields.io/github/tag/holoviz/holoviews.svg?label=tag&colorB=11ccbb)](https://github.com/holoviz/holoviews/tags) [![dev-site](https://img.shields.io/website-up-down-green-red/http/dev.holoviews.org.svg?label=dev%20website)](http://dev.holoviews.org) |
+| Latest dev release | [![Github tag](https://img.shields.io/github/tag/holoviz/holoviews.svg?label=tag&colorB=11ccbb)](https://github.com/holoviz/holoviews/tags) [![dev-site](https://img.shields.io/website-up-down-green-red/http/dev.holoviews.org.svg?label=dev%20website)](https://dev.holoviews.org) |
 | Latest release | [![Github release](https://img.shields.io/github/release/holoviz/holoviews.svg?label=tag&colorB=11ccbb)](https://github.com/holoviz/holoviews/releases) [![PyPI version](https://img.shields.io/pypi/v/holoviews.svg?colorB=cc77dd)](https://pypi.python.org/pypi/holoviews) [![holoviews version](https://img.shields.io/conda/v/pyviz/holoviews.svg?colorB=4488ff&style=flat)](https://anaconda.org/pyviz/holoviews) [![conda-forge version](https://img.shields.io/conda/v/conda-forge/holoviews.svg?label=conda%7Cconda-forge&colorB=4488ff)](https://anaconda.org/conda-forge/holoviews) [![defaults version](https://img.shields.io/conda/v/anaconda/holoviews.svg?label=conda%7Cdefaults&style=flat&colorB=4488ff)](https://anaconda.org/anaconda/holoviews) |
 | Python | [![Python support](https://img.shields.io/pypi/pyversions/holoviews.svg)](https://pypi.org/project/holoviews/) |
 | Docs | [![DocBuildStatus](https://github.com/holoviz/holoviews/workflows/docs/badge.svg?query=branch%3Amain)](https://github.com/holoviz/holoviews/actions?query=workflow%3Adocs+branch%3Amain) [![site](https://img.shields.io/website-up-down-green-red/https/holoviews.org.svg)](https://holoviews.org) |
@@ -22,80 +22,59 @@ and simple. With HoloViews, you can usually express what you want to do
 in very few lines of code, letting you focus on what you are trying to
 explore and convey, not on the process of plotting.
 
-Check out the [HoloViews web site](http://holoviews.org) for extensive examples and documentation.
+Check out the [HoloViews web site](https://holoviews.org) for extensive examples and documentation.
 
 <div>
 <div >
-  <a href="http://holoviews.org/gallery/demos/bokeh/iris_splom_example.html">
-    <img src="http://holoviews.org/_images/iris_splom_example_large.png" width='20%'> </img> </a>
-  <a href="http://holoviews.org/getting_started/Gridded_Datasets.html">
+  <a href="https://holoviews.org/gallery/demos/bokeh/iris_splom_example.html">
+    <img src="https://holoviews.org/_images/iris_splom_example_large.png" width='20%'> </img> </a>
+  <a href="https://holoviews.org/getting_started/Gridded_Datasets.html">
     <img src="https://assets.holoviews.org/collage/cells.png" width='22%'> </img>  </a>
-  <a href="http://holoviews.org/gallery/demos/bokeh/scatter_economic.html">
-    <img src="http://holoviews.org/_images/scatter_economic_large.png" width='43%'> </img> </a>
+  <a href="https://holoviews.org/gallery/demos/bokeh/scatter_economic.html">
+    <img src="https://holoviews.org/_images/scatter_economic_large.png" width='43%'> </img> </a>
 </div>
 
 <div >
-  <a href="http://holoviews.org/gallery/demos/bokeh/square_limit.html">
-    <img src="http://holoviews.org/_images/square_limit_large.png" width='20%'> </a>
-  <a href="http://holoviews.org/gallery/demos/bokeh/bars_economic.html">
-    <img src="http://holoviews.org/_images/bars_economic.png" width='20%'> </a>
-  <a href="http://holoviews.org/gallery/demos/bokeh/texas_choropleth_example.html">
-    <img src="http://holoviews.org/_images/texas_choropleth_example_large.png" width='20%'> </a>
-  <a href="http://holoviews.org/gallery/demos/bokeh/verhulst_mandelbrot.html">
-    <img src="http://holoviews.org/_images/verhulst_mandelbrot.png" width='20%'> </a>
+  <a href="https://holoviews.org/gallery/demos/bokeh/square_limit.html">
+    <img src="https://holoviews.org/_images/square_limit_large.png" width='20%'> </a>
+  <a href="https://holoviews.org/gallery/demos/bokeh/bars_economic.html">
+    <img src="https://holoviews.org/_images/bars_economic.png" width='20%'> </a>
+  <a href="https://holoviews.org/gallery/demos/bokeh/texas_choropleth_example.html">
+    <img src="https://holoviews.org/_images/texas_choropleth_example_large.png" width='20%'> </a>
+  <a href="https://holoviews.org/gallery/demos/bokeh/verhulst_mandelbrot.html">
+    <img src="https://holoviews.org/_images/verhulst_mandelbrot.png" width='20%'> </a>
 </div>
 <div >
-    <a href="http://holoviews.org/gallery/demos/bokeh/dropdown_economic.html">
+    <a href="https://holoviews.org/gallery/demos/bokeh/dropdown_economic.html">
       <img src="https://assets.holoviews.org/collage/dropdown.gif" width='31%'> </a>
-    <a href="http://holoviews.org/gallery/demos/bokeh/dragon_curve.html">
+    <a href="https://holoviews.org/gallery/demos/bokeh/dragon_curve.html">
       <img src="https://assets.holoviews.org/collage/dragon_fractal.gif" width='26%'> </a>
-    <a href="http://holoviews.org/gallery/apps/bokeh/nytaxi_hover.html">
+    <a href="https://holoviews.org/gallery/apps/bokeh/nytaxi_hover.html">
       <img src="https://assets.holoviews.org/collage/ny_datashader.gif" width='31%'> </a>
 </div>
 </div>
 
 # Installation
 
-HoloViews works with
-[Python](https://github.com/holoviz/holoviews/actions/workflows/test.yaml)
-on Linux, Windows, or Mac, and works seamlessly with
-[Jupyter Notebook and JupyterLab](https://jupyter.org).
+HoloViews works with [Python](https://github.com/holoviz/holoviews/actions/workflows/test.yaml)
+on Linux, Windows, or Mac, and works seamlessly with [Jupyter Notebook and JupyterLab](https://jupyter.org).
 
-The recommended way to install HoloViews is using the
-[conda](https://docs.conda.io/projects/conda/en/latest/index.html) command provided by
-[Anaconda](https://docs.anaconda.com/free/anaconda/install/) or
-[Miniconda](https://docs.conda.io/en/latest/miniconda.html):
+You can install HoloViews either with `conda` or `pip`, for more information see the [install guide](https://holoviews.org/install.html).
 
     conda install holoviews
 
-This command will install the typical packages most useful with
-HoloViews, though HoloViews itself depends only on
-[Numpy](https://numpy.org) [Pandas](https://pandas.pydata.org) and [Param](https://param.holoviz.org).
-Additional installation and configuration options are described in the
-[user guide](https://holoviews.org/user_guide/Installing_and_Configuring.html).
+    pip install holoviews
 
-You can also clone holoviews directly from GitHub and install it with:
+# Developer Guide
 
-    git clone git://github.com/holoviz/holoviews.git
-    cd holoviews
-    pip install -e .
+If you want to help develop HoloViews, you can checkout the [developer guide](https://dev.holoviews.org/developer_guide/index.html),
+this guide will help you get set-up. Making it easy to contribute.
 
-## Usage
+# Support & Feedback
 
-Once you've installed HoloViews, you can get a copy of all the examples shown on this website:
-
-    holoviews --install-examples
-    cd holoviews-examples
-
-Now you can launch Jupyter Notebook or JupyterLab to explore them:
-
-    jupyter notebook
-
-    jupyter lab
+If you find any bugs or have any feature suggestions please file a GitHub
+[issue](https://github.com/holoviz/holoviews/issues).
 
-For more details on setup and configuration see [our website](https://holoviews.org/user_guide/Installing_and_Configuring.html).
+If you have any usage questions, please ask them on [HoloViz Discourse](https://discourse.holoviz.org/),
 
-For general discussion, we have a [discord channel](https://discord.gg/AXRHnJU6sP).
-If you find any bugs or have any feature suggestions please file a GitHub
-[issue](https://github.com/holoviz/holoviews/issues)
-or submit a [pull request](https://help.github.com/articles/about-pull-requests).
+For general discussion, we have a [Discord channel](https://discord.gg/AXRHnJU6sP).
diff --git a/doc/developer_guide/index.md b/doc/developer_guide/index.md
@@ -27,7 +27,7 @@ To contribute to HoloViews, you will also need [Github account](https://github.c
 
 ### Pixi
 
-Developing all aspects of HoloViews requires a wide range of packages in different environments. To make this more manageable, Pixi manages the developer experience. To install Pixi, follow [this guide](https://prefix.dev/docs/pixi/overview#installation).
+Developing all aspects of HoloViews requires a wide range of packages in different environments. To make this more manageable, Pixi manages the developer experience. To install Pixi, follow [this guide](https://pixi.sh/latest/#installation).
 
 #### Glossary
 
@@ -40,7 +40,9 @@ For more information, see the [Pixi documentation](https://pixi.sh/latest/).
 :::{admonition} Note
 :class: info
 
-The first time you run `pixi`, it will create a `.pixi` directory in the source directory. This directory will contain all the files needed for the virtual environments. The `.pixi` directory can be large, so don't accidentally put it into a cloud-synced directory.
+The first time you run `pixi`, it will create a `.pixi` directory in the source directory.
+This directory will contain all the files needed for the virtual environments.
+The `.pixi` directory can be large, so it is advised not to put the source directory into a cloud-synced directory.
 :::
 
 ## Installing the Project
@@ -51,9 +53,10 @@ The source code for the HoloViews project is hosted on [GitHub](https://github.c
 
 1. Go to [github.com/holoviz/holoviews](https://github.com/holoviz/holoviews)
 2. [Fork the repository](https://docs.github.com/en/get-started/quickstart/contributing-to-projects#forking-a-repository)
-3. Run in your terminal: `git clone https://github.com/<Your UserName Here>/holoviews`
+3. Run in your terminal: `git clone https://github.com/<Your Username Here>/holoviews`
 
-The instructions for cloning above created a `holoviews` directory at your file system location. This `holoviews` directory is the _source checkout_ for the remainder of this document, and your current working directory is this directory.
+The instructions for cloning above created a `holoviews` directory at your file system location.
+This `holoviews` directory is the _source checkout_ for the remainder of this document, and your current working directory is this directory.
 
 ### Fetch tags from upstream
 
@@ -73,12 +76,15 @@ To start developing, run the following command
 pixi install
 ```
 
-The first time you run it, it will create a `lock-file` with information for all available environments. This command will take a minute or so to run. When this is finished, it is possible to run the following command to download the data HoloViews tests and examples depend upon.
+The first time you run it, it will create a `pixi.lock` file with information for all available environments. This command will take a minute or so to run.
+When this is finished, it is possible to run the following command to download the data HoloViews tests and examples depend upon.
 
 ```bash
 pixi run download-data
 ```
 
+All available tasks can be found by running `pixi task list`, the following sections will give a brief introduction to the most common tasks.
+
 ### Editable install
 
 It can be advantageous to install the HoloViews in [editable mode](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs):
@@ -129,7 +135,7 @@ pixi run test-unit
 
 The task is available in the following environments: `test-39`, `test-310`, `test-311`, `test-312`, and `test-core`. Where the first ones have the same environments except for different Python versions, and `test-core` only has a core set of dependencies.
 
-If you haven't set the environment flag in the command, you need to select which one of the environments to use.
+If you haven't set the environment flag in the command, a menu will help you select which one of the environments to use.
 
 ### Example tests
 
@@ -168,7 +174,7 @@ A development version of HoloViews can be found [here](https://dev.holoviews.org
 
 ## Build
 
-HoloViews have to build tasks. One is for installing packages with Pip, and the other is for installing packages with Conda.
+HoloViews have two build tasks. One is for building packages for Pip, and the other is for building packages for Conda.
 
 ```bash
 pixi run build-pip