diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..61d9402 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,31 @@ +name: ci + +on: + push: + branches: + - master + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Configure Git Credentials + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v4 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install mkdocs-material mkdocstrings[python] pymdown-extensions + - run: mkdocs gh-deploy --force diff --git a/.readthedocs.yaml b/.readthedocs.yaml deleted file mode 100644 index 7ce6fbe..0000000 --- a/.readthedocs.yaml +++ /dev/null @@ -1,19 +0,0 @@ -# Read the Docs configuration file -# https://docs.readthedocs.io/en/stable/config-file/v2.html - -version: 2 - -build: - os: ubuntu-22.04 - tools: - python: "3.8" - -sphinx: - builder: html - # fail_on_warning: true - configuration: doc/source/conf.py - -python: - install: - - requirements: doc/requirements.txt - diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/make.bat b/doc/make.bat deleted file mode 100644 index 6247f7e..0000000 --- a/doc/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index e39c2f4..0000000 --- a/doc/requirements.txt +++ /dev/null @@ -1,6 +0,0 @@ -sphinx -sphinx_immaterial -pyqtgraph -PySide2 -numpy -pyopengl diff --git a/doc/source/conf.py b/doc/source/conf.py deleted file mode 100644 index d81cb40..0000000 --- a/doc/source/conf.py +++ /dev/null @@ -1,96 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# - -import os -import sys -import sphinx_immaterial -#import pathlib as pl -#sys.path.insert(0, pl.Path(__file__).parents[2].absolute()) -path = os.path.dirname(os.path.abspath(__file__)) -sys.path.insert(0, os.path.join(path, '..', '..')) -import mlpyqtgraph - - -# -- Project information ----------------------------------------------------- - -project = 'mlpyqtgraph' -copyright = '2022, Sietze van Buuren' -author = 'Sietze van Buuren' - -# The full version, including alpha/beta/rc tags -release = '0.1' - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx_immaterial', - 'sphinx.ext.autodoc', - 'sphinx.ext.viewcode', - 'sphinx.ext.autosectionlabel', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -add_module_names = False - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_immaterial' - -# material theme options (see theme.conf for more information) -html_theme_options = { - 'toc_title': 'Page Contents', - 'features': [ - 'navigation.expand', - # 'navigation.tabs', - 'navigation.sections', - # 'navigation.instant', - # 'header.autohide', - 'navigation.top', - # 'navigation.tracking', - # 'search.highlight', - 'search.share', - 'toc.follow', - 'toc.sticky', - 'content.tabs.link', - 'announce.dismiss', - ], -} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -rst_epilog = """ -.. role:: raw-html(raw) - :format: html -.. |pyqtgraph| replace:: :raw-html:`pyqtgraph` -.. |matplotlib| replace:: :raw-html:`matplotlib` -""" diff --git a/doc/source/examples.rst b/doc/source/examples.rst deleted file mode 100644 index 8f31258..0000000 --- a/doc/source/examples.rst +++ /dev/null @@ -1,6 +0,0 @@ -Examples -======== - -Please refer to the `examples -`_ directory for -a series of examples that illustrate usage of mlpyqtgraph. diff --git a/doc/source/genindex.rst b/doc/source/genindex.rst deleted file mode 100644 index c07da40..0000000 --- a/doc/source/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. This file is a placeholder and will be replaced - -Index -##### diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst deleted file mode 100644 index 3168e93..0000000 --- a/doc/source/getting_started.rst +++ /dev/null @@ -1,16 +0,0 @@ -Getting started -=============== - -To get started using mlpyqtgraph, it first needs to be installed. Refer to -:ref:`installation page ` for instructions. - -Now, mlpyqtgraph can be used in existing python programs. - -To get started, try out the `full example -`_ -from the `mlpyqtgraph examples -`_. - -.. literalinclude:: ../../examples/full.py - :language: python - :lines: 6- diff --git a/doc/source/index.rst b/doc/source/index.rst deleted file mode 100644 index aa32878..0000000 --- a/doc/source/index.rst +++ /dev/null @@ -1,24 +0,0 @@ -Welcome to mlpyqtgraph's documentation! -======================================= - -mlpyqtgraph enables |matplotlib|\ -like plotting with |pyqtgraph| in existing -python programs. - -Please refer to the :ref:`introduction` for a brief explanation of -mlpyqtgraph or read the :ref:`getting started` to try -mlpyqtgraph out right away. - -.. toctree:: - :hidden: - - mlpyqtgraph - -.. toctree:: - :maxdepth: 2 - - introduction - getting_started - installation - examples - reference/index - genindex diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index a6c25b0..0000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,27 +0,0 @@ -Installation -============ - -mlpyqtgraph is a python package. You can install it just like any other python -package. - -First clone the package from GitHub using ``git``: - -.. code-block:: bash - - git clone https://github.com/swvanbuuren/mlpyqtgraph.git - - -It is recommended to install the mlpyqtgraph package into a virtual enviroment, -e.g. ``venv``. Refer to its `refence documentation -`_ for more details on its creation -and usage. - -After the virtual environment has been created and activated, install the -mlpyqtgraph package using e.g. ``pip``: - -.. code-block:: bash - - pip install /path/to/mlpyqtgraph - -Now, mpyqtgraph can be used whenever the appropriate virtual environment has -been activated. diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst deleted file mode 100644 index 1b6b50f..0000000 --- a/doc/source/introduction.rst +++ /dev/null @@ -1,22 +0,0 @@ -Introduction -============ - -mlpyqtgraph enables |matplotlib|\ -like plotting with |pyqtgraph| in existing -python programs. - -It accomplishes this, by offering an interface very similar to |matplotlib|, -while maintaining key |pyqtgraph| features such as speed and interactivity. - -mlpyqtgraph diverts the existing python program into a dedicated thread, while -using the main thread solely for plotting with pyqtgraph. This is a `requirement -of Qt -`_: the -Graphical User Interface (GUI) is required to run in the main thread (also known -as the "GUI thread"). - -The following example illustrates how mlpyqtgraph can be used in an existing -python program defined in ``main``. - -.. literalinclude:: ../../examples/minimal.py - :language: python - :lines: 5-6, 8-10, 12- diff --git a/doc/source/reference/axes.rst b/doc/source/reference/axes.rst deleted file mode 100644 index 2a37020..0000000 --- a/doc/source/reference/axes.rst +++ /dev/null @@ -1,6 +0,0 @@ -Axes -==== - -.. automodule:: mlpyqtgraph.axes - :members: - :show-inheritance: diff --git a/doc/source/reference/colors.rst b/doc/source/reference/colors.rst deleted file mode 100644 index ba7898a..0000000 --- a/doc/source/reference/colors.rst +++ /dev/null @@ -1,6 +0,0 @@ -Colors -====== - -.. automodule:: mlpyqtgraph.colors - :members: - :show-inheritance: diff --git a/doc/source/reference/config_options.rst b/doc/source/reference/config_options.rst deleted file mode 100644 index ba2ee21..0000000 --- a/doc/source/reference/config_options.rst +++ /dev/null @@ -1,6 +0,0 @@ -Configuration options -===================== - -.. automodule:: mlpyqtgraph.config_options - :members: - :show-inheritance: diff --git a/doc/source/reference/controllers.rst b/doc/source/reference/controllers.rst deleted file mode 100644 index 4f3065d..0000000 --- a/doc/source/reference/controllers.rst +++ /dev/null @@ -1,6 +0,0 @@ -Controllers -=========== - -.. automodule:: mlpyqtgraph.controllers - :members: - :show-inheritance: diff --git a/doc/source/reference/descriptors.rst b/doc/source/reference/descriptors.rst deleted file mode 100644 index b843c2d..0000000 --- a/doc/source/reference/descriptors.rst +++ /dev/null @@ -1,6 +0,0 @@ -Descriptors -=========== - -.. automodule:: mlpyqtgraph.descriptors - :members: - :show-inheritance: diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst deleted file mode 100644 index 1288b1f..0000000 --- a/doc/source/reference/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -API Reference -============= - -This section features the API reference of each module. - -.. toctree:: - - ml_functions - axes - windows - worker - controllers - colors - config_options - descriptors - thread_communicator diff --git a/doc/source/reference/ml_functions.rst b/doc/source/reference/ml_functions.rst deleted file mode 100644 index 275ac03..0000000 --- a/doc/source/reference/ml_functions.rst +++ /dev/null @@ -1,6 +0,0 @@ -Matplotlib-like functions -========================= - -.. automodule:: mlpyqtgraph.ml_functions - :members: - :show-inheritance: diff --git a/doc/source/reference/thread_communicator.rst b/doc/source/reference/thread_communicator.rst deleted file mode 100644 index a227fd7..0000000 --- a/doc/source/reference/thread_communicator.rst +++ /dev/null @@ -1,6 +0,0 @@ -Thread communicator -=================== - -.. automodule:: mlpyqtgraph.thread_communicator - :members: - :show-inheritance: diff --git a/doc/source/reference/windows.rst b/doc/source/reference/windows.rst deleted file mode 100644 index 696b7f9..0000000 --- a/doc/source/reference/windows.rst +++ /dev/null @@ -1,6 +0,0 @@ -Windows -======= - -.. automodule:: mlpyqtgraph.windows - :members: - :show-inheritance: diff --git a/doc/source/reference/worker.rst b/doc/source/reference/worker.rst deleted file mode 100644 index 2f096ea..0000000 --- a/doc/source/reference/worker.rst +++ /dev/null @@ -1,6 +0,0 @@ -Worker -====== - -.. automodule:: mlpyqtgraph.worker - :members: - :show-inheritance: diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..556ec5e --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,4 @@ +# Examples + +Please refer to the [examples](examples) directory for a series of examples that +illustrate usage of mlpyqtgraph. diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..43c222a --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,14 @@ +# Getting started + +To get started using mlpyqtgraph, it first needs to be installed. Refer to +[installation page](Installation) for instructions. + +Now, mlpyqtgraph can be used in existing python programs. + +To get started, try out the [full +example](https://github.com/swvanbuuren/mlpyqtgraph/blob/main/examples/full.py) +from the [mlpyqtgraph examples](examples). + +```python +--8<-- "examples/full.py:6" +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a4f5a26 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,8 @@ +# Welcome to mlpyqtgraph's documentation! + +mlpyqtgraph enables [matplotlib](https://matplotlib.org/)-like plotting with +|[pyqtgraph](https://github.com/pyqtgraph/pyqtgraph) in existing +python programs. + +Please refer to the [](introduction) for a brief explanation of mlpyqtgraph or +read the [getting started](getting_started) to try mlpyqtgraph out right away. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..192322a --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,25 @@ +# Installation + +mlpyqtgraph is a python package. You can install it just like any other python +package. + +First clone the package from GitHub using `git`: + +```bash +git clone https://github.com/swvanbuuren/mlpyqtgraph.git +``` + +It is recommended to install the mlpyqtgraph package into a virtual enviroment, +e.g. `venv`. Refer to its [refence +documentation](https://docs.python.org/3/library/venv.html) for more details on +its creation and usage. + +After the virtual environment has been created and activated, install the +mlpyqtgraph package using e.g. `pip`: + +```bash +pip install /path/to/mlpyqtgraph +``` + +Now, mpyqtgraph can be used whenever the appropriate virtual environment has +been activated. diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..85c868f --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,22 @@ +# Introduction + +mlpyqtgraph enables [matplotlib](https://matplotlib.org/)-like plotting with +|[pyqtgraph](https://github.com/pyqtgraph/pyqtgraph) in existing +python programs. + +It accomplishes this, by offering an interface very similar to |matplotlib|, +while maintaining key |pyqtgraph| features such as speed and interactivity. + +mlpyqtgraph diverts the existing python program into a dedicated thread, while +using the main thread solely for plotting with pyqtgraph. This is a [requirement +of Qt](https://doc.qt.io/qt-6/thread-basics.html#gui-thread-and-worker-thread): +the Graphical User Interface (GUI) is required to run in the main thread (also +known as the "GUI thread"). + +The following example illustrates how mlpyqtgraph can be used in an existing +python program defined in `main`. + + +```python +--8<-- "examples/minimal.py:4" +``` diff --git a/docs/reference/axes.md b/docs/reference/axes.md new file mode 100644 index 0000000..846e21c --- /dev/null +++ b/docs/reference/axes.md @@ -0,0 +1,3 @@ +# Axes + +::: mlpyqtgraph.axes diff --git a/docs/reference/colors.md b/docs/reference/colors.md new file mode 100644 index 0000000..3c7dfa7 --- /dev/null +++ b/docs/reference/colors.md @@ -0,0 +1,3 @@ +# Colors + +::: mlpyqtgraph.colors diff --git a/docs/reference/config_options.md b/docs/reference/config_options.md new file mode 100644 index 0000000..a5c791b --- /dev/null +++ b/docs/reference/config_options.md @@ -0,0 +1,3 @@ +# Configuration options + +::: mlpyqtgraph.config_options diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 0000000..1581205 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,3 @@ +# Code Reference + +This section features the Code reference of each module. diff --git a/docs/reference/ml_functions.md b/docs/reference/ml_functions.md new file mode 100644 index 0000000..00d616b --- /dev/null +++ b/docs/reference/ml_functions.md @@ -0,0 +1,3 @@ +# Matplotlib-like functions + +::: mlpyqtgraph.ml_functions diff --git a/docs/reference/windows.md b/docs/reference/windows.md new file mode 100644 index 0000000..2fc7b77 --- /dev/null +++ b/docs/reference/windows.md @@ -0,0 +1,3 @@ +# Windows + +::: mlpyqtgraph.windows diff --git a/docs/reference/worker.md b/docs/reference/worker.md new file mode 100644 index 0000000..9946eb3 --- /dev/null +++ b/docs/reference/worker.md @@ -0,0 +1,3 @@ +# Workers + +::: mlpyqtgraph.workers diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..6682883 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,49 @@ +site_name: mlpyqtgraph Documentation +site_url: https://swvanbuuren.github.io/mlpyqtgraph/ +repo_url: https://github.com/swvanbuuren/mlpyqtgraph +repo_name: swvanbuuren/mlpyqtgraph + +theme: + name: material + features: + - navigation.sections + - navigation.tabs + - navigation.indexes + +plugins: + - search + - mkdocstrings: + handlers: + python: + options: + show_root_toc_entry: false + +markdown_extensions: + - attr_list + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + + +nav: + - Welcome: + - index.md + - introduction.md + - getting_started.md + - installation.md + - examples.md + - Code Reference: + - reference/index.md + - reference/ml_functions.md + - reference/axes.md + - reference/windows.md + - reference/worker.md + - reference/colors.md + - reference/config_options.md