Merge branch 'doc-pre-release' into main-master

* doc-pre-release: (32 commits)
  RF: use long_description for README.rst
  DOC: proof reading corrections for nifti images
  DOC: fix see also sections for get/set q/s form
  DOC: correct form of Raises section
  DOC: clean up class and some function docstrings
  DOC: small rewrites / fix broken link
  DOC: warn about pending deprecation of data pkgs
  DOC: move image signature discussion up a level
  DOC: move / rewrite spm usecases doc
  DOC: remove filenames usecase document
  DOC: move io implementation doc to old stuff
  DOC: update data pkg doc for implementation
  RF: install sphinx in tests block
  DOC: document adding an image format
  DOC: page on adding / using test data
  DOC: add neuro / radio doc to tutorials
  RF: always close figures before plot directive
  DOC: add image orientation page
  DOC: add tutorials section
  DOC: add document on nifti format
  ...

Conflicts:
	README.rst

Author: matthew-brett

.travis.yml

@@ -26,6 +26,10 @@ matrix:
     - python: 2.7
       env:
         - DEPENDS="numpy==1.5.1 pydicom==0.9.7"
+    # Documentation doctests
+    - python: 2.7
+      env:
+        - DOC_DOC_TEST=1
 before_install:
     - virtualenv --python=python venv
     - source venv/bin/activate
@@ -59,6 +63,13 @@ script:
       cp ../.coveragerc .;
       COVER_ARGS="--with-coverage --cover-package nibabel";
       fi
-    - nosetests --with-doctest $COVER_ARGS nibabel
+    - if [ "$DOC_DOC_TEST" == "1" ]; then
+      pip install sphinx;
+      cd ../doc;
+      make html;
+      make doctest;
+      else
+      nosetests --with-doctest $COVER_ARGS nibabel;
+      fi
 after_success:
     - if [ "${COVERAGE}" == "1" ]; then coveralls; fi

Changelog

@@ -9,10 +9,6 @@ NiBabel Development Changelog
 NiBabel is the successor to the much-loved PyNifti package. Here we list the
 releases for both packages.
 
-'Close gh-' statements refer to GitHub issues that are available at::
-
-  http://github.com/nipy/nibabel/issues
-
 The full VCS changelog is available here:
 
   http://github.com/nipy/nibabel/commits/master
@@ -23,8 +19,8 @@ Releases
 NiBabel
 +++++++
 
-Most work on NiBabel so far has been by Matthew Brett (MB) and Michael Hanke
-(MH) and Stephan Gerhard (SG).
+Most work on NiBabel so far has been by Matthew Brett (MB), Michael Hanke (MH)
+and Stephan Gerhard (SG).
 
 * 2.0.0 (soon)
 
@@ -33,30 +29,35 @@ Most work on NiBabel so far has been by Matthew Brett (MB) and Michael Hanke
 
   * New feature, bugfix release with minor API breakage;
   * Minor API breakage: default write of NIfTI / Analyze image data offset
-    value changed from keeping the value as read from file, to shrinking the
-    offset the minimum necessary to make room for the header and any
-    extensions;
-  * Minor API breakage: data scaling in NIfTI / Analyze now set to NaN when
-    reading images.  To read the original data scaling you need to look at the
-    ``slope`` and ``inter`` properties of the image ``dataobj`` attribute;
-  * Minor API breakage: image data offset in NIfTI / Analyze now set to zero
-    when reading images.  TO read the original data offset use the ``offset``
+    value. The data offset is the number of bytes from the beginning of file
+    to skip before reading the image data.  Nibabel behavior changed from
+    keeping the value as read from file, to setting the offset to zero on
+    read, and setting the offset when writing the header. The value of the
+    offset will now be the minimum value necessary to make room for the header
+    and any extensions when writing the file. You can override the default
+    offset by setting value explicitly to some value other than zero. To read
+    the original data offset as read from the header, use the ``offset``
     property of the image ``dataobj`` attribute;
+  * Minor API breakage: data scaling in NIfTI / Analyze now set to NaN when
+    reading images.  Data scaling refers to the data intercept and slope
+    values in the NIfTI / Analyze header.  To read the original data scaling
+    you need to look at the ``slope`` and ``inter`` properties of the image
+    ``dataobj`` attribute.  You can set scaling explicitly by setting the
+    slope and intercept values in the header to values other than NaN;
   * New API for managing image caching; images have an ``in_memory`` property
     that is true if the image data has been loaded into cache, or is already
     an array in memory; ``get_data`` has new keyword argument ``caching`` to
     specify whether the cache should be filled by ``get_data``;
-  * Images now have properties ``dataobj``, ``affine``, ``header``; we will
+  * Images now have properties ``dataobj``, ``affine``, ``header``. We will
     slowly phase out the ``get_affine`` and ``get_header`` image methods;
   * The image ``dataobj`` can be sliced using an efficient algorithm to avoid
-    reading unneccesary data from disk.  This makes it possible to do very
+    reading unnecessary data from disk.  This makes it possible to do very
     efficient reads of single volumes from a time series;
-  * You can now set NIfTI / Analyze data scaling explicitly to force this
-    scaling to be written into the header;
   * NIfTI2 read / write support;
   * Read support for MINC2;
-  * Much extended read support for PAR / REC, largely due to the work of Eric
-    Larson and Gregory R. Lee giving new code, advice and code review;
+  * Much extended read support for PAR / REC, largely due to work from Eric
+    Larson and Gregory R. Lee on new code, advice and code review. Thanks also
+    to Jeff Stevenson and Bennett Landman for helpful discussion;
   * ``parrec2nii`` script outputs images in LAS voxel orientation, which
     appears to be necessary for compatibility with FSL ``dtifit`` /
     ``fslview`` diffusion analysis pipeline;
@@ -65,19 +66,19 @@ Most work on NiBabel so far has been by Matthew Brett (MB) and Michael Hanke
   * New function to save Freesurfer annotation files (by Github user ohinds);
   * Method to return MGH format ``vox2ras_tkr`` affine (Eric Larson);
   * A new API for reading unscaled data from NIfTI and other images, using
-    ``img.dataobj.get_unscaled()``; deprecate previous way of doing this with
-    ``read_img_data`` function;
-  * Bug fix replacing NaN values with zero when writing floating point data as
-    integers.  If the input floating point data range did not include zero,
-    then NaN would not get written to a value corresponding to zero in the
-    output;
+    ``img.dataobj.get_unscaled()``. Deprecate previous way of doing this,
+    which was to read data with the ``read_img_data`` function;
+  * Fix for bug when replacing NaN values with zero when writing floating
+    point data as integers.  If the input floating point data range did not
+    include zero, then NaN would not get written to a value corresponding to
+    zero in the output;
   * Improvements and bug fixes to image orientation calculation and DICOM
     wrappers by Brendan Moloney;
-  * Bug fix writing GIfTI files with base64 encoding that didn't match the
-    spec, and the wrong field name for the endian code. Thanks to Basile
-    Pinsard and Russ Poldrack for diagnosis and fixes;
-  * Bug fix in freesurfer.read_annot with orig_ids=False when annot contains
-    vertices with no label (Alexandre Gramfort);
+  * Bug fixes writing GIfTI files. We were using a base64 encoding that didn't
+    match the spec, and the wrong field name for the endian code. Thanks to
+    Basile Pinsard and Russ Poldrack for diagnosis and fixes;
+  * Bug fix in ``freesurfer.read_annot`` with ``orig_ids=False`` when annot
+    contains vertices with no label (Alexandre Gramfort);
   * More tutorials in the documentation, including introductory tutorial on
     DICOM, and on coordinate systems;
   * Lots of code refactoring, including moving to common code-base for Python

Makefile

@@ -281,5 +281,8 @@ tox-stale:
 	# installed)
 	tox -e python25,python26,python27,python32,np-1.2.1
 
+refresh-readme:
+	$(PYTHON) tools/refresh_readme.py
+
 .PHONY: orig-src pylint
 

README.rst

@@ -1,11 +1,10 @@
 .. -*- rest -*-
-.. vim:syntax=rest
+.. vim:syntax=rst
 
-|Coveralls|_
-
-.. |Coveralls| image:: https://coveralls.io/repos/nipy/nibabel/badge.png?branch=master
-.. _Coveralls: https://coveralls.io/r/nipy/nibabel?branch=master
+.. image:: https://coveralls.io/repos/nipy/nibabel/badge.png?branch=master
+    :target: https://coveralls.io/r/nipy/nibabel?branch=master
 
+.. Following contents should be from LONG_DESCRIPTION in nibabel/info.py
 
 =======
 NiBabel

doc/Makefile

@@ -43,12 +43,14 @@ api-stamp:
 	@echo "Build API docs...done."
 	@touch $@
 
-html: api-stamp
+html-only:
 	mkdir -p $(BUILDROOT)/html $(BUILDROOT)/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDROOT)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDROOT)/html."
 
+html: api-stamp html-only
+
 pickle:
 	mkdir -p $(BUILDROOT)/pickle $(BUILDROOT)/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDROOT)/pickle
@@ -87,7 +89,7 @@ linkcheck:
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDROOT)/linkcheck/output.txt."
 
-doctest:
+doctest: api-clean
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDROOT)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in _build/doctest/output.txt."

doc/downloads

@@ -0,0 +1 @@
+source/downloads

doc/source/.gitattributes

@@ -0,0 +1 @@
+*.rst  diff merge crlf

doc/source/.gitignore

@@ -0,0 +1 @@
+_long_description.inc

doc/source/conf.py

@@ -34,6 +34,10 @@
 rel = {}
 execfile('../../nibabel/info.py', rel)
 
+# Write long description from info
+with open('_long_description.inc', 'wt') as fobj:
+    fobj.write(rel['LONG_DESCRIPTION'])
+
 # 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.ext.autodoc',

doc/source/coordinate_systems.rst

@@ -60,13 +60,6 @@ the array.
 We collected an anatomical image in the same session.  We can load that image
 and look at slices in the three axes:
 
-.. plot::
-    :nofigs:
-    :include-source: false
-
-    # This guy just closes the previous figure so we don't get it twice
-    plt.close('all')
-
 .. plot::
     :context: