Documentation Update (#166)

* Update all Docker scripts (#161) * Update console commands in installation docs * Update console commands in pydesigner installation doc * Docs: add system requirements * Docs: add Docker instructions * Update system requirements * Docs: include python modules * Update README.md
muscbridge · Feb 20, 2020 · fb28cf5 · fb28cf5
1 parent c791589
commit fb28cf5
Show file tree

Hide file tree

Showing 189 changed files with 17,304 additions and 491 deletions.
diff --git a/Makefile b/Makefile
@@ -14,6 +14,13 @@ help:
 
 .PHONY: help Makefile
 
+# This calls sphinx-apidoc to create an api folder in SOURCEDIR with
+# documentation for all Python modules
+buildapi:
+	@sphinx-apidoc -fMeET -o docsrc/api designer 
+	@echo "Auto-generation of API documentation finished. " \
+			"The generated files are in 'api/'"
+
 github:
 	@make html
 	@cp -a docs/html/. ./docs

diff --git a/README.md b/README.md
diff --git a/designer/test/modules.rst b/designer/test/modules.rst
@@ -0,0 +1,6 @@
+est
+===
+
+.. toctree::
+   :maxdepth: 4
+
diff --git a/docs/.buildinfo b/docs/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 4ede22ff1c6822f7145efaf41eb8eaa5
+config: cdb9c8ea2f194b766698f10b6619310d
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/_sources/api/api.rst.txt b/docs/_sources/api/api.rst.txt
@@ -0,0 +1,9 @@
+API Documentation
+=================
+
+Information on specific functions, classes, and methods.
+
+.. toctree::
+   :glob:
+
+   api/*
diff --git a/docs/_sources/api/designer.fitting.dwidirs.rst.txt b/docs/_sources/api/designer.fitting.dwidirs.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.fitting.dwidirs
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.fitting.dwipy.rst.txt b/docs/_sources/api/designer.fitting.dwipy.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.fitting.dwipy
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.fitting.rst.txt b/docs/_sources/api/designer.fitting.rst.txt
@@ -0,0 +1,15 @@
+designer.fitting package
+========================
+
+.. automodule:: designer.fitting
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+   designer.fitting.dwidirs
+   designer.fitting.dwipy
diff --git a/docs/_sources/api/designer.info.rst.txt b/docs/_sources/api/designer.info.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.info
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.postprocessing.filters.rst.txt b/docs/_sources/api/designer.postprocessing.filters.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.postprocessing.filters
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.postprocessing.rst.txt b/docs/_sources/api/designer.postprocessing.rst.txt
@@ -0,0 +1,14 @@
+designer.postprocessing package
+===============================
+
+.. automodule:: designer.postprocessing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+   designer.postprocessing.filters
diff --git a/docs/_sources/api/designer.preprocessing.mrinfoutil.rst.txt b/docs/_sources/api/designer.preprocessing.mrinfoutil.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.preprocessing.mrinfoutil
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.preprocessing.mrpreproc.rst.txt b/docs/_sources/api/designer.preprocessing.mrpreproc.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.preprocessing.mrpreproc
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.preprocessing.preparation.rst.txt b/docs/_sources/api/designer.preprocessing.preparation.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.preprocessing.preparation
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.preprocessing.rician.rst.txt b/docs/_sources/api/designer.preprocessing.rician.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.preprocessing.rician
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.preprocessing.rst.txt b/docs/_sources/api/designer.preprocessing.rst.txt
@@ -0,0 +1,20 @@
+designer.preprocessing package
+==============================
+
+.. automodule:: designer.preprocessing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+   designer.preprocessing.mrinfoutil
+   designer.preprocessing.mrpreproc
+   designer.preprocessing.preparation
+   designer.preprocessing.rician
+   designer.preprocessing.smoothing
+   designer.preprocessing.snrplot
+   designer.preprocessing.util
diff --git a/docs/_sources/api/designer.preprocessing.smoothing.rst.txt b/docs/_sources/api/designer.preprocessing.smoothing.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.preprocessing.smoothing
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.preprocessing.snrplot.rst.txt b/docs/_sources/api/designer.preprocessing.snrplot.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.preprocessing.snrplot
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.preprocessing.util.DWIFile.rst.txt b/docs/_sources/api/designer.preprocessing.util.DWIFile.rst.txt
@@ -0,0 +1,35 @@
+DWIFile
+=======
+
+.. currentmodule:: designer.preprocessing.util
+
+.. autoclass:: DWIFile
+   :show-inheritance:
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~DWIFile.getBVAL
+      ~DWIFile.getBVEC
+      ~DWIFile.getFull
+      ~DWIFile.getJSON
+      ~DWIFile.getName
+      ~DWIFile.getPath
+      ~DWIFile.hasJSON
+      ~DWIFile.isAcquisition
+      ~DWIFile.isPartialFourier
+      ~DWIFile.print
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: getBVAL
+   .. automethod:: getBVEC
+   .. automethod:: getFull
+   .. automethod:: getJSON
+   .. automethod:: getName
+   .. automethod:: getPath
+   .. automethod:: hasJSON
+   .. automethod:: isAcquisition
+   .. automethod:: isPartialFourier
+   .. automethod:: print
diff --git a/docs/_sources/api/designer.preprocessing.util.DWIParser.rst.txt b/docs/_sources/api/designer.preprocessing.util.DWIParser.rst.txt
@@ -0,0 +1,21 @@
+DWIParser
+=========
+
+.. currentmodule:: designer.preprocessing.util
+
+.. autoclass:: DWIParser
+   :show-inheritance:
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~DWIParser.cat
+      ~DWIParser.getPath
+      ~DWIParser.json2fslgrad
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: cat
+   .. automethod:: getPath
+   .. automethod:: json2fslgrad
diff --git a/docs/_sources/api/designer.preprocessing.util.bvec_is_fullsphere.rst.txt b/docs/_sources/api/designer.preprocessing.util.bvec_is_fullsphere.rst.txt
@@ -0,0 +1,6 @@
+bvec_is_fullsphere
+==================
+
+.. currentmodule:: designer.preprocessing.util
+
+.. autofunction:: bvec_is_fullsphere
diff --git a/docs/_sources/api/designer.preprocessing.util.find_valid_ext.rst.txt b/docs/_sources/api/designer.preprocessing.util.find_valid_ext.rst.txt
@@ -0,0 +1,6 @@
+find_valid_ext
+==============
+
+.. currentmodule:: designer.preprocessing.util
+
+.. autofunction:: find_valid_ext
diff --git a/docs/_sources/api/designer.preprocessing.util.rst.txt b/docs/_sources/api/designer.preprocessing.util.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.preprocessing.util
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.preprocessing.util.vecs_are_fullsphere.rst.txt b/docs/_sources/api/designer.preprocessing.util.vecs_are_fullsphere.rst.txt
@@ -0,0 +1,6 @@
+vecs_are_fullsphere
+===================
+
+.. currentmodule:: designer.preprocessing.util
+
+.. autofunction:: vecs_are_fullsphere
diff --git a/docs/_sources/api/designer.pydesigner.rst.txt b/docs/_sources/api/designer.pydesigner.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.pydesigner
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.rst.txt b/docs/_sources/api/designer.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/api/designer.system.rst.txt b/docs/_sources/api/designer.system.rst.txt
@@ -0,0 +1,14 @@
+designer.system package
+=======================
+
+.. automodule:: designer.system
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+   designer.system.systemtools
diff --git a/docs/_sources/api/designer.system.systemtools.rst.txt b/docs/_sources/api/designer.system.systemtools.rst.txt
@@ -0,0 +1,4 @@
+.. automodule:: designer.system.systemtools
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/_sources/docker/docker_configuration.rst.txt b/docs/_sources/docker/docker_configuration.rst.txt
@@ -0,0 +1,117 @@
+Docker Configuration
+====================
+
+Docker can be configured in a wide-varietry of ways based on hardware
+resources available. Parameters such as CPU cores, RAM and storage can
+be assigned to Docker for running NeuroDock.
+
+For validations purposes, the NeuroDock image was tested to work as
+intended on the following three systems:
+
+.. csv-table::
+    :header: "Part", "Machine A", "Machine B", "Machine C"
+
+    "Build", "Apple iMac Pro", "Custom", "Custom"
+    "OS", "Mac OS X Mojave", "Ubuntu 18.04", "Microsoft Windows 10 Pro"
+    "CPU", "Intel Xeon W [8C/16T]", "AMD Ryzen R9 2700X [8C/16T]", "AMD Ryzen R9 2700X [8C/16T]"
+    "Memory", 64 GB, 16 GB, 16 GB
+    "Video", Raden Pro Vega 56 8 GB, Nvidia GTX 1080 8 GB, Nvidia GTX 1080 8 GB
+
+We found identical results across the three operating systes on all
+these configurations.
+
+Docker Preferences
+------------------
+
+Based on Docker's system requirements, we recommend assigning the
+following sysem resources to Docker:
+
+.. csv-table::
+    :header: "Parameter", "Value"
+
+    "CPUs", 8
+    "Memory", 16.00 GB
+    "Disk image size", 32.00 GB
+
+By default, Docker assigns itself half the number of available
+CPU cores and 2 GB of memory. Considering that the entire NeuroDock
+image is ~14.5 GB, we recommend at least double in disk image size.
+You may configure your Docker Engine to run on this configuration, or
+input your own values based on your processing needs. The following
+sections detail how to set these parameters.
+
+Linux
+~~~~~
+
+CPU and memory access to Docker containers on Linux machines is
+manipulated via CFGS scheduler flags at run time. These flags are:
+
+.. csv-table::
+    :header: "Flag", "Description"
+
+    :code:`--cpus=<value>`, specify how many CPU cores to use
+    :code:`-m` or :code:`--memory`, specify the maximum amount of memory available to containers
+
+For a more comprehensive list of manupulable system parameters for
+for Linux, please visit the `Runtime options with Memory, CPUs, and GPUs`_
+page on Docker documentation.
+
+.. _Runtime options with Memory, CPUs, and GPUs: https://docs.docker.com/config/containers/resource_constraints/
+
+Mac OS
+~~~~~~
+
+Manipulating these three variables is very simple on Mac OS because
+these parameters are located in the GUI.
+
+1. On the Docker icon in the status bar, right-click on the Docker
+icon, then **Preferences**.
+
+2. Click on the **Resources** tab on the left
+
+.. figure:: /images/Docker_Mac_resources.png
+    :scale: 75 %
+    :align: center
+
+    Docker Mac preferences GUI; click on resources
+
+3. The **Resourcs** menu will show you the configuration, please
+change them to desired valus. You may leave "Swap" at default.
+
+.. figure:: /images/Docker_Mac_configs.png
+    :scale: 75 %
+    :align: center
+
+    Docker Mac resources configuration
+
+
+Windows
+~~~~~~~
+
+Similar to the Mac, the same sequence of steps apply for the Windows
+platform.
+
+1. Right-click on the Dpcker icon in the taskbar, then click on
+**Preferences**.
+
+2. Clock on the **Resources** tab on the left.
+
+.. figure:: /images/Docker_Win_configs.png
+    :scale: 75 %
+    :align: center
+
+    Docker Windows preferences GUI; configure as desired
+
+3. The **Resourcs** menu will show you the configuration, please
+change them to desired valus. You may leave "Swap" at default.
+
+Setting the correct configuration will force Docker to not exceed
+these constraints. By splitting up CPU and memory loads, researchers
+can process multiple DWIs simultaneously.
+
+GPU Support
+-----------
+
+At this time, there is no CUDA or ROCm GPU support. These feature are
+planned for a later release. Please use the non-Docker, native Linux
+configuration to utilize GPU for eddy and EPI correction.