Merge pull request #15 from open-ephys/standardize-docs

Standardize documentation sites

Pipfile

@@ -5,4 +5,6 @@ verify_ssl = true
 
 [packages]
 sphinx = "*"
-pydata-sphinx-theme = "0.3.1"
+pydata-sphinx-theme = "0.13.3"
+sphinx-tabs = "*"
+make = "*"

README.rst

@@ -1,19 +1,18 @@
 =========
-Template for Open Ephys Documentation
+Documentation for the Open Ephys Acquisition Board
 =========
 
 This documentation's source template was taken from the `Spinal HDL <https://github.com/SpinalHDL/SpinalDoc-RTD>`_ project.
 
 The theme is based on the `PyData Sphinx Theme <https://pydata-sphinx-theme.readthedocs.io/en/latest/>`_
 
+For more detailed usage instructions, see the `Open Ephys Doc Template <https://github.com/open-ephys/doc-template>`_
+
 How to build this documentation
 ===============================
 
 With pipenv (recommended)
 -----------
-Requirements (system)
-
-* make
 
 Requirements (Python 3):
 
@@ -58,8 +57,7 @@ Requirements (system):
 Requirements (Python 3):
 
 * sphinx
-* sphinx-rtd-theme
-* sphinxcontrib-wavedrom
+* pydata-sphinx-theme=="0.13.3"
 
 After installing the requirements you can run
 
@@ -70,13 +68,3 @@ After installing the requirements you can run
    make latexpdf # for latex (will require latexpdf installed)
    make          # list all the available output format
 
-Continuous Integration(CI)
-==========================
-
-This repo uses Travis for its CI needs.
-If you want have a gh-pages preview on your fork, you need to activate your repo on Travis admin page.
-After that you only need add ``GITHUB_TOKEN`` as Environment Variable with your Github personal token (you only need grant repo/public_repo access)
-More details here:
-
-* `Defining variables <https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings>`_
-* `Deploy to gh-pages <https://docs.travis-ci.com/user/deployment/pages/>`_

source/Build-Instructions/index.rst

@@ -3,7 +3,7 @@
    :format: html
 
 ***********************************
-Build Instructions
+Assembly Guide
 ***********************************
 
 This section will guide you through the steps necessary to build as many Open Ephys acquisition boards as you need. The amount of time and money invested will vary depending on your approach, but it's unlikely that you'll end up devoting more than 2-3 days of work and $1000 per board. Please correct us if these numbers differ from the amount of time/money you actually spend!

source/User-Manual/Custom-cables.rst

@@ -64,6 +64,7 @@ When running two RHD chips on one cable, the voltage drop over the cable resista
 It's not required to twist the LVDS pairs for the short distances in the adapter in our experience.
 
 .. _customBNC:
+
 Making an HDMI- BNC Cable
 ----------------------------------------
 

source/User-Manual/Gateware-Update.rst

@@ -44,7 +44,7 @@ If the version does not appear or appears as ``N/A`` when creating the node, it
 updated after acquisition starts.
 
 Instructions to update the gateware in case you don't have the latest version
--------------------------------------------------------------------
+--------------------------------------------------------------------------------
 
 .. warning:: Do not attempt to update the board gateware while the GUI or any other software using
     the board is in use. Do not open any software that uses the board while an update is in process.

source/User-Manual/New-FPGA.rst

@@ -2,6 +2,7 @@
 
 New Open Ephys FPGA module
 =====================================================
+
 *Last updated: 18th Jul 2023*
 
 Devices shipped from Dec 2022 onwards use a brand-new FPGA module designed by Open Ephys.
@@ -140,11 +141,10 @@ We have completed:
 Differences with previous boards
 -----------------------------------
 
-* **This board has a single power supply input located on the FPGA module itself. Always use the 5V power supply provided.**
+**This board has a single power supply input located on the FPGA module itself. Always use the 5V power supply provided.**
 Since this new FPGA module was developed by us, it has the voltage protection circuitry we require for use with the acquisition board.
 
-* **The power light inside the board is now red.**
-
+**The power light inside the board is now red.**
 The LED that indicates that the FPGA module is powered used to be green on the FPGA module we used previously, but on our new one it is red.
 
 .. image:: /_static/images/usermanual/newfpga/FPGA-module-power-led.png
@@ -203,9 +203,9 @@ Contribute
 ------------
 We count on user feedback to improve our devices, as we test them before they get to you but might not have covered all the use cases and your particular hardware. Always test new devices by performing checks on a short recording before using them for research.
 
-If you find any problems, please let us know and we will address them as fast as we can. We would appreciate it if you can post a GitHub Issue to the plugin repository `here <https://github.com/open-ephys-plugins/rhythm-oni-plugin/issues>`_.
+If you find any problems, please let us know and we will address them as fast as we can. We would appreciate it if you can post a GitHub Issue to the `plugin repository <https://github.com/open-ephys-plugins/rhythm-oni-plugin/issues>`_.
 
-While acquisition board usage is the same, we will be slowly updating the documentation to reflect these changes. You are welcome to contribute to our documentation `here <https://github.com/open-ephys/acq-board-docs>`_.
+While acquisition board usage is the same, we will be slowly updating the documentation to reflect these changes. You are welcome to contribute to our documentation `hosted on GitHub <https://github.com/open-ephys/acq-board-docs>`_.
 
 .. _newfpga_why:
 

source/User-Manual/Quickstart-guide.rst

@@ -6,63 +6,67 @@
 Quickstart guide
 ***********************************
 
-#. **Connecting the USB cable and power supply**
+Connecting the USB cable and power supply
+-------------------------------------------
 
-    *Required components: USB cable, 5V power supply*
+*Required components: USB cable, 5V power supply*
 
-    Connect the USB cable to a USB port on your computer. If possible, using a USB 3.0-compatible port is recommended (often indicated by a blue color). USB cables longer than 2 meters are not recommended.
+Connect the USB cable to a USB port on your computer. If possible, using a USB 3.0-compatible port is recommended (often indicated by a blue color). USB cables longer than 2 meters are not recommended.
 
-    .. warning:: Make sure you're using a 5V DC power supply! The latest version of the Acquisition Board includes over-voltage protection, but it's always safest to use the power jack on the Acquisition Board. Do not use the power supply on the FPGA, next to the USB port. The acquisition board power jack has extra protections to avoid damage to the system that the FPGA plug lacks.
+.. warning:: Make sure you're using a 5V DC power supply! The latest version of the Acquisition Board includes over-voltage protection, but it's always safest to use the power jack on the Acquisition Board. Do not use the power supply on the FPGA, next to the USB port. The acquisition board power jack has extra protections to avoid damage to the system that the FPGA plug lacks.
 
-    .. image:: ../_static/images/usermanual/quickstart/power_usb.jpg
-      :width: 70%
-      :align: center
+.. image:: ../_static/images/usermanual/quickstart/power_usb.jpg
+    :width: 70%
+    :align: center
 
-#. **Connecting the headstages**
+Connecting the headstages
+-------------------------------------------
 
-    *Required components: RHD headstage, SPI cables*
+*Required components: RHD headstage, SPI cables*
 
-    There are four headstage connectors on the front of the acquisition board. You can use any combination of the four (but you might as well start with input "A"). The connectors on the SPI cables are very small, so sometimes they can be tricky to insert. Make sure everything is properly aligned before you apply pressure, otherwise you might break the connector. Plug the opposite end of each cable (or series of daisy-chained cables) into a headstage, or a headstage Y-adapter, if you're using two headstages on one port.
+There are four headstage connectors on the front of the acquisition board. You can use any combination of the four (but you might as well start with input "A"). The connectors on the SPI cables are very small, so sometimes they can be tricky to insert. Make sure everything is properly aligned before you apply pressure, otherwise you might break the connector. Plug the opposite end of each cable (or series of daisy-chained cables) into a headstage, or a headstage Y-adapter, if you're using two headstages on one port.
 
-    .. image:: ../_static/images/usermanual/quickstart/spi_cable.jpg
-      :width: 70%
-      :align: center
+.. image:: ../_static/images/usermanual/quickstart/spi_cable.jpg
+    :width: 70%
+    :align: center
 
-#. **Connecting peripheral devices**
+Connecting peripheral devices
+-------------------------------------------
 
-    *Required components: I/O Board, HDMI cable*
+*Required components: I/O Board, HDMI cable*
 
-    External devices that generate digital or analog signals can interface with Open Ephys system through an I/O board. We use HDMI cables to connect to the I/O board, as these are cheap and have exactly the right number of shielded wires inside of them. Please note that these ports are not standard HDMI points; they will not work with any HDMI-compatible devices.
+External devices that generate digital or analog signals can interface with Open Ephys system through an I/O board. We use HDMI cables to connect to the I/O board, as these are cheap and have exactly the right number of shielded wires inside of them. Please note that these ports are not standard HDMI points; they will not work with any HDMI-compatible devices.
 
 |
 
-    The HDMI connections on the acquisition board are as follows:
+The HDMI connections on the acquisition board are as follows:
 
 |
 
-    .. image:: ../_static/images/usermanual/quickstart/in_out_label.png
+.. image:: ../_static/images/usermanual/quickstart/in_out_label.png
 
 
-#. **Operation**
+Operation
+-------------------------------------------
 
-    This section assumes you have compatible acquisition software installed (likely the Open Ephys GUI or Bonsai). Check out :ref:`this page <acquisitionsoftware>` for more info.
+This section assumes you have compatible acquisition software installed (likely the Open Ephys GUI or Bonsai). Check out :ref:`this page <acquisitionsoftware>` for more info.
 
-    These are some things to keep in mind:
+These are some things to keep in mind:
 
-    *Using a laptop*
+*Using a laptop*
 
-    If you're using the acquisition board with a laptop that's running off battery power, you will have a "floating" ground. This will cause your signals to look extremely noisy. To fix the issue, connect the ground of the acquisition board to whatever ground you're using for your experimental setup (perhaps a wall socket or a Faraday cage). You can either do this via the BNC connector (alligator clips work well for this), or by attaching a wire to one of the two dedicated screw terminals on the side of the board. The screw terminals are preferred because the BNC may be needed for another purpose. 
-
-    .. caution:: If you use the BNC for grounding, be extra careful to attach your ground wire to the exterior shell, not the center pin. Connecting the center pin of the BNC to ground will short your board and may fry the FPGA.
+If you're using the acquisition board with a laptop that's running off battery power, you will have a "floating" ground. This will cause your signals to look extremely noisy. To fix the issue, connect the ground of the acquisition board to whatever ground you're using for your experimental setup (perhaps a wall socket or a Faraday cage). You can either do this via the BNC connector (alligator clips work well for this), or by attaching a wire to one of the two dedicated screw terminals on the side of the board. The screw terminals are preferred because the BNC may be needed for another purpose. 
 
-    *Analog inputs*
+.. caution:: If you use the BNC for grounding, be extra careful to attach your ground wire to the exterior shell, not the center pin. Connecting the center pin of the BNC to ground will short your board and may fry the FPGA.
 
-    There is a small DC offset (~0.4 V) on the ADCs when they're in ±5V range. This offset is taken into account by the Open Ephys GUI, but since the offset can be slightly different for each channel, the traces may not be exactly centered around zero. Be sure to measure the "zero" value for each channel if you're doing any analysis that depends on absolute DC values and applying a high-pass filter is not possible.
+*Analog inputs*
 
-    .. note:: If any of the ADC channels are not connected (i.e., the signal pin is floating), signals from adjacent channels will bleed through. This is expected behavior.
+There is a small DC offset (~0.4 V) on the ADCs when they're in ±5V range. This offset is taken into account by the Open Ephys GUI, but since the offset can be slightly different for each channel, the traces may not be exactly centered around zero. Be sure to measure the "zero" value for each channel if you're doing any analysis that depends on absolute DC values and applying a high-pass filter is not possible.
 
-    *LEDs*
+.. note:: If any of the ADC channels are not connected (i.e., the signal pin is floating), signals from adjacent channels will bleed through. This is expected behavior.
 
-    The LEDs on the acquisition board will flash during normal operation. Fast flashing of the left-most LED (analog output) is expected. The digital input LED should turn green when one of the digital input channels is high, which is useful for checking whether or not your synchronization is working.
+*LEDs*
 
-    It is possible that the LEDs can create noise in your recordings for some grounding configurations. You may also want to disable them if you're performing behavioral experiments in the dark. The LEDs can be turned off by clicking the "LED" button in the `Rhythm FPGA <https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Rhythm-FPGA.html>`_ plugin in the Open Ephys GUI.
+The LEDs on the acquisition board will flash during normal operation. Fast flashing of the left-most LED (analog output) is expected. The digital input LED should turn green when one of the digital input channels is high, which is useful for checking whether or not your synchronization is working.
+
+It is possible that the LEDs can create noise in your recordings for some grounding configurations. You may also want to disable them if you're performing behavioral experiments in the dark. The LEDs can be turned off by clicking the "LED" button in the `Rhythm FPGA <https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Rhythm-FPGA.html>`_ plugin in the Open Ephys GUI.