begin documentation

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/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx_rtd_theme==1.3.0
+sphinx_copybutton==0.5.2

docs/source/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Scanbuddy'
+copyright = '2025, info@neuroinfo.org'
+author = 'info@neuroinfo.org'
+
+latex_elements = {
+  'extraclassoptions': 'openany,oneside'
+}
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx_rtd_theme',
+    'sphinx.ext.autosectionlabel',
+    'sphinx_copybutton'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/source/developers.rst

@@ -0,0 +1,228 @@
+Developer Documentation
+=======================
+.. _XNAT: https://xnat.org
+.. _Gradle: https://gradle.org/install/
+.. _pip: https://pip.pypa.io/en/stable/installation/
+.. _python: https://www.python.org/downloads/
+.. _PyPi: https://pypi.org/project/dwiqc/
+.. _prequal: https://github.com/MASILab/PreQual
+.. _qsiprep: https://qsiprep.readthedocs.io/en/latest/
+.. _FSL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki
+.. _chromium: https://www.chromium.org/chromium-projects/
+
+.. note::
+    This documentation assumes a basic understanding of the command line. Here's a quick (and free!) crash `course <https://www.codecademy.com/learn/learn-the-command-line>`_ if needed.
+
+HPC/Local Installation
+----------------------
+At the moment, the only supported way to install *DWIQC* is via "bare metal" using the `python`_ package manager `pip`_. A python version >=3.4 will come with pip preinstalled. Esnure that you have both python and pip installed on your HPC or local machine before attempting to install *DWIQC*.
+
+Creating a Virtual Environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+With python and pip installed, you can download and install *DWIQC* from `PyPi`_. You may choose to do so in a `virtual environment <https://docs.python.org/3/library/venv.html>`_. The examples here (and in other portions of the documentation) will assume that you are using a virtual environment, though it won't affect any installation or running instructions.
+
+To create a virtual environment, named dwiqc in this example, run the following command:
+
+.. code-block:: shell
+
+    python3 -m venv dwiqc
+
+Activate the virtual environment:
+
+.. code-block:: shell
+
+    source dwiqc/bin/activate
+
+Your terminal window should look something like this with the name of the virtual environment in parentheses and a directory with the virtual env name.
+
+.. image:: images/venv.png
+
+Installing DWIQC and Dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Install *DWIQC* from the command line using pip:
+
+.. code-block:: shell
+
+    pip install dwiqc
+
+*DWIQC* will being installing along with some of its dependencies. It should only take a few moments. Run ``pip show dwiqc`` to ensure that it was installed successfully.
+
+*DWIQC* relies on the `prequal`_, `qsiprep`_, `chromium`_, and `FSL`_ software packages so we will need to download those respective containers into your local environment. *DWIQC* uses specific and customized versions of these packages. They can be easily installed using *DWIQC*'s *install-containers* functionality. *DWIQC* will default to installing the containers at ``~/.config/dwiqc/containers``; however, the user can specify a download directory using the ``--install-location`` commmand:
+
+.. code-block:: shell
+
+    dwiQC.py install-containers --install-location /path/to/install/location
+
+The containers will take 30-45 minutes to download depending on your connection speed. The containers will occupy ~30GB of storage space so pick a directory with plenty of free storage. Once the containers are downloaded, you'll be ready to `run dwiqc <xnat.html>`_!
+
+XNAT Installation
+-----------------
+The following section will describe how to build and configure *DWIQC* as an `XNAT`_ plugin.
+
+Building the Plugin
+^^^^^^^^^^^^^^^^^^^
+Clone the ``xnat-1.8`` branch from the ``github.com/harvard-nrg/dwiqc`` 
+repository ::
+
+    git clone -b xnat-1.8 --single-branch https://github.com/harvard-nrg/dwiqc
+
+Change into the repository directory and compile the plugin using `Gradle`_ ::
+
+    ./gradlew jar
+
+Once the plugin has been compiled, move the resulting ``.jar`` into your XNAT plugins directory ::
+
+    mv ./build/libs/dwiqc-plugin-1.0.0.jar ${XNAT_HOME}/plugins/
+
+Configuring Nginx
+^^^^^^^^^^^^^^^^^
+You will have to do a little bit of extra configuration in the ``nginx.conf`` file on the XNAT server. Without this configuration, XNAT will start downloading all of the DWIQC reports to your local machine and you won't be able to view them on the browser. Here's a way around that!
+
+First, navigate to your ``nginx`` directory. This might be located at ``/etc/nginx`` if you're running XNAT on "bare metal" or under your ``xnat-docker-compose`` directory if you're using that to run your XNAT. Once you're there, cd into the ``conf.d`` directory and open up the server config file using your favorite text editor. ``xnat-docker-compose`` users may have a file named ``nginx.conf``. 
+
+Your ``nginx.conf`` file may look something like this (lines of interest highlighted):
+
+.. code-block:: text
+  :emphasize-lines: 71-85
+
+    #user www-data;
+    worker_processes auto;
+    #pid /run/nginx.pid;
+    events {
+      worker_connections 1024;
+      # multi_accept on;
+    }
+    http {
+      ##
+      # Basic Settings
+      ##
+      sendfile on;
+      tcp_nopush on;
+      tcp_nodelay on;
+      keepalive_timeout 100;
+      types_hash_max_size 2048;
+      # server_tokens off;
+      # server_names_hash_bucket_size 64;
+      # server_name_in_redirect off;
+      include /etc/nginx/mime.types;
+      default_type application/octet-stream;
+      ##
+      # SSL Settings
+      ##
+      #ssl_protocols TLSv1 TLSv1.1 TLSv1.2; # Dropping SSLv3, ref: POODLE
+      #ssl_prefer_server_ciphers on;
+      ##
+      # Logging Settings
+      ##
+      access_log /var/log/nginx/access.log;
+      error_log /var/log/nginx/error.log;
+      ##
+      # Gzip Settings
+      ##
+      gzip on;
+      gzip_disable "msie6";
+      # gzip_vary on;
+      # gzip_proxied any;
+      # gzip_comp_level 6;
+      # gzip_buffers 16 8k;
+      # gzip_http_version 1.1;
+      # gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+      ##
+      # Virtual Host Configs
+      ##
+      #include /etc/nginx/conf.d/*.conf;
+      #include /etc/nginx/sites-enabled/*;
+      server {
+        listen 80;
+        return                301 https://cbscentral02.rc.fas.harvard.edu$request_uri;
+      } 
+      server {
+        listen 443 ssl;
+        ssl_certificate       /etc/pki/tls/cbscentral02_rc_fas_harvard_edu.crt;
+        ssl_certificate_key   /etc/pki/tls/cbscentral02_rc_fas_harvard_edu.key;
+        location / {
+            proxy_pass                          http://xnat-web:8080;
+            proxy_redirect                      http://xnat-web:8080 $scheme://localhost;
+            proxy_set_header Host               $host;
+            proxy_set_header X-Real-IP          $remote_addr;
+            proxy_set_header X-Forwarded-Host   $host;
+            proxy_set_header X-Forwarded-Server $host;
+            proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
+            proxy_connect_timeout               150;
+            proxy_send_timeout                  100;
+            proxy_read_timeout                  100;
+            proxy_buffers                       8 4k;
+            proxy_max_temp_file_size            2048m;
+            client_max_body_size                0;
+            client_body_buffer_size             128k;
+            # Don't download pdf reports when imbedded in an iframe
+            location ~ /data.*\.pdf$ {
+              proxy_pass http://xnat-web:8080;
+              proxy_hide_header Content-Disposition;
+            }
+            # Don't download qsiprep html report when imbedded in an iframe
+            location ~ /data.*qsiprep\.html$ {
+              proxy_pass http://xnat-web:8080;
+              proxy_hide_header Content-Disposition;
+            }
+            # Don't download svg files when imbedded in an iframe
+            location ~ /data.*\.svg$ {
+              proxy_pass http://xnat-web:8080;
+              proxy_hide_header Content-Disposition;
+            }
+        }
+        access_log /var/log/nginx/xnat.access.log;
+        error_log /var/log/nginx/xnat.error.log;
+    }
+    }
+
+This is a bit overwhelming but the part to focus on is at the bottom starting with the comment that says `Don't download pdf reports when imbedded in an iframe`. Copy and paste all three ``location`` blocks so that XNAT doesn't automatically download the pdf files, qsiprep.html and the svg files. So just this section:
+
+.. code-block:: yaml
+
+    # Don't download pdf reports when imbedded in an iframe
+    location ~ /data.*\.pdf$ {
+      proxy_pass http://xnat-web:8080;
+      proxy_hide_header Content-Disposition;
+    }
+    # Don't download qsiprep html report when imbedded in an iframe
+    location ~ /data.*qsiprep\.html$ {
+      proxy_pass http://xnat-web:8080;
+      proxy_hide_header Content-Disposition;
+    }
+    # Don't download svg files when imbedded in an iframe
+    location ~ /data.*\.svg$ {
+      proxy_pass http://xnat-web:8080;
+      proxy_hide_header Content-Disposition;
+    }
+
+With that added to the ``nginx.conf`` file, you're ready to activate your plugin!
+
+.. note::
+
+    If tomcat or the docker containers are running when you make this change you will have to restart them!
+
+Activating the Plugin
+^^^^^^^^^^^^^^^^^^^^^
+There are several necessary steps to activate the *DWIQC* plugin via your XNAT instance's home page. First, login and click on the *Administer* button at the top:
+
+.. image:: images/administer-button.png
+
+Next, click on *Data Types*:
+
+.. image:: images/data-types.png
+
+Click on *Setup Additional Data Type*:
+
+.. image:: images/setup-data-type.png
+
+You will see a drop down menu. Select *neuroinfo:dwiqc* and click *Submit*.
+
+.. image:: images/neuroinfo-dwiqc.png
+
+You can leave all of the True/False statements as they are in this window (unless you have a reason to change them). Fill in the boxes labeled *Singular Name*, *Plural Name*, and *Category* with the information shown below and click *Next*. 
+
+.. image:: images/dwiqc-access-options.png
+
+Click *Next* through the remainder of the windows without editing anything, and Voila! *DWIQC* is now configured on your XNAT instance.

docs/source/index.rst

@@ -0,0 +1,30 @@
+.. AnatQC documentation master file, created by
+   sphinx-quickstart on Tue Jun 20 12:46:20 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to DWIQC's documentation!
+==================================
+.. _Prequal: https://doi.org/10.1002/mrm.28678 
+.. _QSIPREP: https://doi.org/10.1038/s41592-021-01185-5 
+.. _XNAT: https://doi.org/10.1385/NI:5:1:11
+
+DWIQC is a diffusion MRI preprocessing and quality control pipeline built on the `Prequal`_ and `QSIPREP`_ software packages. Working closely with neuroimaging experts, we designed an ergonomic user interface for the `XNAT`_ informatics and data management platform that allows users to quickly assess image quality and use those insights to get ahead of issues within the data acquisition workflow. Non-XNAT users can also benefit from DWIQC as a one-stop shop for running two state of the art diffusion pipelines simultaneously and receiving their associated outputs. See `Prequal`_ and `QSIPREP`_ documentation for further details.
+
+
+.. image:: images/logo.png
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   xnat
+   developers
+   xnattagger
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`