Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 56abbd9

Browse files
kushalkolarkushalkolar
authored
docs reorganization take 3 (#639)
* misc -> misc-dev * remove empty README file * examples/desktop -> examples * update examples * remove old nb example stuff * set offset for both dims for selectors * update actions * rename lint -> black * update docs to use pydata sphinx theme and switcher * update toctrees w.r.t pydata theme * update deploy docs to deploy to version dir * fix github var name * update headings * update links and homepage * tryign to learn github actions properly blargh * add a / * update docs deploy * update readme and guide * update readme * comments in workflow * force fail if there are doc build warnings * update job name * no longer need separate doc CI test * fix headings * activate minigalleries * comment on PR with link to built docs * proper link * update intersphinx for fastplotlib * remove fastplotlib from intersphinx inventory for now
1 parent 3bd6de2 commit 56abbd9

File tree

147 files changed

+850
-2020
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

147 files changed

+850
-2020
lines changed

‎.github/workflows/black.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Lint
1+
name: black
22

33
on:
44
push:

‎.github/workflows/ci.yml

Lines changed: 2 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -14,39 +14,6 @@ on:
1414
- ready_for_review
1515

1616
jobs:
17-
docs-build:
18-
name: Docs
19-
runs-on: ubuntu-latest
20-
timeout-minutes: 10
21-
if: ${{ !github.event.pull_request.draft }}
22-
strategy:
23-
fail-fast: false
24-
steps:
25-
- uses: actions/checkout@v3
26-
- name: Set up Python 3.11
27-
uses: actions/setup-python@v4
28-
with:
29-
python-version: 3.11
30-
- name: Install llvmpipe and lavapipe for offscreen canvas, and git lfs
31-
run: |
32-
sudo apt-get update -y -qq
33-
sudo apt-get install --no-install-recommends -y libegl1-mesa libgl1-mesa-dri libxcb-xfixes0-dev mesa-vulkan-drivers git-lfs
34-
- name: Install pandoc v3.14, nbsphinx complains about older pandoc versions
35-
run: |
36-
wget https://github.com/jgm/pandoc/releases/download/3.1.4/pandoc-3.1.4-1-amd64.deb
37-
sudo apt-get install ./pandoc-3.1.4-1-amd64.deb
38-
- name: Install dev dependencies
39-
run: |
40-
python -m pip install --upgrade pip setuptools
41-
# remove pygfx from install_requires, we install using pygfx@main
42-
sed -i "/pygfx/d" ./setup.py
43-
pip install git+https://github.com/pygfx/pygfx.git@main
44-
pip install -e ".[notebook,docs,tests]"
45-
- name: Build docs
46-
run: |
47-
cd docs
48-
make html SPHINXOPTS="-W --keep-going"
49-
5017
test-build-full:
5118
name: Test Linux, notebook + offscreen
5219
runs-on: ubuntu-latest
@@ -101,7 +68,7 @@ jobs:
10168
with:
10269
name: screenshot-diffs
10370
path: |
104-
examples/desktop/diffs
71+
examples/diffs
10572
examples/notebooks/diffs
10673
10774
test-build-desktop:
@@ -157,7 +124,7 @@ jobs:
157124
with:
158125
name: screenshot-diffs
159126
path: |
160-
examples/desktop/diffs
127+
examples/diffs
161128
162129
# test-build-full-mac:
163130
# name: Test Mac, notebook + glfw

‎.github/workflows/docs-deploy.yml

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
name: Deploy docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
types:
11+
- opened
12+
- reopened
13+
- synchronize
14+
- ready_for_review
15+
release:
16+
types: [published]
17+
18+
jobs:
19+
build-docs:
20+
name: "Build and deploy docs"
21+
runs-on: ubuntu-latest
22+
if: ${{ !github.event.pull_request.draft }}
23+
permissions:
24+
pull-requests: write
25+
strategy:
26+
fail-fast: false
27+
steps:
28+
- uses: actions/checkout@v4
29+
with:
30+
lfs: true
31+
- name: Set up Python
32+
uses: actions/setup-python@v5
33+
with:
34+
python-version: 3.12
35+
- name: Install llvmpipe and lavapipe for offscreen canvas
36+
run: |
37+
sudo apt-get update -y -qq
38+
sudo apt-get install --no-install-recommends -y ffmpeg libegl1-mesa libgl1-mesa-dri libxcb-xfixes0-dev mesa-vulkan-drivers git-lfs
39+
- name: Install dev dependencies
40+
run: |
41+
python -m pip install --upgrade pip setuptools
42+
# remove pygfx from install_requires, we install using pygfx@main
43+
sed -i "/pygfx/d" ./setup.py
44+
pip install git+https://github.com/pygfx/pygfx.git@main
45+
pip install -e ".["docs"]"
46+
- name: Show wgpu backend
47+
run:
48+
python -c "from examples.tests.testutils import wgpu_backend; print(wgpu_backend)"
49+
- name: build docs
50+
run: |
51+
cd docs
52+
RTD_BUILD=1 make html SPHINXOPTS="-W --keep-going"
53+
54+
# set environment variable `DOCS_VERSION_DIR` to either the pr-branch name, "dev", or the release version tag
55+
- name: set output pr
56+
if: ${{ github.ref != 'refs/heads/main' }}
57+
# sets dir to the branch name when it's a PR
58+
# ex: fastplotlib.org/ver/feature-branch
59+
run: echo "DOCS_VERSION_DIR=$GITHUB_HEAD_REF" >> "$GITHUB_ENV"
60+
61+
- name: set output release
62+
if: ${{ github.ref_type == 'tag' }}
63+
# sets dir to the release version tag, ex. v0.3.0 (I think...)
64+
# ex: fastplotlib.org/ver/v0.3.0
65+
run: echo "DOCS_VERSION_DIR=$GITHUB_REF_NAME" >> "$GITHUB_ENV"
66+
67+
- name: set output dev
68+
if: ${{ github.ref == 'refs/heads/main' }}
69+
# any push to main goes to fastplotlib.org/ver/dev
70+
run: echo "DOCS_VERSION_DIR=dev" >> "$GITHUB_ENV"
71+
72+
# upload docs via FTP
73+
- name: Deploy docs
74+
uses: SamKirkland/[email protected]
75+
with:
76+
server: ${{ secrets.DOCS_SERVER }}
77+
username: ${{ secrets.DOCS_USERNAME }}
78+
password: ${{ secrets.DOCS_PASSWORD }}
79+
# built docs
80+
local-dir: docs/build/html/
81+
# output subdir based on the previous if statements
82+
server-dir: ./ver/${{ env.DOCS_VERSION_DIR }}/
83+
84+
# comment on PR to provide link to built docs
85+
- name: Add PR link in comment
86+
if: ${{ github.event_name == 'pull_request' }}
87+
uses: mshick/add-pr-comment@v2
88+
with:
89+
message: |
90+
📚 Docs preview built and uploaded! https://www.fastplotlib.org/ver/${{ env.DOCS_VERSION_DIR }}
91+
92+
# also deploy to root if this is a new release
93+
# i.e., fastplotlib.org/ points to docs for the latest release
94+
- name: Deploy docs
95+
if: ${{ github.ref_type == 'tag' }}
96+
uses: SamKirkland/[email protected]
97+
with:
98+
server: ${{ secrets.DOCS_SERVER }}
99+
username: ${{ secrets.DOCS_USERNAME }}
100+
password: ${{ secrets.DOCS_PASSWORD }}
101+
local-dir: docs/build/html/
102+
server-dir: ./ # deploy to the root dir
103+
exclude: | # don't delete the /ver/ dir
104+
**/ver/**

‎.github/workflows/screenshots.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,5 +55,5 @@ jobs:
5555
with:
5656
name: screenshots
5757
path: |
58-
examples/desktop/screenshots/
58+
examples/screenshots/
5959
examples/notebooks/screenshots/

‎README.md

Lines changed: 39 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,22 @@
44

55
---
66

7-
[![CI](https://github.com/kushalkolar/fastplotlib/actions/workflows/ci.yml/badge.svg)](https://github.com/kushalkolar/fastplotlib/actions/workflows/ci.yml)
7+
[![CI](https://github.com/fastplotlib/fastplotlib/actions/workflows/ci.yml/badge.svg)](https://github.com/fastplotlib/fastplotlib/actions/workflows/ci.yml)
88
[![PyPI version](https://badge.fury.io/py/fastplotlib.svg)](https://badge.fury.io/py/fastplotlib)
99
[![Documentation Status](https://readthedocs.org/projects/fastplotlib/badge/?version=latest)](https://fastplotlib.readthedocs.io/en/latest/?badge=latest)
1010
[![DOI](https://zenodo.org/badge/485481453.svg)](https://zenodo.org/doi/10.5281/zenodo.13365890)
1111

12-
[**Installation**](https://github.com/kushalkolar/fastplotlib#installation) |
12+
[**Installation**](https://github.com/fastplotlib/fastplotlib#installation) |
1313
[**GPU Drivers**](https://github.com/kushalkolar/fastplotlib#graphics-drivers) |
1414
[**Documentation**](https://github.com/fastplotlib/fastplotlib#documentation) |
1515
[**Examples**](https://github.com/kushalkolar/fastplotlib#examples) |
1616
[**Contributing**](https://github.com/kushalkolar/fastplotlib#heart-contributing)
1717

1818
Next-gen plotting library built using the [`pygfx`](https://github.com/pygfx/pygfx) rendering engine that can utilize [Vulkan](https://en.wikipedia.org/wiki/Vulkan), [DX12](https://en.wikipedia.org/wiki/DirectX#DirectX_12), or [Metal](https://developer.apple.com/metal/) via WGPU, so it is very fast! `fastplotlib` is an expressive plotting library that enables rapid prototyping for large scale explorative scientific visualization.
1919

20-
![scipy-fpl](https://github.com/fastplotlib/fastplotlib/assets/9403332/b981a54c-05f9-443f-a8e4-52cd01cd802a)
21-
22-
### SciPy 2023 Talk
23-
24-
[![fpl_thumbnail](http://i3.ytimg.com/vi/Q-UJpAqljsU/hqdefault.jpg)](https://www.youtube.com/watch?v=Q-UJpAqljsU)
25-
26-
Note that the API is currently evolving quickly. We recommend using the latest notebooks from the repo but the general
27-
concepts are similar to those from the API shown in the video.
20+
> **Note**
21+
>
22+
> `fastplotlib` is currently in the **late alpha stage**, but you're welcome to try it out or contribute! See our [Roadmap](https://github.com/kushalkolar/fastplotlib/issues/55). See this for a discussion on API stability: https://github.com/fastplotlib/fastplotlib/issues/121
2823
2924
# Supported frameworks
3025

@@ -36,43 +31,52 @@ concepts are similar to those from the API shown in the video.
3631
:heavy_check_mark: `wxPython`
3732

3833
**Notes:**\
39-
:heavy_check_mark: Non-blocking Qt/PySide output is supported in ipython and notebooks by using [`%gui qt`](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-gui). This **must** be called *before* importing `fastplotlib`!
34+
:heavy_check_mark: Non-blocking interactive Qt/PySide output is supported in ipython and notebooks, see http://fastplotlib.org/ver/dev/user_guide/guide.html#using-fastplotlib-in-an-interactive-shell \
4035
:grey_exclamation: We do not officially support `jupyter notebook` through `jupyter_rfb`, this may change with notebook v7\
36+
:grey_exclamation: We only officially support jupyterlab for use in notebook. This means we do not support vscode notebooks etc. Jupyterlab is the most reliable way to use `fastplotlib` in notebooks.\
4137
:disappointed: [`jupyter_rfb`](https://github.com/vispy/jupyter_rfb) does not work in collab, see https://github.com/vispy/jupyter_rfb/pull/77
4238

43-
> **Note**
44-
>
45-
> `fastplotlib` is currently in the **late alpha stage**, but you're welcome to try it out or contribute! See our [Roadmap](https://github.com/kushalkolar/fastplotlib/issues/55). See this for a discussion on API stability: https://github.com/fastplotlib/fastplotlib/issues/121
39+
We recommend sticking to jupyter-lab for notebooks. From our experience the usage on other platforms, such as vscode
40+
notebooks, is not optimal.
4641

47-
# Documentation
4842

49-
http://fastplotlib.readthedocs.io/
43+
# Documentation
5044

51-
The examples are interactive if you run them locally on your computer. If someone wants to integrate `pyodide` with `pygfx` we would be able to have live interactive examples on the website!
45+
http://www.fastplotlib.org/
5246

5347
Questions, issues, ideas? You are welcome to post an [issue](https://github.com/fastplotlib/fastplotlib/issues) or post on the [discussion forum](https://github.com/fastplotlib/fastplotlib/discussions)! :smiley:
5448

5549
# Installation
5650

57-
### Minimal, use with your own `Qt` or `glfw` applications
51+
To install use pip:
52+
5853
```bash
59-
pip install fastplotlib
60-
```
54+
# with imgui and jupyterlab
55+
pip install -U "fastplotlib[notebook,imgui]"
6156

62-
**This does not give you `PyQt`/`PySide` or `glfw`, you will have to install your preferred GUI framework separately**.
57+
# minimal install, install glfw, pyqt6 or pyside6 separately
58+
pip install -U fastplotlib
6359

64-
### Notebook
65-
```bash
66-
pip install "fastplotlib[notebook]"
60+
# with imgui
61+
pip install -U "fastplotlib[imgui]"
62+
63+
# to use in jupyterlab, no imgui
64+
pip install -U "fastplotlib[notebook]"
6765
```
6866

69-
**Strongly recommended: install `simplejpeg` for much faster notebook visualization, this requires you to first install [libjpeg-turbo](https://libjpeg-turbo.org/)**
67+
We strongly recommend installing ``simplejpeg`` for use in notebooks, you must first install [libjpeg-turbo](https://libjpeg-turbo.org/)
68+
69+
- If you use ``conda``, you can get ``libjpeg-turbo`` through conda.
70+
- If you are on linux you can get it through your distro's package manager.
71+
- For Windows and Mac compiled binaries are available on their release page: https://github.com/libjpeg-turbo/libjpeg-turbo/releases
72+
73+
Once you have ``libjpeg-turbo``:
7074

7175
```bash
7276
pip install simplejpeg
7377
```
7478

75-
> **Note**
79+
> **Note**[guide.rst](docs%2Fsource%2Fuser_guide%2Fguide.rst)
7680
>
7781
> `fastplotlib` and `pygfx` are fast evolving projects, the version available through pip might be outdated, you will need to follow the "For developers" instructions below if you want the latest features. You can find the release history here: https://github.com/fastplotlib/fastplotlib/releases
7882
@@ -95,42 +99,23 @@ Se [Contributing](https://github.com/fastplotlib/fastplotlib?tab=readme-ov-file#
9599

96100
# Examples
97101

98-
Examples gallery: https://fastplotlib.readthedocs.io/en/latest/_gallery/index.html
99-
100-
> **Note:** `fastplotlib` and `pygfx` are fast evolving, you will probably require the latest `pygfx` and `fastplotlib` from github to use the examples in the main branch.
101-
102-
`fastplotlib` code is identical across notebook (`jupyter`), and desktop use with `Qt`/`PySide` or `glfw`.
103-
104-
Even if you do not intend to use notebooks with `fastplotlib`, the `quickstart.ipynb` tutorial notebook is the best way to get familiar with the API: https://github.com/fastplotlib/fastplotlib/tree/main/examples/notebooks/quickstart.ipynb
105-
106-
The specifics for running `fastplotlib` in different GUI frameworks are:
107-
- Running in `glfw` requires a `fastplotlib.run()` call (which is really just a `wgpu` `run()` call)
108-
- With `Qt` you can encapsulate it within a `QApplication`, see `examples/qt`
109-
- Notebooks plots have ipywidget-based toolbars and widgets. There are plans to move toward an identical in-canvas toolbar with UI elements across all supported frameworks 😄
110-
111-
### Embedding in a `Qt` app
112-
113-
See these for examples on embedding within a Qt app. Note that you can also use `fastplotlib` with qt interactively using `%gui qt` in jupyter or ipython.
114-
115-
https://github.com/fastplotlib/fastplotlib/tree/main/examples/qt
116-
117-
### Notebook examples
102+
Examples gallery: http://fastplotlib.org/ver/dev/_gallery/index.html
118103

119-
Notebook examples are here, these include examples on selector tools.
104+
User guide: http://fastplotlib.org/ver/dev/user_guide/guide.html
120105

121-
https://github.com/fastplotlib/fastplotlib/tree/main/examples/notebooks
106+
`fastplotlib` code is identical across notebook (`jupyterlab`), and desktop use with `Qt`/`PySide` or `glfw`.
122107

123-
### Video
108+
**Notebooks**
124109

125-
Our SciPy 2023 talk walks through numerous demos: https://github.com/fastplotlib/fastplotlib#scipy-talk
110+
The `quickstart.ipynb` tutorial notebook is a great way to get familiar with the API: https://github.com/fastplotlib/fastplotlib/tree/main/examples/notebooks/quickstart.ipynb
126111

127112
## Graphics drivers
128113

129-
You will need a relatively modern GPU (newer integrated GPUs in CPUs are usually fine). Generally if your GPU is from 2017 or later it should be fine.
114+
You will need a relatively modern GPU, modern integrated graphics are usually fine for many use cases. Generally if your GPU is from 2017 or later it should be fine.
130115

131116
For more detailed information, such as use on cloud computing infrastructure, see: https://wgpu-py.readthedocs.io/en/stable/start.html#platform-requirements
132117

133-
Some more information on GPUs is here: https://fastplotlib.readthedocs.io/en/latest/user_guide/gpu.html
118+
Some more information on GPUs is here: http://fastplotlib.org/ver/dev/user_guide/gpu.html
134119

135120
### Windows:
136121
Vulkan drivers should be installed by default on Windows 11, but you will need to install your GPU manufacturer's driver package (Nvidia or AMD). If you have an integrated GPU within your CPU, you might still need to install a driver package too, check your CPU manufacturer's info.
@@ -161,6 +146,6 @@ WGPU uses Metal instead of Vulkan on Mac. You will need at least Mac OSX 10.13.
161146

162147
# :heart: Contributing
163148

164-
We welcome contributions! See the contributing guide: https://github.com/kushalkolar/fastplotlib/blob/main/CONTRIBUTING.md
149+
We welcome contributions! See the contributing guide: https://github.com/fastplotlib/fastplotlib/blob/main/CONTRIBUTING.md
165150

166-
You can also take a look at our [**Roadmap for 2025**](https://github.com/kushalkolar/fastplotlib/issues/55) and [**Issues**](https://github.com/kushalkolar/fastplotlib/issues) for ideas on how to contribute!
151+
You can also take a look at our [**Roadmap for 2025**](https://github.com/fastplotlib/fastplotlib/issues/55) and [**Issues**](https://github.com/fastplotlib/fastplotlib/issues) for ideas on how to contribute!

‎docs/source/_static/switcher.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[
2+
{
3+
"name": "dev/main",
4+
"version": "dev",
5+
"url": "http://www.fastplotlib.org/versions/dev"
6+
}
7+
]

‎docs/source/_templates/autosummary/class.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
.. currentmodule:: {{ module }}
44

55
.. autoclass:: {{ objname }}
6+
7+
.. minigallery:: fastplotlib.{{ objname }}
8+
:add-heading: Examples

‎docs/source/_templates/autosummary/method.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
.. currentmodule:: {{ module }}
44

55
.. automethod:: {{ objname }}
6+
7+
.. minigallery:: fastplotlib.{{ objname }}
8+
:add-heading: Examples

‎docs/source/_templates/autosummary/property.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
.. currentmodule:: {{ module }}
44

55
.. autoproperty:: {{ objname }}
6+
7+
.. minigallery:: fastplotlib.{{ objname }}
8+
:add-heading: Examples

‎docs/source/api/index.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
API Reference
2+
*************
3+
4+
.. toctree::
5+
:caption: API Reference
6+
:maxdepth: 2
7+
8+
layouts/index
9+
graphics/index
10+
graphic_features/index
11+
selectors/index
12+
ui/index
13+
widgets/index
14+
fastplotlib
15+
utils

‎docs/source/api/layouts/index.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Layouts
2+
********
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
7+
imgui_figure
8+
figure
9+
subplot

0 commit comments

Comments
 (0)