Merge pull request #3 from TEParsons/main

BF: Add entry points, docs and tests

.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

README.md

@@ -1,13 +1,11 @@
-# psychopy-mri-emulator
-
 Software emulator for fMRI hardware.
 
 Idea: Run or debug an experiment script using exactly the same code, i.e., for both testing and online data acquisition. 
 To debug timing, you can emulate sync pulses and user responses. Limitations: pyglet only; keyboard events only.
 
 ## Installing
 
-Install this package with the following shell command:: 
+Install this package with the following shell command: 
 
     pip install psychopy-mri-emulator
 

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-plugin-template
+=======================================================
+
+You can download `psychopy-plugin-template` via pip as follows::
+
+    pip install git+https://github/psychopy/psychopy-plugin-template@main

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-plugin-template's documentation!
+=======================================================
+
+The `psychopy-template` 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>