Improve comments

docs/gallery/general/read_basics.py

@@ -183,7 +183,8 @@
 #
 #     (200, 400, 300, 3)
 #
-# This :py:class:`~pynwb.image.OpticalSeries` data contains 200 images of size 400x300 pixels with three channels (red, green, and blue).
+# This :py:class:`~pynwb.image.OpticalSeries` data contains 200 images of size 400x300 pixels with three channels
+# (red, green, and blue).
 #
 # Slicing datasets
 # ----------------

requirements-doc.txt

@@ -1,4 +1,5 @@
-# dependencies to generate the documentation for PyNWB
+# dependencies to generate the documentation for PyNWB and test run the sphinx gallery examples that do not require
+# ROS3 support in h5py. For those examples, use the conda env specified in environment-ros3.yml
 sphinx>=4  # improved support for docutils>=0.17
 sphinx_rtd_theme>=1  # <1 does not work with docutils>=0.17
 matplotlib

test.py

@@ -73,6 +73,7 @@ def _import_from_file(script):
 
 
 def run_example_tests():
+    """Run the Sphinx gallery example files, excluding ROS3-dependent ones, to check for errors."""
     logging.info('running example tests')
     examples_scripts = list()
     for root, dirs, files in os.walk(os.path.join(os.path.dirname(__file__), "docs", "gallery")):
@@ -88,6 +89,7 @@ def run_example_tests():
 
 
 def run_example_ros3_tests():
+    """Run the Sphinx gallery example files that depend on ROS3 to check for errors."""
     logging.info('running example ros3 tests')
     examples_scripts = list()
     for root, dirs, files in os.walk(os.path.join(os.path.dirname(__file__), "docs", "gallery")):
@@ -273,17 +275,17 @@ def main():
         run_test_suite("tests/unit", "pynwb unit tests", verbose=args.verbosity)
 
     # Run example tests
-    if flags['example'] in args.suites:
+    if flags['example'] in args.suites or flags['validation'] in args.suites:
         run_example_tests()
 
     # Run example tests with ros3 streaming examples
-    if flags['example-ros3'] in args.suites:
+    # NOTE this requires h5py to be built with ROS3 support and the dandi package to be installed
+    # this is most easily done by creating a conda environment using environment-ros3.yml
+    if flags['example-ros3'] in args.suites or flags['validation'] in args.suites:
         run_example_ros3_tests()
 
-    # Run validation tests
+    # Run validation tests on the example NWB files generated above
     if flags['validation'] in args.suites:
-        run_example_tests()
-        run_example_ros3_tests()
         validate_nwbs()
 
     # Run integration tests

tox.ini

@@ -99,7 +99,7 @@ commands = {[testenv:build]commands}
 deps = null
 commands = python -c "import hdmf"
 
-# Envs that will execute gallery tests
+# Envs that will execute gallery tests that do not require ROS3
 [testenv:gallery]
 install_command =
     pip install -U {opts} {packages}
@@ -110,7 +110,7 @@ deps =
 
 commands =
     pip install -r requirements-doc.txt
-    # installing allensdk may downgrade certain requirements so
+    # NOTE: installing allensdk may downgrade certain requirements so
     # reinstall the repo with its requirements
     pip install -r requirements-dev.txt -r requirements.txt
     pip install -U -e .
@@ -143,7 +143,7 @@ deps =
 
 commands =
     pip install -r requirements-doc.txt
-    # installing allensdk may downgrade certain requirements so
+    # NOTE: installing allensdk may downgrade certain requirements so
     # reinstall the repo with its requirements
     pip install -r requirements-dev.txt -r requirements.txt
     pip install -U -e .
@@ -161,7 +161,7 @@ deps =
 
 commands =
     pip install -r requirements-doc.txt
-    # installing allensdk may downgrade certain requirements so
+    # NOTE: installing allensdk may downgrade certain requirements so
     # reinstall the repo with its requirements
     pip install -r requirements-dev.txt -r requirements.txt
     pip install -U --pre -e .