Sphinx documentation (#27)

* Fix of the dartsort parameter such that it uses scratch_dir

* Added spikeinterface backend

* Added Google style documentation for all the functions

* Ruff fixes

* Changes to documentation and README.md

Author: rai-pranav

.gitignore

@@ -181,4 +181,9 @@ testing.ipynb
 *.parquet
 scratch/
 .DS_Store
-random_testing_scripts.py
+random_testing_scripts.py
+84c48d67-3d58-4cb6-8e57-fd206e6508d6/
+
+
+#Sphinx doucmentation
+docs/build/

CONTRIBUTING.md

@@ -6,6 +6,7 @@ The main branch is the trunk and features branches are squashed merge after a su
 
 Contributer steps:
 - [X] make sure the tests pass locally
+- [X] follow Google docstring format for all function and class documentation
 - [X] use `ruff format` and `ruff check` to make sure the formatting is correct
 - [X] `CHANGELOG.md` documents the changes, references the PR, the date and the new version number in `./src/ephysatlas/__init__.py`
 - [X] create a PR from your feature branch to main

README.md

@@ -5,182 +5,20 @@
 
 This repository contains tools for computing electrophysiology features and performing region inference from neural recordings.
 
-## Installation
+## Documentation
 
-> **Note**: It is recommended to create and use a separate virtual environment before installation.
+For detailed documentation, installation instructions, usage examples, and API reference, please visit our comprehensive documentation:
+
+**[📚 View Full Documentation](docs/source/index.rst)**
+
+## Quick Installation
 
-1. Clone the repository and navigate to the directory:
 ```bash
 git clone https://github.com/int-brain-lab/ibleatools.git
 cd ibleatools
-```
-
-2. Install the package in editable mode:
-```bash
 pip install -e .
 ```
 
-## Main Functions
-
-The package provides functions for electrophysiology analysis:
-
-### 1. Feature Computation from Probe ID (`compute_features_from_pid`)
-
-This function computes various electrophysiological features from raw neural recordings using data from the IBL database with a probe ID (pid).
-
-Basic usage:
-```python
-from one.api import ONE
-from ephysatlas.feature_computation import compute_features_from_pid
-
-# Using IBL database
-one = ONE()  # Initialize ONE client
-df_features = compute_features_from_pid(
-    pid="your_probe_id",
-    t_start=300.0,  # Start time in seconds
-    duration=3.0,   # Duration in seconds
-    one=one
-)
-```
-
-The function returns a pandas DataFrame containing various electrophysiological features, which are also saved in Parquet format for efficient storage and retrieval.
-
-### 2. Feature Computation from Files (`compute_features_from_file`)
-
-This function computes various electrophysiological features from local .cbin files (AP and LF band data).
-
-Basic usage:
-```python
-from ephysatlas.feature_computation import compute_features_from_file
-
-# Using local files
-df_features = compute_features_from_file(
-    ap_file="path/to/ap.cbin",
-    lf_file="path/to/lf.cbin",
-    t_start=300.0,
-    duration=3.0
-)
-```
-
-### 3. Legacy Function (`compute_features`) - DEPRECATED
-
-> **Note**: The `compute_features` function is deprecated and will be removed in a future version. Please use `compute_features_from_pid` or `compute_features_from_file` instead.
-
-This function was the original interface for computing electrophysiological features. It can work with either:
-- Data from the IBL database using a probe ID (pid)
-- Local .cbin files (AP and LF band data)
-
-Basic usage:
-```python
-from one.api import ONE
-from ephysatlas.feature_computation import compute_features
-
-# Using IBL database
-one = ONE()  # Initialize ONE client
-df_features = compute_features(
-    pid="your_probe_id",
-    t_start=300.0,  # Start time in seconds
-    duration=3.0,   # Duration in seconds
-    one=one
-)
-
-# Using local files
-df_features = compute_features(
-    ap_file="path/to/ap.cbin",
-    lf_file="path/to/lf.cbin",
-    t_start=300.0,
-    duration=3.0
-)
-```
-
-The function returns a pandas DataFrame containing various electrophysiological features, which are also saved in Parquet format for efficient storage and retrieval.
-
-> **Note**: Due to a known issue in PyTorch ([#132372](https://github.com/pytorch/pytorch/issues/132372)), you might encounter a SEGFAULT when running the feature computation. To resolve this, you can either:
-> 1. Import torch at the start of your script:
->    ```python
->    import torch  # Add this at the beginning of your script
->    ```
-> 2. Set the `DYLD_LIBRARY_PATH` environment variable to point to your virtual environment's torch library:
->    ```bash
->    export DYLD_LIBRARY_PATH=/path/to/your/venv/lib/python3.x/site-packages/torch/lib
->    ```
-
-> **Important**: This package (`ephysatlas`) is different from the `ephys_atlas` package (with underscore) from the [paper-ephys-atlas](https://github.com/int-brain-lab/paper-ephys-atlas) repository.
-
-### 4. Region Inference (`infer_regions`)
-
-This function uses pre-trained models to infer brain regions from the computed features. It performs inference across multiple model folds and returns both the predicted regions and their probabilities.
-
-Basic usage:
-
-```python
-from ephysatlas.regionclassifier.region_inference import infer_regions
-
-# Perform region inference
-predicted_probas, predicted_region = infer_regions(
-    df_inference=df_features,  # DataFrame from compute_features
-    path_model="path/to/model"  # Path to the model directory
-)
-```
-
-The function returns:
-- `predicted_probas`: Array of shape (n_folds, n_channels, n_regions) containing region probabilities
-- `predicted_region`: Array of shape (n_folds, n_channels) containing predicted region indices
-
-## Usage through CLI
-
-The CLI interface is through `main.py`, which can be run using a configuration file:
-
-```bash
-python main.py --config config.yaml
-```
-
-Using CLI one can do both feature computations and region inference by specifying it in the configuration.
-
-> **Note**: The CLI currently uses the deprecated `compute_features` function internally. This will be updated in a future version to use the new `compute_features_from_pid` and `compute_features_from_file` functions.
-
-### Configuration File
-
-The configuration is managed through a YAML file. To avoid committing local changes, the actual configuration file (`config.yaml`) is ignored by git. Instead, a template file (`config_template.yaml`) is provided. To use the tool:
-
-1. Copy the template file to create your local configuration:
-```bash
-cp config_template.yaml config.yaml
-```
-
-2. Edit `config.yaml` with your specific settings:
-```yaml
-# Required parameters
-pid: "5246af08-0730-40f7-83de-29b5d62b9b6d"  # Probe ID
-t_start: 300.0  # Start time in seconds
-duration: 3.0  # Duration in seconds
-
-# Operation mode
-mode: "both"  # Options: 'features', 'inference', or 'both'
-
-# Optional parameters
-output_dir: "/path/to/output_dir"  # Path to output directory
-model_path: "/path/to/model"  # Path to the model directory for region inference
-```
-
-#### Configuration Parameters
-
-- **Required Parameters**:
-  - `pid`: Probe ID for the recording
-  - `t_start`: Start time in seconds
-  - `duration`: Duration of the analysis in seconds
-
-- **Operation Mode**:
-  - `mode`: Specifies which operations to perform
-    - `features`: Only compute features
-    - `inference`: Only perform region inference
-    - `both`: Perform both feature computation and region inference
-
-- **Optional Parameters**:
-  - `output_dir`: Path to output directory for saving results
-  - `model_path`: Path to the model directory for region inference. If not provided, a default path will be used
-
-## Output
+## Contributing
 
-- Features are saved in Parquet format for efficient storage
-- Region inference results include predicted regions and their probabilities
+Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to contribute to this project.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,135 @@
+# Building ibleatools Documentation
+
+This directory contains the Sphinx documentation for ibleatools. This README explains how to build and serve the documentation locally for development purposes.
+
+## Prerequisites
+
+Before building the documentation, ensure you have the following installed:
+
+1. **Python 3.10+** - The project requires Python 3.10 or higher
+2. **ibleatools package** - Install the package in development mode:
+   ```bash
+   pip install -e .
+   ```
+3. **Sphinx and documentation dependencies** - Install the required packages:
+   ```bash
+   pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints
+   ```
+
+## Building the Documentation
+
+### Quick Start
+
+To build the documentation, navigate to the `docs/` directory and run:
+
+```bash
+cd docs/
+make html
+```
+
+This will generate the HTML documentation in the `build/html/` directory.
+
+### Available Build Commands
+
+The documentation supports several build targets:
+
+- **`make html`** - Build HTML documentation (default)
+- **`make clean`** - Clean the build directory
+- **`make help`** - Show all available build options
+- **`make livehtml`** - Build HTML with live reload (requires `sphinx-autobuild`)
+
+### Windows Users
+
+If you're on Windows, use the provided batch file instead:
+
+```cmd
+cd docs/
+make.bat html
+```
+
+## Viewing the Documentation
+
+After building, you can view the documentation by:
+
+1. **Opening the HTML files directly:**
+   - Navigate to `docs/build/html/`
+   - Open `index.html` in your web browser
+
+2. **Using a local web server:**
+   ```bash
+   cd docs/build/html/
+   python -m http.server 8000
+   ```
+   Then open http://localhost:8000 in your browser
+
+## Development Workflow
+
+### Making Changes
+
+1. Edit the source files in `docs/source/`
+2. Rebuild the documentation: `make html`
+3. Refresh your browser to see changes
+
+### Live Reload (Optional)
+
+For automatic rebuilding when files change, install `sphinx-autobuild` and use:
+
+```bash
+pip install sphinx-autobuild
+make livehtml
+```
+
+This will start a local server that automatically rebuilds and refreshes the documentation when you make changes.
+
+## Documentation Structure
+
+The documentation is organized as follows:
+
+```
+docs/
+├── source/           # Sphinx source files
+│   ├── index.rst     # Main documentation page
+│   ├── ephysatlas.rst # Package overview
+│   ├── features.rst  # Feature computation module
+│   ├── plots.rst     # Visualization module
+│   ├── reveal.rst    # High-level interface
+│   ├── utils.rst     # Utility functions
+│   ├── how-to/       # Tutorials and guides
+│   └── reference/    # API reference
+├── build/            # Generated documentation (git-ignored)
+├── Makefile          # Build commands
+└── make.bat          # Windows build commands
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Import errors**: Ensure ibleatools is installed in development mode (`pip install -e .`)
+2. **Missing dependencies**: Install all required packages listed in the Prerequisites section
+3. **Build errors**: Check that all source files are valid RST format
+4. **Permission errors**: Ensure you have write permissions to the `build/` directory
+
+### Cleaning Build Artifacts
+
+If you encounter build issues, clean the build directory:
+
+```bash
+make clean
+make html
+```
+
+## Contributing to Documentation
+
+When contributing to the documentation:
+
+1. Follow the existing RST format and structure
+2. Use Google-style docstrings in Python code (as specified in CONTRIBUTING.md)
+3. Test your changes by building the documentation locally
+4. Ensure all links and references work correctly
+
+## Online Documentation
+
+The latest documentation is available online at:(This is TODO) [https://int-brain-lab.github.io/ibleatools](https://int-brain-lab.github.io/ibleatools)
+
+For questions or issues with the documentation, please open an issue on the [ibleatools GitHub repository](https://github.com/int-brain-lab/ibleatools).