Documentation: Pip installable environment and build instructions

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.8"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Python requirements required to build your docs
+python:
+  install:
+    - requirements: requirements-minimal.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

@@ -138,3 +138,21 @@ datalad install -rg https://gin.g-node.org/CatalystNeuro/behavior_testing_data
 Once the data is downloaded to your system, you must manually modify the config file ([example](https://github.com/catalystneuro/nwb-conversion-tools/blob/main/base_gin_test_config.json)) located in `./tests/test_on_data/gin_test_config.json` so its corresponding `LOCAL_PATH` key points to the correct folder on your system that contains the dataset folder (e.g., `ephy_testing_data` for testing `ecephys`). The code will automatically detect that the tests are being run locally, so all you need to do ensure the path is correct to your specific system.
 
 The output of these tests is, by default, stored in a temporary directory that is then cleaned after the tests finish running. To examine these files for quality assessment purposes, set the flag `SAVE_OUTPUTS=true` in the `gin_test_config.json` file and modify the variable `OUTPUT_PATH` in the respective test if necessary.
+
+## Build the documentation
+For building the documentation locally, the following procedure can be followed. Create a clean environment and type
+the following commands in your terminal:
+```shell
+git clone https://github.com/catalystneuro/nwb-conversion-tools
+cd nwb-conversion-tools
+pip install -e .[docs]
+```
+These commands install both the latest version of the repo and the dependencies necessary to build the documentation.
+Note that the argument `-e` makes you install [editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)
+
+Now, to build the documention issue the following command in your terminal:
+```shell
+sphinx-build -b html docs ./docs/_build/
+```
+
+This builds the html under `/docs/_build/` (from your root directory, where you have installed `nwb-conversion-tools`). This allows you to review the outcome of the process localy before commiting code.

requirements-rtd.txt

@@ -1,20 +1,3 @@
-pynwb>=1.4.0
-hdmf>=3.2.1
-h5py>=2.10.0
-tqdm>=4.60.0
-natsort>=7.1.1
-numpy>=1.21.0
-PyYAML>=5.4
-jsonschema>=3.2.0
-psutil>=5.8.0
-dandi>=0.34.1
-nwbinspector>=0.2.3
-spikeextractors>=0.9.9
-spikeinterface>=0.93.0
-neo>=0.10.0
-roiextractors>=0.4.0
-lxml>=4.6.5
-scipy>=1.4.1
 myst_parser==0.13.5
 Jinja2<3.1
 sphinx==3.5.1

setup.py

@@ -12,8 +12,11 @@
     install_requires = f.readlines()
 with open(os.path.join(path, "requirements-full.txt")) as f:
     full_dependencies = f.readlines()
+with open(os.path.join(path, "requirements-rtd.txt")) as f:
+    documentation_dependencies = f.readlines()
+
 testing_suite_dependencies = ["pytest", "pytest-cov", "ndx-events==0.2.0", "parameterized==0.8.1"]
-extras_require = dict(full=full_dependencies, test=testing_suite_dependencies)
+extras_require = dict(full=full_dependencies, test=testing_suite_dependencies, docs=documentation_dependencies)
 
 # Create a local copy for the gin test configuration file based on the master file `base_gin_test_config.json`
 gin_config_file_base = Path("./base_gin_test_config.json")