Skip to content

Commit 773ed84

Browse files
Peyman-NPeyman-N
authored
adding read the docs (#72)
* adding read the docs * typos
1 parent 50a051e commit 773ed84

9 files changed

+203
-0
lines changed

‎.readthedocs.yaml

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
version: "2"
2+
3+
build:
4+
os: "ubuntu-22.04"
5+
tools:
6+
python: "3.10"
7+
8+
python:
9+
install:
10+
- requirements: docs/requirements.txt
11+
12+
sphinx:
13+
configuration: docs/source/conf.py

‎docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/requirements.txt

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
sphinx==7.1.2
2+
sphinx-rtd-theme==1.3.0rc1

‎docs/source/conf.py

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'bids2openminds'
10+
copyright = '2024, open Metadata Initiative'
11+
author = 'Peyman Najafi'
12+
release = '0.01'
13+
14+
# -- General configuration ---------------------------------------------------
15+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
16+
17+
extensions = ["sphinx.ext.intersphinx"]
18+
19+
templates_path = ['_templates']
20+
21+
22+
23+
24+
25+
# -- Options for HTML output -------------------------------------------------
26+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
27+
28+
html_theme = 'sphinx_rtd_theme'
29+
html_static_path = ['_static']
30+
html_show_sphinx = False
31+
32+

‎docs/source/index.rst

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. bids2openminds documentation master file, created by
2+
sphinx-quickstart on Thu Jul 25 15:21:10 2024.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
bids2openminds documentation
7+
============================
8+
9+
A tool to generate `openMINDS metadata <https://openminds-documentation.readthedocs.io/en/latest/>`_ from `BIDS datasets <https://bids.neuroimaging.io/>`_
10+
11+
.. note::
12+
This project is under active development, please try the first alpha release and send us feedback by creating an issue.
13+
14+
15+
We are curentlly supporting linux, windows and mac os.
16+
17+
.. toctree::
18+
installation
19+
usage

‎docs/source/installation.rst

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Installation
2+
============
3+
4+
Dependencies
5+
############
6+
7+
- `pybids` : Python tools for querying and manipulating BIDS datasets.
8+
- `openminds` : Python package for the openMINDS metadata models. The package contains all openMINDS schemas as Python classes in addition to schema base classes and utility methods.
9+
- `pandas` : Flexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more
10+
- `click` : Used to create a command-line interface for this function.
11+
- `nameparser` : A simple Python module for parsing human names into their individual components.
12+
13+
Installation
14+
############
15+
16+
You can install bids2openminds by using pip:
17+
18+
.. code-block:: console
19+
20+
(.venv) $ pip install bids2openminds

‎docs/source/requirements.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
sphinx-rtd-theme

‎docs/source/usage.rst

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
Usage
2+
=====
3+
4+
You can use bids2openminds as both a command line tool and a python library.
5+
6+
Usage as Python library
7+
=======================
8+
9+
Overview
10+
########
11+
The ``convert`` function processes a Brain Imaging Data Structure (BIDS) directory, converts its contents into OpenMINDS format, and optionally saves the output. It handles BIDS layout, extracts relevant information, and creates a dataset description based on BIDS data using OpenMINDS templates.
12+
13+
14+
Function Signature
15+
##################
16+
>>> def convert(input_path, save_output=False, output_path=None, multiple_files=False, include_empty_properties=False, quiet=False):
17+
18+
Parameters
19+
##########
20+
- ``input_path`` (str): Path to the BIDS directory. This is required and must be a valid directory.
21+
- ``save_output`` (bool, default=False): If True, the converted OpenMINDS data will be saved to the specified output_path.
22+
- ``output_path`` (str, default=None): The path where the OpenMINDS data should be saved. If not specified, defaults to [``input_path``]/openminds.jsonld (single file mode) or [``input_path``]/openminds/ (multiple files mode).
23+
- ``multiple_files`` (bool, default=False): If True, the OpenMINDS data will be saved into multiple files within the specified output_path.
24+
- ``include_empty_properties`` (bool, default=False): If True, includes all the openMINDS properties with empty values in the final output. Otherwise includes only properties that have a non `None` value.
25+
- ``quiet`` (bool, default=False): If True, suppresses warnings and the final report output. Only prints success messages.
26+
27+
Returns
28+
#######
29+
- ``collection`` (openminds.Collection): The OpenMINDS collection object representing the converted dataset. For more information on OpenMINDS collection please refer to `openMINDS readthedocs <https://openminds-documentation.readthedocs.io/en/latest/shared/getting_started/openMINDS_collections.html>`_.
30+
31+
Example Usage
32+
#############
33+
>>> import bids2openminds.converter as converter
34+
>>> input_path = "/path/to/BIDS/dataset"
35+
>>> collection = converter.convert(input_path, save_output=True, output_path="/path/to/output", multiple_files=False, include_empty_properties=False, quiet=False)
36+
37+
Or one can chose the default parmetrs as following:
38+
39+
>>> import bids2openminds.converter as converter
40+
>>> collection = converter.convert("/path/to/BIDS/dataset")
41+
42+
43+
Command-Line Interface (CLI)
44+
============================
45+
This function is also accessible via a command-line interface using the `click` library.
46+
47+
.. code-block:: console
48+
49+
Usage: script.py [OPTIONS] INPUT_PATH
50+
51+
Arguments:
52+
input-path Path to the BIDS directory.
53+
54+
Options:
55+
-o, --output-path TEXT The output path or filename for OpenMINDS file/files.
56+
--single-file Save the entire collection into a single file (default).
57+
--multiple-files Save each node into a separate file within the specified directory.
58+
-e, --include-empty-properties
59+
Include empty properties in the final file.
60+
-q, --quiet Suppress warnings and reports.
61+

0 commit comments

Comments
 (0)