Merge pull request #50 from open-ephys/update-gha

Update to modern GitHub Pages deployment

Author: bparks13

.github/workflows/sphinx-build.yml

@@ -1,13 +1,13 @@
-name: Update Documentation
+name: Build Documentation
 
 on:
   push:
-    branches:    
-      - main
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     steps:
@@ -19,36 +19,52 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.10"
+          python-version: "3.12"
 
       - name: Install pipenv
         run: |
           python -m pip install --upgrade pipenv==2024.4.1 wheel
 
+      - id: cache-pipenv
+        uses: actions/cache@v4
+        with:
+          path: ~/.local/share/virtualenvs
+          key: ${{ runner.os }}-pipenv-${{ hashFiles('**/Pipfile.lock') }}
+
       - name: Install dependencies
+        if: steps.cache-pipenv.outputs.cache-hit != 'true'
         run: |
           pipenv install --deploy --dev
 
-      - name: Make
+      - name: Manually install setuptools # NB: This step is required to correctly link the pkg_resources module
         run: |
-          pipenv run make html
+          pipenv run python -m pip install -U setuptools
 
-      # 2. Add and commit HTML files to gh-pages branch
-      - name: Commit documentation changes
+      - name: Build HTML pages
         run: |
-          git clone https://github.com/${{ github.repository_owner }}/gui-docs.git --branch gh-pages --single-branch gh-pages
-          cd gh-pages
-          rm -rf *
-          cp -r ../docs/html/* .
-          git config --local user.email "[email protected]"
-          git config --local user.name "GitHub Action"
-          git add .
-          git commit -m "Update documentation" -a || true
-
-      # 3. Push changes to gh-pages branch (updates documentation page)
-      - name: Push changes
-        uses: ad-m/github-push-action@master
+          pipenv run make html SPHINXOPTS="-W --keep-going"
+  
+      - name: Check all external links
+        id: make_linkcheck
+        run: |
+          pipenv run make linkcheck SPHINXOPTS="-W --keep-going"
+  
+      - name: Upload GitHub Pages Artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          branch: gh-pages
-          directory: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          path: docs/html/
+
+  deploy:
+    name: Deploy docs
+    runs-on: ubuntu-22.04
+    needs: build
+    if: github.event_name == 'push' && always() && !failure() && !cancelled()
+    
+    permissions:
+      # Both required by actions/deploy-pages
+      pages: write
+      id-token: write
+      
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.travis.yml

@@ -43,7 +43,7 @@ The first step in creating a new common library is to create a repository from t
 
 5. Click the green "Create repository from template" button.
 
-On your local machine, create an "OEPlugins" directory within the same directory that contains your :code:`plugin-GUI` repository: Then, using the command line or the `GitHub Desktop <https://desktop.github.com/>`__ app, clone your the common library repository into this new folder. Your directory structure should look something like this:
+On your local machine, create an "OEPlugins" directory within the same directory that contains your :code:`plugin-GUI` repository: Then, using the command line or the `GitHub Desktop <https://github.com/apps/desktop>`__ app, clone your the common library repository into this new folder. Your directory structure should look something like this:
 
 .. code-block:: 
 

Pipfile.lock

@@ -15,7 +15,7 @@ Most Open Ephys GUI plugins work equally well on Windows, Linux, and Mac. Howeve
 Obtaining the source code
 --------------------------
 
-The first step for compiling a pre-existing plugin is downloading the source code. If you're planning to make your own changes to the plugin, we recommend first forking the plugin's GitHub repository to your own account, then cloning the fork via the `command line <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository-using-the-command-linee>`__ or the `GitHub Desktop app <https://desktop.github.com/>`__. If you're not planning to make any changes to the plugin, you can clone the original repository or download the code as a **.zip** file.
+The first step for compiling a pre-existing plugin is downloading the source code. If you're planning to make your own changes to the plugin, we recommend first forking the plugin's GitHub repository to your own account, then cloning the fork via the `command line <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository?tool=cli>`__ or the `GitHub Desktop app <https://github.com/apps/desktop/>`__. If you're not planning to make any changes to the plugin, you can clone the original repository or download the code as a **.zip** file.
 
 All of the officially supported plugins assume that the plugin source code is contained within a separate directory *at the same level* as that of the host application (the :code:`plugin-GUI` GitHub repository). Before attempting to compile your plugin, make sure your directory structure looks something like this:
 

source/Developer-Guide/Common-and-external-libraries.rst

@@ -5,7 +5,7 @@
 Compiling the GUI
 =====================
 
-If you'd like to build the GUI from source, you'll have to download the code to your local machine. We recommend first forking the `GUI's GitHub repository <https://github.com/open-ephys/plugin-GUI>`__ to your own account, then cloning the fork via the `command line <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository-using-the-command-line>`__ or the `GitHub Desktop app <https://desktop.github.com/>`__. 
+If you'd like to build the GUI from source, you'll have to download the code to your local machine. We recommend first forking the `GUI's GitHub repository <https://github.com/open-ephys/plugin-GUI>`__ to your own account, then cloning the fork via the `command line <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository?tool=cli>`__ or the `GitHub Desktop app <https://github.com/apps/desktop/>`__. 
 
 
 Windows

source/Developer-Guide/Compiling-plugins.rst

@@ -35,7 +35,7 @@ The first step in creating a new plugin is to create a repository from the appro
 
 5. Click the green "Create repository from template" button.
 
-On your local machine, create an "OEPlugins" directory within the same directory that contains your :code:`plugin-GUI` repository: Then, using the command line or the `GitHub Desktop <https://desktop.github.com/>`__ app, clone your the plugin repository into this new folder. Your directory structure should look something like this:
+On your local machine, create an "OEPlugins" directory within the same directory that contains your :code:`plugin-GUI` repository: Then, using the command line or the `GitHub Desktop <https://github.com/apps/desktop/>`__ app, clone your the plugin repository into this new folder. Your directory structure should look something like this:
 
 .. code-block:: 
 
@@ -58,7 +58,7 @@ Inside the "Source" folder of the plugin repository you just cloned, you'll find
 **Processor** and **Visualizer** Plugins
 -------------------------------------------
 
-Most plugins will be "processors," meaning they implement the :code:`process()` method of `GenericProcessor.h <https://github.com/open-ephys/plugin-GUI/blob/master/Source/Processors/GenericProcessor/GenericProcessor.h>`__. This method is called repeatedly during the GUI's acquisition loop, so each plugin has a chance to respond to incoming data (or generate its own). If they include a canvas for displaying data, Processor plugins can also be Visualizer plugins.
+Most plugins will be "processors," meaning they implement the :code:`process()` method of `GenericProcessor.h <https://github.com/open-ephys/plugin-GUI/blob/main/Source/Processors/GenericProcessor/GenericProcessor.h>`__. This method is called repeatedly during the GUI's acquisition loop, so each plugin has a chance to respond to incoming data (or generate its own). If they include a canvas for displaying data, Processor plugins can also be Visualizer plugins.
 
 Processor and Visualizer plugins should edit the following lines in :code:`OpenEphysLib.cpp`:
 

source/Developer-Guide/Compiling-the-GUI.rst

@@ -14,7 +14,7 @@ If you're planning to update the host application, or any of the plugins in the
 
 1. Fork the `GUI's GitHub repository <https://github.com/open-ephys/plugin-GUI>`__ to your own account.
 
-2. Clone the fork via the `command line <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository-using-the-command-line>`__ or the `GitHub Desktop app <https://desktop.github.com/>`__. 
+2. Clone the fork via the `command line <https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository?tool=cli>`__ or the `GitHub Desktop app <https://github.com/apps/desktop/>`__. 
 
 3. Compile the GUI for your platform of choice according to the steps on :ref:`this page<compilingthegui>`.
 

source/Developer-Guide/Creating-a-new-plugin.rst

@@ -24,7 +24,7 @@ Before you :ref:`create a new plugin<creatinganewplugin>`, you'll need to have s
 Updating the host application
 ------------------------------
 
-If you'd like to make changes to the Open Ephys GUI main repository, first read through :ref:`this section<modifyingthehostapplication>` of the developer documentation. Then, take a look at our list of `active projects <https://github.com/open-ephys/plugin-GUI/projects>`__ to find out about the features we're planning to update in the near future. If you're interested in tackling one of these projects, or have other ideas for useful additions to the main application, don't hesistate to `open an issue on GitHub <https://github.com/open-ephys/plugin-GUI/issues>`__.
+If you'd like to make changes to the Open Ephys GUI main repository, first read through :ref:`this section<modifyingthehostapplication>` of the developer documentation. Then, take a look at our list of `active projects <https://github.com/open-ephys/plugin-GUI/projects?query=is%3Aopen>`__ to find out about the features we're planning to update in the near future. If you're interested in tackling one of these projects, or have other ideas for useful additions to the main application, don't hesitate to `open an issue on GitHub <https://github.com/open-ephys/plugin-GUI/issues>`__.
 
 Other projects
 ---------------

source/Developer-Guide/Modifying-the-host-application.rst

@@ -62,6 +62,6 @@ If you want to contribute in a more substantial way, you could add funding for a
 
 **Can I license the Open Ephys GUI for a commercial project?**
 
-The GUI is released under a `GPL 3.0 license <https://github.com/open-ephys/plugin-GUI/blob/master/LICENSE>`__, which means that any derivative software must also be open source. However, if you'd like to use the GUI to acquire data from a closed-source device, this is both easy and encouraged! We would love for more companies to use the GUI, rather than choosing to build their own acquisition software from scratch. 
+The GUI is released under a `GPL 3.0 license <https://github.com/open-ephys/plugin-GUI/blob/main/LICENSE>`__, which means that any derivative software must also be open source. However, if you'd like to use the GUI to acquire data from a closed-source device, this is both easy and encouraged! We would love for more companies to use the GUI, rather than choosing to build their own acquisition software from scratch. 
 
 |

source/Developer-Guide/index.rst

@@ -36,7 +36,7 @@ The first step in creating a plugin is to create a new code repository from a te
 .. image:: ../_static/images/tutorials/makeyourownplugin/makeyourownplugin-02.png
   :alt: Create TTLEventGenerator Repository
 
-On your local machine, create an "OEPlugins" directory within the same directory that contains your :code:`plugin-GUI` repository. Then, using the `git <https://git-scm.com/>`__ command line interface or the `GitHub Desktop <https://desktop.github.com/>`__ app, clone the newly created plugin repository into this directory. Your directory structure should look something like this:
+On your local machine, create an "OEPlugins" directory within the same directory that contains your :code:`plugin-GUI` repository. Then, using the `git <https://git-scm.com/>`__ command line interface or the `GitHub Desktop <https://github.com/apps/desktop/>`__ app, clone the newly created plugin repository into this directory. Your directory structure should look something like this:
 
 .. code-block:: 
 

source/FAQ/index.rst

@@ -38,7 +38,7 @@ The first step in creating a plugin is to create a new code repository from a te
 .. image:: ../_static/images/tutorials/makeyourownvisualizerplugin/visualizerplugin-02.png
   :alt: Create rate-viewer Repository
 
-On your local machine, create an "OEPlugins" directory within the same directory that contains your :code:`plugin-GUI` repository. Then, using the `git <https://git-scm.com/>`__ command-line interface or the `GitHub Desktop <https://desktop.github.com/>`__ app, clone the newly created plugin repository into this directory. 
+On your local machine, create an "OEPlugins" directory within the same directory that contains your :code:`plugin-GUI` repository. Then, using the `git <https://git-scm.com/>`__ command-line interface or the `GitHub Desktop <https://github.com/apps/desktop/>`__ app, clone the newly created plugin repository into this directory. 
 
 Your directory structure should look something like this:
 

source/Tutorials/How-To-Make-Your-Own-Plugin.rst

@@ -40,7 +40,7 @@ Processors handle four types of data:
 
 * **Text events:** messages generated by the user or other processors, or sent via the network. Some processors have specific behaviors that are triggered by text events.
 
-In addition, it's important to keep in mind that every continuous signal, event, and spike must be associated with a single *data stream*, or a collection of channels that are sampled synchronously. Any time you merge together data from different Sources, channels from each source will belong to different data streams. In addition, some Source processors (such as :ref:`neuropixelspxi`) generate multiple data streams. In most cases, data from separate streams will be processed independently, because samples from different streams are not guaranteed to be aligned. See the :ref:`whatsnew` page for more information about modifying parameters for individual streams.
+In addition, it's important to keep in mind that every continuous signal, event, and spike must be associated with a single *data stream*, or a collection of channels that are sampled synchronously. Any time you merge together data from different Sources, channels from each source will belong to different data streams. In addition, some Source processors (such as :ref:`neuropixelspxi`) generate multiple data streams. In most cases, data from separate streams will be processed independently, because samples from different streams are not guaranteed to be aligned. See the :ref:`whatsnewinv06x` page for more information about modifying parameters for individual streams.
 
 
 3. Message Center
@@ -129,7 +129,7 @@ View
 Help
 -----
 
-* **Online documentation...**: Open the GUI's documentation site in a browser window (requires access to the interent).
+* **Online documentation...**: Open the GUI's documentation site in a browser window (requires access to the internet).
 
 
 Debug console
@@ -155,14 +155,13 @@ Windows
 Debug console is automatically displayed on Windows when you run the :code:`open-ephys` application.
 
 
-
 Log files
 ###############
 
-Every action taken by the user is logged to a file, along with additional information that can be useful for spotting issues when things go wrong. If the GUI exits sucessfully, the latest log file will be overwritten the next time the GUI is launched. If the GUI crashes, then the name of the latest log file will be appended with a unique date string.
+Every action taken by the user is logged to a file, along with additional information that can be useful for spotting issues when things go wrong. If the GUI exits successfully, the latest log file will be overwritten the next time the GUI is launched. If the GUI crashes, then the name of the latest log file will be appended with a unique date string.
 
 Linux
--------
+------
 
 Log files are written to :code:`/home/<username>/open-ephys/configs-api8`
 

source/Tutorials/Making-Your-Own-Visualizer-Plugin.rst

@@ -19,6 +19,8 @@ More than 1000 `Open Ephys acquisition boards <https://open-ephys.org/acq-board>
 
 The following hardware is recommended for experiments that use the acquisition board:
 
+.. _computer-specs-open-ephys:
+
 Computer specs
 #####################
 
@@ -39,11 +41,11 @@ Other hardware
 
 These are the minimum requirements for getting up and running. You will likely need additional hardware for the full experiment (e.g. reward ports, mazes, commutators, light for optogenetic stimulation).
 
-* **Acquisition board** (available from the `Open Ephys Store <https://open-ephys.org/acquisition-system/acquisition-board>`__)
+* **Acquisition board** (available from the `Open Ephys Store <https://open-ephys.org/acquisition-system/oeps-9029>`__)
 
 * **I/O boards** for interfacing with auxiliary analog and digital signals (available from the `Open Ephys Store <https://open-ephys.org/acquisition-system/io-board-pcb>`__)
 
-* **Headstages and cables** (available as part of the `Open Ephys Starter Kit <https://open-ephys.org/acquisition-system/starter-kit>`__ or from `Intan Technologies <https://intantech.com/pricing.html>`__; there is also a low-profile headstage available from the `Open Ephys Store <https://open-ephys.org/acquisition-system/low-profile-spi-headstage-64ch>`__)
+* **Headstages and cables** (available as part of the `Open Ephys Starter Kit <https://open-ephys.org/acquisition-system/starter-kit>`__ or from `Intan Technologies <https://intantech.com/pricing.html>`__; there is also a low-profile headstage available from the `Open Ephys Store <https://open-ephys.org/acquisition-system/oeps-6570-6571>`__)
 
 * **Electrodes** - there is lots of flexibility here, as long as you have some way to interface between your electrodes and a compatible headstage. For tetrodes, we recommend the `shuttleDrive <https://open-ephys.org/drive-implant>`__.
 
@@ -58,6 +60,8 @@ Neuropixels are quickly become a new standard for electrophysiology, given their
 
 The following hardware is recommended for experiments with Neuropixels:
 
+.. _computer-specs-neuropixels:
+
 Computer specs
 ################
 
@@ -77,7 +81,9 @@ Computer specs
 Other hardware
 ###############
 
-The following summarizes the additional hardware you'll need to buy to run Neuropixels experiments. OneBoxes, PXI basestations, headstages, and probes can be ordered from `neuropixels.org <https://neuropixels.org>`__. Other PXI components are available from NI.
+The following summarizes the additional hardware you'll need to buy to run Neuropixels experiments. OneBoxes, PXI basestations, headstages, and probes can be ordered from `neuropixels.org <https://www.neuropixels.org>`__. Other PXI components are available from NI.
+
+.. _onebox-hardware-requirements:
 
 OneBox
 -------