Merge pull request #4 from TEParsons/main

RF: Implement new test/docs structure

.github/workflows/docs.yaml

@@ -0,0 +1,41 @@
+name: Publish docs
+
+on: push
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: macos-11
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+
+    - name: Install package and dependencies
+      run: |
+        python3 -m pip install -e .[docs]
+    
+    - name: Build docs
+      run: |
+        sphinx-build docs_src docs -b dirhtml
+    
+    - name: Bypass Jekyll
+      run: |
+        echo "" > docs/.nojekyll
+
+    - name: Commit
+      run: |
+        git add --all
+        git commit --all -m "sys: Build documentation"
+    
+    - name: Push
+      uses: ad-m/github-push-action@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: gh-pages
+        force: true

.github/workflows/pypi.yaml

@@ -0,0 +1,42 @@
+name: Publish package
+
+on:
+    workflow_dispatch:
+    push:
+      tags:
+       - '*'
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        environment: pypi
+        permissions:
+          id-token: write
+          contents: write 
+        steps:
+        - uses: actions/checkout@master
+
+        - name: Setup Python
+          uses: actions/setup-python@v3
+          with:
+            python-version: '3.10'
+
+        - name: Install packages
+          run: |
+            python -m pip install build twine
+        
+        - name: Build
+          run: |
+            python -m build
+        
+        - name: Attach binaries
+          if: startsWith(github.ref, 'refs/tags/')
+          uses: softprops/action-gh-release@v2
+          with:
+            token: ${{ secrets.GITHUB_TOKEN }}
+            files: |
+              dist/*
+        
+        - name: Upload to PyPi
+          if: startsWith(github.ref, 'refs/tags/')
+          uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/tests.yaml

@@ -0,0 +1,80 @@
+name: Run tests
+
+on:
+  workflow_dispatch:  # manual
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  mac-tests:
+    name: Run tests on Mac
+    runs-on: macos-11
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+
+    - name: Install package and dependencies
+      run: |
+        python3 -m pip install -e .[tests]
+    
+    - name: Run tests
+      run: |
+        pytest
+  
+  windows-tests:
+    name: Run tests on Windows
+    runs-on: windows-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+
+    - name: Install package and dependencies
+      run: |
+        python3 -m pip install -e .[tests]
+    
+    - name: Run tests
+      run: |
+        pytest
+    
+  linux-tests:
+    name: Run tests on Linux
+    runs-on: ubuntu-latest
+
+    steps:
+        - name: Checkout
+          uses: actions/checkout@v4
+
+        - name: Set up Python
+          uses: actions/setup-python@v4
+          with:
+            python-version: "3.10"
+
+        - name: Prepare to build wx
+          run: |
+            python3 -m pip install wheel six distro attrdict3
+            sudo apt-get update
+            sudo apt-get install -y -qq python3-dev libgtk-3-dev
+            sudo apt-get install -y -qq libgstreamer1.0-0 gstreamer1.0-plugins-base
+            sudo apt-get install -y -qq libwebkit2gtk-4.0-dev
+            sudo apt-get install -y -qq libpng-dev libjpeg-dev libtiff-dev libnotify-dev libsm-dev
+            sudo apt-get install -y -qq libsdl2-dev libsdl2-mixer-2.0-0 libsdl2-image-2.0-0 libsdl2-2.
+        
+        - name: Install package and dependencies
+          run: |
+            python3 -m pip install -e .[tests]
+        
+        - name: Run tests
+          run: |
+            pytest

CONTRIBUTING.md

@@ -0,0 +1,9 @@
+For consistency with PsychoPy, use the following tags before commit/PR messages:
+
+- **BF:** bug fix. For fixing bugs in the *release* branch.
+- **FF:** ‘feature’ fix. For fixing bugs in the *dev* branch.
+- **RF:** refactoring
+- **NF:** new feature
+- **ENH:** enhancement (to existing code, but don't worry too much about the difference between this and NF)
+- **DOC:** for all kinds of documentation related commits
+- **TEST:** for adding or changing tests

docs_src/conf.py

@@ -0,0 +1,40 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'PsychoPy Example Plugin'
+copyright = '2024, Open Science Tools Ltd.'
+author = 'Open Science Tools Ltd.'
+release = '0.0.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode'
+]
+
+html_static_path = ["static"]
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme_path = ["themes"]
+html_theme = 'psychopy_plugin'

docs_src/download.rst

@@ -0,0 +1,8 @@
+
+=======================================================
+How to install psychopy-eyetracker-pupil-labs
+=======================================================
+
+You can download `psychopy-eyetracker-pupil-labs` via pip as follows::
+
+    pip install psychopy-eyetracker-pupil-labs

docs_src/generatePages.py

@@ -0,0 +1,68 @@
+"""
+Use data from the imported library to automatically generate pages. This approach is very much limited, so we recommend using it as a starting point and then writing manually from there. Use with caution if you already have docs written as this may overwrite them!
+"""
+
+
+from importlib import metadata, import_module
+from pathlib import Path
+from psychopy.experiment import Experiment
+
+
+# specify path to docs source folder
+docsFolder = Path(__file__).parent
+# specify path to root folder (containing the pyproject.toml)
+rootFolder = docsFolder.parent
+# create a dummy experiment so we can initialize comps/routines to inspect their params
+exp = Experiment()
+# get path for the module folder (will be the first folder found which contains an __init__.py)
+modFolder = None
+for candidate in rootFolder.glob("*/__init__.py"):
+    if candidate.parent.stem not in ("tests", "docs", "docs_src"):
+        modFolder = candidate.parent
+if modFolder is None:
+    raise ModuleNotFoundError("Could not find module.")
+# find all entry point groups
+for group, points in metadata.entry_points().items():
+    # make sure it's pointing to psychopy
+    if not group.startswith("psychopy"):
+        continue
+    # find all entry points for this group
+    for ep in points:
+        # make sure it's come from a module from this plugin
+        if not ep.value.split(".")[0] == modFolder.stem:
+            continue
+        # load object
+        try:
+            obj = ep.load()
+        except:
+            print("Failed to write docs for " + ep.value)
+            continue
+        # get name and mro
+        mro, name = ep.value.split(":")
+        # write docs
+        if group.startswith("psychopy.experiment.components"):
+            content = obj(exp, "").getFullDocumentation()
+            file = docsFolder / "builder" / "components" / (name + ".rst")
+            file.write_text(content)
+        else:
+            # anything else, write for Coder
+            content = (
+                f"===============================\n"
+                f"{name}\n"
+                f"===============================\n"
+                f"\n"
+                f"To import {name}, you can either use::\n"
+                f"\n"
+                f"    from {mro} import {name}\n"
+                f"\n"
+                f"or, any time after `psychopy.plugins.activatePlugins` has been called::\n"
+                f"\n"
+                f"    from {group} import {name}\n"
+                f"\n"
+                f".. autoclass:: {mro}.{name}\n"
+                f"    :members:\n"
+                f"    :undoc-members:\n"
+                f"    :inherited-members:\n"
+            )
+            file = docsFolder / "coder" / (name + ".rst")
+            file.write_text(content)

docs_src/index.rst

@@ -0,0 +1,33 @@
+=======================================================
+Welcome to psychopy-eyetracker-pupil-labs's documentation!
+=======================================================
+
+The `psychopy-eyetracker-pupil-labs` plugin is designed to show you how to make a plugin.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Added content for the PsychoPy app
+   :glob:
+
+   app/*
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Added content for Builder
+   :glob:
+
+   builder/**/*
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Added content for Coder
+   :glob:
+
+   coder/*
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs_src/themes/psychopy_plugin/globaltoc.html

@@ -0,0 +1,10 @@
+<li class="dropdown globaltoc-container">
+  <a role="button"
+     id="dLabelGlobalToc"
+     data-toggle="dropdown"
+     data-target="#"
+     href="{{ pathto(master_doc) }}">{{ theme_navbar_site_name }} <b class="caret"></b></a>
+  <ul class="dropdown-menu globaltoc"
+      role="menu"
+      aria-labelledby="dLabelGlobalToc">{{ toctree(maxdepth=theme_globaltoc_depth|toint, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}</ul>
+</li>