Merge pull request #4 from computational-psychology/dev_docs

Documentation: API reference, demos, README

.gitignore

@@ -66,6 +66,8 @@ target/
 **/.ipynb_checkpoints/
 **/.ipynb_checkpoints/
 
+docs/reference/_api/
+
 # Modelfest dataset for easy comparison / testing
 **/modelfest/
 

.readthedocs.yaml

@@ -3,17 +3,18 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"
+    python: "3.11"
   jobs:
     pre_build:
       # Generate the Sphinx configuration for this Jupyter Book so it builds.
       - "jupyter-book config sphinx docs/"
 
 python:
   install:
-    - requirements: docs/requirements.txt
     - method: pip
       path: .
+      extra_requirements:
+        - docs
 
 sphinx:
   builder: html

README.md

@@ -1,26 +1,78 @@
 # Stimupy
 
 [![Tests](https://github.com/computational-psychology/stimupy/actions/workflows/test.yml/badge.svg)](https://github.com/computational-psychology/stimupy/actions/workflows/test.yml) [![](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Documentation Status](https://readthedocs.org/projects/stimupy/badge/?version=latest)](https://stimupy.readthedocs.io/en/latest/?badge=latest)
 
 Contains submodules for
 - drawing basic visual stimulus components ([components](stimupy/components/))
 - creating different (brightness) illusions ([illusions](stimupy/illusions/))
 - replicating illusions in certain published papers  ([papers](stimupy/papers/))
 converting pixel values to degrees of visual angle ([utils](stimupy/utils/))
 
-For details, please refer to the source directory (stimupy/),
-the respective subdirectories and the docstrings.
+`Stimupy` is a pure-Python package
+for creating new and exiting visual stimuli
+commonly used in the sudy of contrast, brightness/lightness,
+and other aspects of visual perception.
+
+## Core features:
+Stimupy has been designed to generate stimuli from code,
+so that they are reproducible, flexible, and easy.
+- Stimuli available through stimupy are:
+  - basic visual stimulus [components](stimupy/components/),
+    such as basic shapes, gratings, Gaussians, Gabors
+  - visual [noise](stimupy/noises/) textures, of different kinds,
+  - and many different stimuli commonly referred to as [illusions](stimupy/illusions/)
+    with some special regions of interest,
+    such as Simultaneous Brightness Contrast, White's illusion,
+    but also Hermann Grids, checkerboards, Ponzo illusion, etc.
+
+- All these stimuli are fully parameterizable
+  with interpretable parameters that are relevant to vision scientists
+  (e.g. visual angle, spatial frequency, target placements).
+  - This also makes it possible to explore stimulus parameter spaces
+    which might reveal relations between formerly unconnected stimuli
+
+- Stimuli are also composable/composed:
+`illusions` tend to be composed from several `components`.
+
+- Generated stimuli are output as a Python `dict`ionary,
+containing the stimulus-image as a NumPy-array,
+together with other useful stimulus-specific information
+(e.g. (target) masks, sizes etc.).
+    - Since Python dictionaries are mutable data structures (compared to objects),
+      they allow the user to add additional information easily.
+    - The image as NumPy-array (rather than, e.g., an OpenGL texture),
+      makes these stimuli fully interoperablye using common NumPy tooling.
+
+- In addition, we provide many [utils](stimupy/utils/) functions
+  to apply common operations to either the images, or the full stimulus-`dict`s.
+
+- Reuse of existing stimuli and stimulus sets should be a key aim,
+  so also included are exact replications of stimuli previously published (e.g. ModelFest)
+  as described in their respecive [papers](stimupy/papers/)
+
+See the [documentation](https://stimupy.readthedocs.io/en/latest/) for more details
+
+## Your stimulus (set) is not here?
+Given the modular nature of the package,
+any stimulus or stimulus set not currently available, can be easily added.
+Open an [issue](https://github.com/computational-psychology/stimupy/issues/new)
+and let us know what you'd like to see added.
+
+If you want to contribute yourself, see [contributing](#contributing-to-stimupy)
+
 
 
 ## Installation
 
-Either install using `pip`:
+For now, `pip` can install directly from GitHub (the `main` branch)
+GitHub repository
 ```python
-pip install 'stimupy @ https://github.com/computational-psychology/stimupy'
+pip install https://github.com/computational-psychology/stimupy/zipball/main
 ```
 
 OR (for developers), install from source:
-1. Clone the repository from GitHub (TUB):
+1. Clone the repository from GitHub:
 
     ```bash
     git clone git@github.com:computational-psychology/stimupy.git
@@ -42,19 +94,20 @@ rather than having to reinstall the package after every change.
 ### Dependencies
 Dependencies should be automatically installed (at least using `pip`).
 `stimupy`s required dependencies are:
-- numpy
-- scipy
-- matplotlib
-- Pillow
-- pandas
+- [NumPy](https://numpy.org/)
+- [SciPy](https://scipy.org/)
+- [matplotlib](https://matplotlib.org/)
+- [Pillow](https://pillow.readthedocs.io/)
+- [pandas](https://pandas.pydata.org/)
 
+## Citing stimupy
 
-## Importing
-To use in your own code, `import` (from) the modules.
-```python
-from stimupy import components
-from stimupy import noises
-from stimupy import illusions
-from stimupy import papers
-from stimupy import utils
-```
+## Contributing to stimupy
+1. *Fork* the [GitHub repository](https://github.com/computational-psychology/stimupy/)
+2. *Clone* the repository to your local machine
+3. *Install* `stimupy` using the developer install: `pip install -e ".[dev]"`
+4. *Edit* the code:
+    - To contribute a stimulus set, add it to `stimupy/papers/`
+    - To contribute a stimulus function, add it to the relevant directory
+5. *Commit & Push* to your fork
+6. *Pull request* from your fork to our repository

binder/labconfig/default_setting_overrides.json

@@ -0,0 +1,8 @@
+{
+    "@jupyterlab/docmanager-extension:plugin": {
+        "defaultViewers": {
+            "markdown": "Jupytext Notebook",
+            "myst": "Jupytext Notebook"
+        }
+    }
+}

binder/postBuild

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -e  # don't allow errors to fail silently
+echo `which pip`  # in case the wrong `pip` is used, this will let us debug
+
+# See https://github.com/mwouts/jupytext/issues/803#issuecomment-982170660
+mkdir -p ${HOME}/.jupyter/labconfig
+cp binder/labconfig/* ${HOME}/.jupyter/labconfig
+
+# Install stimupy
+pip install -e .

binder/requirements.txt

@@ -0,0 +1,3 @@
+jupytext>=1.13.3
+jupyterlab_myst
+myst_nb

docs/_config.yml

@@ -23,10 +23,50 @@ bibtex_bibfiles:
 repository:
   url: https://github.com/computational-psychology/stimupy  # Online location of your book
   path_to_book: docs  # Optional path to your book, relative to the repository root
-  branch: main  # Which branch of the repository should be used when creating links (optional)
+  branch: dev_docs  # Which branch of the repository should be used when creating links (optional)
 
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
 html:
   use_issues_button: true
   use_repository_button: true
+
+launch_buttons:
+  notebook_interface: "jupyterlab" # The interface interactive links will activate ["classic", "jupyterlab"]
+  binderhub_url: "https://mybinder.org"
+
+sphinx:
+  extra_extensions:
+    - sphinx.ext.intersphinx
+    - sphinx.ext.autosummary        # generate summary tables of functions in modules
+    - sphinx.ext.napoleon           # recognize NumPy style docstrings
+    - sphinx.ext.viewcode           # add links to source code in API reference
+
+  config:
+    #autosummary_generate: True      # autosummary generates module-level .rst files?
+    add_module_names: False         # Don't include module names in autosummary tables
+    autosummary_imported_members: True
+    autosummary_ignore_module_all: False
+    autodoc_default_options: {
+     "members": True,                # Include module/class members.
+     "member-order": 'bysource',     # Order members as in source file.
+    }
+    templates_path: ['_templates']  # Path(s) that contain templates, relative to this config
+    exclude_patterns: ['_build', '_templates']
+    intersphinx_mapping:
+        numpy [stable]:
+          - 'https://numpy.org/doc/stable/'
+          - null
+        matplotlib [stable]:
+          - 'https://matplotlib.org/stable/'
+          - null
+        pandas [latest?]:
+          - 'https://pandas.pydata.org/docs/'
+          - null
+        scipy [latest]:
+          - 'https://docs.scipy.org/doc/scipy/'
+          - null
+        pillow [latest]:
+          - 'https://pillow.readthedocs.io/en/latest/'
+          - null
+    suppress_warnings: ["etoc.toctree"]

docs/_templates/autosummary/components.rst

@@ -0,0 +1,75 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   Module attributes
+   -----------------
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block modules %}
+   {% if modules %}
+   Modules
+   -------
+
+   .. autosummary::
+      :toctree: {{ name }}
+      :recursive:
+   {% for item in modules %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+
+   {% block classes %}
+   {% if classes %}
+   Classes
+   -------
+
+   .. autosummary::
+      :toctree: {{ name }}
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   Exceptions
+   ----------
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   :doc:`Demos <../../demos/components/{{name}}>`
+   ------------------------------------------------------------------------------
+
+
+   Functions
+   ---------
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}

docs/_templates/autosummary/illusions.rst

@@ -0,0 +1,74 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   Module attributes
+   -----------------
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block modules %}
+   {% if modules %}
+   Modules
+   -------
+
+   .. autosummary::
+      :toctree: {{ name }}
+      :recursive:
+   {% for item in modules %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+
+   {% block classes %}
+   {% if classes %}
+   Classes
+   -------
+
+   .. autosummary::
+      :toctree: {{ name }}
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   Exceptions
+   ----------
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   :doc:`Demos <../../demos/illusions/{{name}}>`
+   ------------------------------------------------------------------------------
+
+   Functions
+   ---------
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}