sty+enh: try new style, add more content

Author: mgxd

docs/changes.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGELOG.md

docs/heuristics.rst

@@ -15,9 +15,9 @@ heuristic file, and some useful functions available when making one.
 Components
 ==========
 
----------------------
-`infotodict(seqinfos)`
----------------------
+------------------------
+``infotodict(seqinfos)``
+------------------------
 
 The only required function for a heuristic, `infotodict` is used to both define 
 the conversion outputs and specify the criteria for scan to output association. 
@@ -26,46 +26,46 @@ used for the basis of outputs, as well as a `tuple` of output types. Valid types
 include `nii`, `nii.gz`, and `dicom`.
 
 .. note::
-
-    An example conversion key:
-    ('sub-{subject}/func/sub-{subject}_task-test_run-{item}_bold', ('nii.gz', 'dicom'))
+    An example conversion key
+    
+    ``('sub-{subject}/func/sub-{subject}_task-test_run-{item}_bold', ('nii.gz', 'dicom'))``
 
 
-The `seqinfos` parameter is a list of namedtuples which serves as a grouped and 
+The ``seqinfos`` parameter is a list of namedtuples which serves as a grouped and 
 stacked record of the DICOMs passed in. Each item in `seqinfo` contains DICOM 
 metadata that can be used to isolate the series, and assign it to a conversion 
 key.
 
-A dictionary of {conversion key: seqinfo} is returned.
+A dictionary of {``conversion key``: ``seqinfo``} is returned.
 
--------------------------------
-`create_key(template, outtype)`
--------------------------------
+---------------------------------
+``create_key(template, outtype)``
+---------------------------------
 
-A common helper function used to create the conversion key in `infotodict`. 
+A common helper function used to create the conversion key in ``infotodict``. 
 
-------------------
-`filter_files(fl)`
-------------------
+--------------------
+``filter_files(fl)``
+--------------------
 
 A utility function used to filter any input files.
 
 If this function is included, every file found will go through this filter. Any 
-files where this function returns `True` will be filtered out.
+files where this function returns ``True`` will be filtered out.
 
-------------------------
-`filter_dicom(dcm_data)`
-------------------------
+--------------------------
+``filter_dicom(dcm_data)``
+--------------------------
 
 A utility function used to filter any DICOMs.
 
 If this function is included, every DICOM found will go through this filter. Any 
-DICOMs where this function returns `True` will be filtered out.
+DICOMs where this function returns ``True`` will be filtered out.
 
-----------------------------
-`infotoids(seqinfos, outdir)`
-----------------------------
+-------------------------------
+``infotoids(seqinfos, outdir)``
+-------------------------------
 
-Further processing on `seqinfos` to deduce/customize subject, session, and locator.
+Further processing on ``seqinfos`` to deduce/customize subject, session, and locator.
 
 A dictionary of {"locator": locator, "session": session, "subject": subject} is returned.

docs/index.rst

@@ -12,8 +12,8 @@ Contents
    :maxdepth: 2
 
    installation
-   ../CHANGELOG
+   changes
    usage
    heuristics
    tutorials
-   API
+   api

docs/installation.rst

@@ -7,32 +7,32 @@ Installation
 
 Local
 =====
-Released versions of HeuDiConv are available on `PyPI <https://pypi.org/project/heudiconv/>`_
- and `conda <https://github.com/conda-forge/heudiconv-feedstock#installing-heudiconv>`_.
- If installing through ``PyPI``, eg::
+Released versions of HeuDiConv are available on `PyPI <https://pypi.org/project/heudiconv/>`_ 
+and `conda <https://github.com/conda-forge/heudiconv-feedstock#installing-heudiconv>`_. 
+If installing through ``PyPI``, eg::
 
     pip install heudiconv[all]
 
-Manual installation of `dcm2niix <https://github.com/rordenlab/dcm2niix#install>`_
- is required.
+Manual installation of `dcm2niix <https://github.com/rordenlab/dcm2niix#install>`_ 
+is required.
 
- On Debian-based systems we recommend using `NeuroDebian <http://neuro.debian.net>`_
- which provides the `heudiconv package <http://neuro.debian.net/pkgs/heudiconv.html>`_.
+On Debian-based systems we recommend using `NeuroDebian <http://neuro.debian.net>`_ 
+which provides the `heudiconv package <http://neuro.debian.net/pkgs/heudiconv.html>`_.
 
 
 Docker
 ======
-If `Docker <https://docs.docker.com/install/>`_ is available on your system, you
- can visit `our page on Docker Hub <https://hub.docker.com/r/nipy/heudiconv/tags>`_
- to view available releases. To pull the latest release, run::
+If `Docker <https://docs.docker.com/install/>`_ is available on your system, you 
+can visit `our page on Docker Hub <https://hub.docker.com/r/nipy/heudiconv/tags>`_ 
+to view available releases. To pull the latest release, run::
 
     $ docker pull nipy/heudiconv:0.5.4
 
 
 Singularity
 ===========
-If `Singularity <https://www.sylabs.io/singularity/>`_ is available on your system,
- you can use it to pull and convert our Docker images! For example, to pull and
- build the latest release, you can run::
+If `Singularity <https://www.sylabs.io/singularity/>`_ is available on your system, 
+you can use it to pull and convert our Docker images! For example, to pull and 
+build the latest release, you can run::
 
     $ singularity pull docker://nipy/heudiconv:0.5.4

docs/tutorials.rst

@@ -5,18 +5,14 @@ User Tutorials
 Luckily(?), we live in an era of plentiful information. Below are some links to
 other users' tutorials covering their experience with ``heudiconv``.
 
-- `YouTube tutorial <https://www.youtube.com/watch?v=O1kZAuR7E00>`_ by 
-`James Kent <https://github.com/jdkent>`_.
+- `YouTube tutorial <https://www.youtube.com/watch?v=O1kZAuR7E00>`_ by `James Kent <https://github.com/jdkent>`_.
 
-- `Walkthrough <http://reproducibility.stanford.edu/bids-tutorial-series-part-2a/>`_ 
-by the `Standard Center for Reproducible Neuroscience <http://reproducibility.stanford.edu/>`_.
+- `Walkthrough <http://reproducibility.stanford.edu/bids-tutorial-series-part-2a/>`_ by the `Standard Center for Reproducible Neuroscience <http://reproducibility.stanford.edu/>`_.
 
-- `U of A Neuroimaging Core <https://neuroimaging-core-docs.readthedocs.io/en/latest/pages/heudiconv.html>`_ 
-by `Dianne Patterson <https://github.com/dkp>`_.
+- `U of A Neuroimaging Core <https://neuroimaging-core-docs.readthedocs.io/en/latest/pages/heudiconv.html>`_ by `Dianne Patterson <https://github.com/dkp>`_.
 
 - `Sample Conversion: Coastal Coding 2019 <http://www.repronim.org/coco2019-training/presentations/heudiconv/#1>`_.
 
-.. note::
-
-    Keep in mind, some of these tutorials may not be 100% up to date with 
+.. caution::
+    Some of these tutorials may not be up to date with 
     the latest releases of ``heudiconv``.

docs/usage.rst

@@ -1,4 +1,44 @@
-## How it works (in some more detail)
+=====
+Usage
+=====
+
+``heudiconv`` processes DICOM files and converts the output into user defined 
+paths.
+
+CommandLine Arguments
+======================
+
+.. argparse::
+   :ref: heudiconv.cli.run.get_parser
+   :prog: heudiconv
+   :nodefault:
+   :nodefaultconst:
+   
+
+Support
+=======
+
+All bugs, concerns and enhancement requests for this software can be submitted here:
+https://github.com/nipy/heudiconv/issues.
+
+If you have a problem or would like to ask a question about how to use ``heudiconv``,
+please submit a question to `NeuroStars.org <http://neurostars.org/tags/heudiconv>`_ with a ``heudiconv`` tag.
+NeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.
+
+All previous ``heudiconv`` questions are available here:
+http://neurostars.org/tags/heudiconv/
+
+
+Batch example
+=============
+
+``heudiconv`` can greatly facilitate large scale conversions
+
+
+*******************************************************************************************
+*******************************************************************************************
+*******************************************************************************************
+*******************************************************************************************
 
 Call `heudiconv` like this: