docs: revise docstrings, add changes [docs versions]

Author: oesteban

docs/index.rst

@@ -10,3 +10,7 @@ Contents
     :maxdepth: 3
 
     api/templateflow
+
+What's new
+----------
+.. include:: ../CHANGES.rst

templateflow/__about__.py

@@ -1,8 +1,6 @@
 # emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
 # vi: set ft=python sts=4 ts=4 sw=4 et:
-"""
-Templateflow
-"""
+"""Versioning and other metadata about TemplateFlow."""
 from ._version import get_versions
 __version__ = get_versions()['version']
 del get_versions

templateflow/__init__.py

@@ -1,9 +1,6 @@
 # emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
 # vi: set ft=python sts=4 ts=4 sw=4 et:
-"""
-The Zone of Templates
-=====================
-"""
+"""TemplateFlow is the Zone of Templates."""
 from .__about__ import __version__, __copyright__, __credits__
 
 __packagename__ = 'templateflow'

templateflow/api.py

@@ -8,8 +8,26 @@
 
 def get(template, **kwargs):
     """
-    Fetch one file from one template
-
+    Fetch one file from one particular template.
+
+    Parameters
+    ----------
+    template : str
+        A template identifier (e.g., ``MNI152NLin2009cAsym``).
+
+    Keyword Arguments
+    -----------------
+    resolution: int or None
+        Index to an specific spatial resolution of the template.
+    suffix : str or None
+        BIDS suffix
+    atlas : str
+        Name of a particular atlas
+    desc : str
+        Description field
+
+    Examples
+    --------
     >>> str(get('MNI152Lin', resolution=1, suffix='T1w'))  # doctest: +ELLIPSIS
     '.../tpl-MNI152Lin/tpl-MNI152Lin_res-01_T1w.nii.gz'
 
@@ -66,8 +84,21 @@ def get(template, **kwargs):
 
 def templates(**kwargs):
     """
-    Returns a list of available templates
-
+    Returns a list of available templates.
+
+    Keyword Arguments
+    -----------------
+    resolution: int or None
+        Index to an specific spatial resolution of the template.
+    suffix : str or None
+        BIDS suffix
+    atlas : str
+        Name of a particular atlas
+    desc : str
+        Description field
+
+    Examples
+    --------
     >>> base = ['MNI152Lin', 'MNI152NLin2009cAsym', 'NKI', 'OASIS30ANTs']
     >>> tpls = templates()
     >>> all([t in tpls for t in base])
@@ -82,8 +113,15 @@ def templates(**kwargs):
 
 def get_metadata(template):
     """
-    Fetch one file from one template
+    Fetch one file from one template.
+
+    Parameters
+    ----------
+    template : str
+        A template identifier (e.g., ``MNI152NLin2009cAsym``).
 
+    Examples
+    --------
     >>> get_metadata('MNI152Lin')['Name']
     'Linear ICBM Average Brain (ICBM152) Stereotaxic Registration Model'
 

templateflow/conf/__init__.py

@@ -1,6 +1,4 @@
-"""
-Settings
-"""
+"""Configuration and settings."""
 from os import getenv
 from warnings import warn
 from pathlib import Path

templateflow/conf/bids.py

@@ -1,6 +1,4 @@
-"""
-Extending pyBIDS
-"""
+"""Extending pyBIDS for querying TemplateFlow."""
 from pkg_resources import resource_filename
 from bids.layout import BIDSLayout, add_config_paths