[DOC] Update style guide and auto documentation

.gitignore

@@ -1,4 +1,5 @@
 data/
+docs/generated/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = python -msphinx
-SPHINXPROJ    = meica
+SPHINXPROJ    = tedana
 SOURCEDIR     = .
 BUILDDIR      = _build
 

docs/_templates/function.rst

@@ -0,0 +1,12 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}====================
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div class="clearer"></div>

docs/_templates/module.rst

@@ -0,0 +1,40 @@
+{{ fullname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/api.rst

@@ -0,0 +1,110 @@
+API
+===
+
+:mod:`tedana.model`: Modeling TE-dependence
+--------------------------------------------------
+
+.. automodule:: tedana.model
+   :no-members:
+   :no-inherited-members:
+
+.. autosummary:: tedana.model
+   :toctree: generated/
+   :template: function.rst
+
+   tedana.model.fit_decay
+   tedana.model.fit_decay_ts
+   tedana.model.fitmodels_direct
+   tedana.model.make_optcom
+
+   :template: module.rst
+
+   tedana.model.monoexponential
+   tedana.model.fit
+   tedana.model.combine
+
+.. currentmodule:: tedana
+
+.. _calibration_ref:
+
+
+:mod:`tedana.decomposition`: Data decomposition
+--------------------------------------------------
+
+.. automodule:: tedana.decomposition
+   :no-members:
+   :no-inherited-members:
+
+.. autosummary:: tedana.decomposition
+   :toctree: generated/
+   :template: function.rst
+
+   tedana.decomposition.tedpca
+   tedana.decomposition.tedica
+
+   :template: module.rst
+
+   tedana.decomposition._utils
+
+.. currentmodule:: tedana
+
+.. _calibration_ref:
+
+
+:mod:`tedana.selection`: Component selection
+--------------------------------------------------
+
+.. automodule:: tedana.selection
+   :no-members:
+   :no-inherited-members:
+
+.. autosummary:: tedana.selection
+   :toctree: generated/
+   :template: function.rst
+
+   tedana.selection.selcomps
+
+   :template: module.rst
+
+   tedana.selection._utils
+
+.. currentmodule:: tedana
+
+.. _calibration_ref:
+
+
+:mod:`tedana.workflows`: Component selection
+--------------------------------------------------
+
+.. automodule:: tedana.workflows
+   :no-members:
+   :no-inherited-members:
+
+.. autosummary:: tedana.workflows
+   :template: function.rst
+   :toctree: generated/
+
+   tedana.workflows.tedana
+   tedana.workflows.t2smap
+
+.. currentmodule:: tedana
+
+.. _calibration_ref:
+
+:mod:`tedana.utils`: Utility functions
+--------------------------------------------------
+
+.. automodule:: tedana.utils
+   :no-members:
+   :no-inherited-members:
+
+.. autosummary:: tedana.utils
+   :toctree: generated/
+   :template: module.rst
+
+   tedana.utils.io
+   tedana.utils.utils
+
+.. currentmodule:: tedana
+
+.. _calibration_ref:

docs/conf.py

@@ -19,8 +19,11 @@
 #
 import os
 import sys
+sys.path.insert(0, os.path.abspath('sphinxext'))
 sys.path.insert(0, os.path.abspath('../tedana'))
 
+from sphinxext import make_linkcode_resolve
+
 
 # -- General configuration ------------------------------------------------
 
@@ -32,9 +35,23 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.autodoc',
               'sphinx.ext.napoleon',
-              'sphinxarg.ext']
+              'sphinxarg.ext',
+              'sphinx.ext.intersphinx',
+              'sphinx.ext.autosummary',
+              'sphinx.ext.doctest',
+              'sphinx.ext.todo',
+              'numpydoc',
+              'sphinx.ext.ifconfig',
+              'sphinx.ext.linkcode']
+
+# pngmath / imgmath compatibility layer for different sphinx versions
+import sphinx
+from distutils.version import LooseVersion
+if LooseVersion(sphinx.__version__) < LooseVersion('1.4'):
+    extensions.append('sphinx.ext.pngmath')
+else:
+    extensions.append('sphinx.ext.imgmath')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -101,11 +118,11 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# html_context = {
-#     'css_files': [
-#         '_static/theme_overrides.css',  # override wide tables in RTD theme
-#         ],
-#      }
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+        ],
+    }
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -178,3 +195,25 @@
      author, 'tedana', 'One line description of project.',
      'Miscellaneous'),
 ]
+
+# generate autosummary even if no references
+autosummary_generate = True
+autodoc_default_flags = ['members', 'inherited-members']
+add_module_names = False
+
+# The following is used by sphinx.ext.linkcode to provide links to github
+linkcode_resolve = make_linkcode_resolve('tedana',
+                                         u'https://github.com/me-ica/'
+                                         'tedana/blob/{revision}/'
+                                         '{package}/{path}#L{lineno}')
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'http://docs.python.org/3.5': None,
+    'http://docs.scipy.org/doc/numpy': None,
+    'http://docs.scipy.org/doc/scipy/reference': None,
+    'http://matplotlib.org/': None,
+    'http://scikit-learn.org/0.17': None,
+    'http://nipy.org/nibabel/': None,
+    'http://pandas.pydata.org/pandas-docs/stable/': None,
+}

docs/contributing.rst

@@ -1,9 +1,10 @@
 Contributing to tedana
 ======================
 
-This document explains how to set up a development environment for contributing to tedana
-and code style conventions we follow within the project.
-For a more general guide to the tedana development, please see our `contributing guide`_.
+This document explains how to set up a development environment for contributing
+to tedana and code style conventions we follow within the project.
+For a more general guide to the tedana development, please see our
+`contributing guide`_.
 
 Development in docker_ is encouraged, for the sake of consistency and portability.
 By default, work should be built off of ``emdupre/meica-docker:0.0.3``
@@ -15,6 +16,21 @@ By default, work should be built off of ``emdupre/meica-docker:0.0.3``
 Style Guide
 -----------
 
+Code
+####
+
+Docstrings should follow `numpydoc`_ convention. We encourage extensive
+documentation.
+
+The code itself should follow `PEP8`_ convention as much as possible, with at
+most about 500 lines of code (not including docstrings) per script.
+
+.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
+.. _PEP8: https://www.python.org/dev/peps/pep-0008/
+
+Pull Requests
+#############
+
 We encourage the use of standardized tags for categorizing pull requests.
 When opening a pull request, please use one of the following prefixes:
 

docs/index.rst

@@ -1,7 +1,7 @@
 .. include:: <isonum.txt>
 
 
-tedana: TE Dependent Analysis
+tedana: TE Dependent ANAlysis
 =============================
 
 The ``tedana`` package is part of the ME-ICA pipeline, performing TE-dependent
@@ -18,10 +18,9 @@ Citations
 
 When using tedana, please include the following citations:
 
-Kundu, P., Inati, S.J., Evans, J.W., Luh, W.M. & Bandettini, P.A.
-(2011).
-`Differentiating BOLD and non-BOLD signals in fMRI time series using multi-echo EPI.`_
-*NeuroImage*, *60*, 1759-1770.
+  Kundu, P., Inati, S.J., Evans, J.W., Luh, W.M. & Bandettini, P.A. (2011).
+  `Differentiating BOLD and non-BOLD signals in fMRI time series using multi-echo EPI.`_
+  *NeuroImage*, *60*, 1759-1770.
 
 .. _Differentiating BOLD and non-BOLD signals in fMRI time series using multi-echo EPI.: http://dx.doi.org/10.1016/j.neuroimage.2011.12.028
 
@@ -40,6 +39,7 @@ Copyright |copy| 2011-2017, Prantik Kundu. All rights reserved.
 
    introduction
    installation
+   api
    contributing
    usage
 

docs/installation.rst

@@ -2,12 +2,16 @@ Installation
 ============
 
 We recommend running `containerized versions`_ of ``tedana`` to avoid dependency issues.
-The `Docker Engine`_ appropriate for your system (i.e., linux, Mac OSX, or Windows) is required to access and run the container.
+The `Docker Engine`_ appropriate for your system (i.e., linux, Mac OSX, or
+Windows) is required to access and run the container.
 
 .. _Docker Engine: https://docs.docker.com/engine/installation/
 
-It is also possible to run a local or "bare-metal" ``tedana`` if your system has `AFNI`_ and python 2.7 or 3.4+ installed.
-With a local python installation, we recommend using the `Anaconda`_ or `Miniconda`_ package manager, as these allow for the creation of `virtual environments`_.
+It is also possible to run a local or "bare-metal" ``tedana`` if your system
+has `AFNI`_ and python 2.7 or 3.4+ installed.
+With a local python installation, we recommend using the `Anaconda`_ or
+`Miniconda`_ package manager, as these allow for the creation of
+`virtual environments`_.
 
 .. _AFNI: https://afni.nimh.nih.gov/
 .. _Anaconda: https://docs.continuum.io/anaconda/install/
@@ -20,7 +24,7 @@ Containerized versions
 To access a containerized version of ``tedana`` simply pull the latest Docker image.
 This can be accomplished with the following command:
 
-``docker pull emdupre/meica-docker:0.0.3``
+  ``docker pull emdupre/meica-docker:0.0.3``
 
 Local installation
 ------------------

docs/introduction.rst

@@ -1,8 +1,11 @@
 Introduction
 ============
 
-``tedana`` works by defining components in a BOLD time course via PCA and ICA.
-These components for then analyzed for TE-dependence, as classified as BOLD or non-BOLD.
+``tedana`` works by decomposing multi-echo BOLD data via PCA and ICA.
+These components are then analyzed to determine whether they are TE-dependent
+or -independent. TE-dependent components are classified as BOLD, while
+TE-independent components are classified as non-BOLD, and are discarded as part
+of data cleaning.
 
 Derivatives
 -----------
@@ -11,7 +14,8 @@ Derivatives
     'Denoised' BOLD time series after: basic preprocessing,
     T2* weighted averaging of echoes (i.e. 'optimal combination'),
     ICA denoising.
-    Use this dataset for task analysis and resting state time series correlation analysis.
+    Use this dataset for task analysis and resting state time series correlation
+    analysis.
 * ``tsoc``
     'Raw' BOLD time series dataset after: basic preprocessing
     and T2* weighted averaging of echoes (i.e. 'optimal combination').
@@ -24,4 +28,5 @@ Derivatives
 * ``mefl``
     Component maps (in units of \delta S) of ALL ICA components.
 * ``ctab``
-    Table of component Kappa, Rho, and variance explained values, plus listing of component classifications.
+    Table of component Kappa, Rho, and variance explained values, plus listing
+    of component classifications.