Docs build, CI consolidation, README update

.github/dependabot.yml

@@ -21,11 +21,10 @@ updates:
           - "minor"
           - "patch"
     ignore:
-      # torch and torchvision are pinned to exact versions served from the
-      # custom CUDA wheel index declared in pyproject.toml, and the two must
-      # move together. Routine version bumps here would break that pairing or
-      # silently pull the plain PyPI build instead, so they are upgraded by
-      # hand. These conditions cover version updates only; Dependabot security
+      # torch and torchvision are locked (poetry.lock) to builds from the CUDA
+      # wheel index declared in pyproject.toml, and docs/requirements.txt pins
+      # the matching CPU builds. The two must move together, and a routine bump
+      # could pull the plain PyPI build instead, so they are upgraded by hand. These conditions cover version updates only; Dependabot security
       # alerts for torch and torchvision still come through.
       - dependency-name: "torch"
         update-types:
@@ -53,3 +52,12 @@ updates:
       github-actions:
         patterns:
           - "*"
+
+  # Base image of the Dockerfile.
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"

.github/workflows/black.yml

@@ -1,14 +1,34 @@
+# Formatting and import-order check. Branch protection on master requires the job named "lint"; keep that name.
 name: Black Formater
 
-on: [push, pull_request]
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
 
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-python@v7
-      - uses: psf/black@stable
+        with:
+          python-version: "3.13"
+      # Use the black and isort versions pinned in poetry.lock, so CI and local
+      # formatting agree.
+      - name: Check formatting with black
+        run: |
+          version=$(python -c "import tomllib; print(next(p['version'] for p in tomllib.load(open('poetry.lock','rb'))['package'] if p['name']=='black'))")
+          pipx run "black==${version}" --check --diff .
+      - name: Check import order with isort
+        run: |
+          version=$(python -c "import tomllib; print(next(p['version'] for p in tomllib.load(open('poetry.lock','rb'))['package'] if p['name']=='isort'))")
+          pipx run "isort==${version}" --check-only --diff .

.github/workflows/python-app.yml

@@ -1,47 +1,62 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-
+# Tests. Branch protection on master requires the job named "build"; keep that name.
 name: BindsNET build status
 
 on:
   push:
     branches: [ master ]
   pull_request:
     branches: [ master ]
+  workflow_dispatch:
 
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  POETRY_VERSION: "2.4.3"
+
 jobs:
   build:
-
+    name: build
     runs-on: ubuntu-latest
-
     steps:
     - uses: actions/checkout@v7
-    - name: Set up Python 3.13
-      uses: actions/setup-python@v7
-      with:
-        python-version: 3.13
     - name: Install Poetry
-      env:
-        POETRY_VERSION: 2.4.3
-      run: |
-        curl -sSL https://install.python-poetry.org | python - -y &&\
-            poetry config virtualenvs.create false
+      run: pipx install "poetry==${POETRY_VERSION}"
+    - uses: actions/setup-python@v7
+      with:
+        python-version: "3.13"
+        cache: poetry
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install flake8 pytest
-        # if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
         poetry install
-        .github/scripts/use_cpu_torch.sh python
-    - name: Lint with flake8
-      run: |
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        # flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+        .github/scripts/use_cpu_torch.sh "poetry run python"
+    - name: Lint with flake8 (syntax errors and undefined names)
+      run: pipx run flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
     - name: Test with pytest
+      run: poetry run pytest
+
+  # The other supported Python versions (pyproject.toml: >=3.11,<3.14).
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+    - uses: actions/checkout@v7
+    - name: Install Poetry
+      run: pipx install "poetry==${POETRY_VERSION}"
+    - uses: actions/setup-python@v7
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: poetry
+    - name: Install dependencies
       run: |
-        pytest
+        poetry install
+        .github/scripts/use_cpu_torch.sh "poetry run python"
+    - name: Test with pytest
+      run: poetry run pytest

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# Installed by `poetry run pre-commit install` (see CONTRIBUTING.md).
+# Uses the isort and black installed by Poetry, so the version always matches poetry.lock and CI.
+repos:
+  - repo: local
+    hooks:
+      - id: isort
+        name: isort
+        entry: poetry run isort
+        language: system
+        types: [python]
+      - id: black
+        name: black
+        entry: poetry run black
+        language: system
+        types: [python]

.readthedocs.yaml

@@ -1,39 +1,25 @@
-# .readthedocs.yaml
 # Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
-# Required
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.11"
+    python: "3.13"
 
-# Build documentation in the docs/ directory with Sphinx
 sphinx:
   builder: html
   configuration: docs/source/conf.py
-  
+
 formats:
   - epub
   - pdf
 
-# We recommend specifying your dependencies to enable reproducible builds:
-# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# autodoc imports bindsnet, so the package and its dependencies must be installed.
+# docs/requirements.txt installs the CPU build of torch first (much smaller than the
+# CUDA build); installing the package then keeps that torch.
 python:
   install:
     - requirements: docs/requirements.txt
     - method: pip
-      path: docs/
-      # extra_requirements:
-        # - docs
-
-# python:
-  # version: 3.8
-  # install:
-    # - method: pip
-      # path: .
-    # - requirements: docs/requirements.txt
-  # system_packages: False
+      path: .

CHANGELOG.md

@@ -6,6 +6,42 @@ see the [GitHub releases / tags](https://github.com/BindsNET/bindsnet/releases).
 
 ## [Unreleased]
 
+### Fixed
+- API reference on Read the Docs was empty: the build never installed `bindsnet`, so
+  every `automodule` failed to import (`No module named 'matplotlib'`), and
+  `docs/pyproject.toml` downgraded Sphinx to 7.2.6. `.readthedocs.yaml` now installs a
+  CPU build of torch and the package (Python 3.13, Ubuntu 24.04);
+  `docs/pyproject.toml` removed.
+- The docs build has no warnings (was 48 on Read the Docs, 53 with the package
+  installed): docstring markup fixed in `topology.py`, `topology_features.py`,
+  `monitors.py`, `learning.py`, `nodes.py`, `encoders.py`, `plotting.py`,
+  `conversion.py`, `davis.py`, `preprocess.py`, `cue_reward.py`, `dot_simulator.py`;
+  broken links in `index.rst` and the guide; `conf.py` takes the version from the
+  installed package. Docstring text only; no code changed.
+- API reference now includes `learning.MCC_learning`, `network.topology_features`,
+  `environment.cue_reward`, `environment.dot_simulator` and
+  `analysis.dotTrace_plotter`, which were missing.
+
+### Changed
+- CI: one test workflow (`python-app.yml`: job `build` on Python 3.13 plus a 3.11/3.12
+  matrix, Poetry 2.4.3 with dependency caching, superseded runs cancelled);
+  `pythonpackage.yml` removed (it ran on every push to every branch and its
+  `black .` step reformatted instead of checking). `black.yml` checks with the black
+  version from `poetry.lock` instead of the floating `psf/black@stable`.
+- Dependabot also updates the Dockerfile base image.
+- Imports sorted with isort (settings already in `pyproject.toml`, never applied; 20
+  files, import order only). `black.yml` and the pre-commit hook now also check isort.
+- Removed from git: 59 TensorBoard event files under `logs/` (test output; `logs/*`
+  was already in `.gitignore`), `.vscode/launch.json` (a local interpreter path) and
+  `docs/Makefile.old`, `docs/make.bat.old`.
+- Added `.pre-commit-config.yaml` (black from Poetry); `CONTRIBUTING.md` already told
+  contributors to install pre-commit, but there was no configuration.
+- `[tool.black] target-version` is `py311`-`py313` (was `py38`); no file changes.
+- README: dead link to Markram et al. (1997) replaced with its DOI; RL example named
+  correctly (Breakout, not Space Invaders); OpenAI gym text replaced (Gymnasium and
+  ale-py install with BindsNET); benchmark marked as from the 2018 paper; PyPI badge
+  refreshes hourly.
+
 ## [0.3.4 (PyPI)] - 2026-09-16
 
 First PyPI upload since 0.2.7. It is built from the `master` branch on this date, not