DOC: README update

README.rst

@@ -1,110 +1,149 @@
 .. -*- rest -*-
 .. vim:syntax=rst
 
-.. image:: https://codecov.io/gh/nipy/nibabel/branch/master/graph/badge.svg
-  :target: https://codecov.io/gh/nipy/nibabel
-
-.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.591597.svg
-   :target: https://doi.org/10.5281/zenodo.591597
-
-.. image:: https://repology.org/badge/version-for-repo/aur/python:nibabel.svg?header=Arch%20%28%41%55%52%29
-   :target: https://repology.org/project/python:nibabel/versions
-   :alt: Arch (AUR)
-
-.. image:: https://repology.org/badge/version-for-repo/debian_unstable/nibabel.svg?header=Debian%20Unstable
-   :target: https://repology.org/project/nibabel/versions
-   :alt: Debian Unstable package
-
-.. image:: https://repology.org/badge/version-for-repo/gentoo_ovl_science/nibabel.svg?header=Gentoo%20%28%3A%3Ascience%29
-   :target: https://repology.org/project/nibabel/versions
-   :alt: Gentoo (::science)
-
-.. image:: https://repology.org/badge/version-for-repo/nix_unstable/python:nibabel.svg?header=nixpkgs%20unstable
-   :target: https://repology.org/project/python:nibabel/versions
-   :alt: nixpkgs unstable
-
-.. Following contents should be from LONG_DESCRIPTION in nibabel/info.py
-
-
-=======
-NiBabel
-=======
-
-Read / write access to some common neuroimaging file formats
-
-This package provides read +/- write access to some common medical and
-neuroimaging file formats, including: ANALYZE_ (plain, SPM99, SPM2 and later),
-GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_, MINC1_, MINC2_, `AFNI BRIK/HEAD`_, MGH_ and
-ECAT_ as well as Philips PAR/REC.  We can read and write FreeSurfer_ geometry,
-annotation and morphometry files.  There is some very limited support for
-DICOM_.  NiBabel is the successor of PyNIfTI_.
-
-.. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
+.. image:: doc/pics/logo.png
+   :target: https://nipy.org/nibabel
+   :alt: NiBabel logo
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 0
+
+   * - Code
+     -
+      .. image:: https://img.shields.io/pypi/pyversions/nibabel.svg
+         :target: https://pypi.python.org/pypi/nibabel/
+         :alt: PyPI - Python Version
+      .. image:: https://img.shields.io/badge/code%20style-blue-blue.svg
+         :target: https://blue.readthedocs.io/en/latest/
+         :alt: code style: blue
+      .. image:: https://img.shields.io/badge/imports-isort-1674b1
+         :target: https://pycqa.github.io/isort/
+         :alt: imports: isort
+      .. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
+         :target: https://github.com/pre-commit/pre-commit
+         :alt: pre-commit
+
+   * - Tests
+     -
+      .. image:: https://github.com/nipy/NiBabel/actions/workflows/stable.yml/badge.svg
+         :target: https://github.com/nipy/NiBabel/actions/workflows/stable.yml
+         :alt: stable tests
+      .. image:: https://codecov.io/gh/nipy/NiBabel/branch/master/graph/badge.svg
+         :target: https://codecov.io/gh/nipy/NiBabel
+         :alt: codecov badge
+
+   * - PyPI
+     -
+      .. image:: https://img.shields.io/pypi/v/nibabel.svg
+         :target: https://pypi.python.org/pypi/nibabel/
+         :alt: PyPI version
+      .. image:: https://img.shields.io/pypi/dm/nibabel.svg
+         :target: https://pypistats.org/packages/nibabel
+         :alt: PyPI - Downloads
+
+   * - Packages
+     -
+      .. image:: https://img.shields.io/conda/vn/conda-forge/nibabel
+         :target: https://anaconda.org/conda-forge/nibabel
+         :alt: Conda package
+      .. image:: https://repology.org/badge/version-for-repo/debian_unstable/nibabel.svg?header=Debian%20Unstable
+         :target: https://repology.org/project/nibabel/versions
+         :alt: Debian Unstable package
+      .. image:: https://repology.org/badge/version-for-repo/aur/python:nibabel.svg?header=Arch%20%28%41%55%52%29
+         :target: https://repology.org/project/python:nibabel/versions
+         :alt: Arch (AUR)
+      .. image:: https://repology.org/badge/version-for-repo/gentoo_ovl_science/nibabel.svg?header=Gentoo%20%28%3A%3Ascience%29
+         :target: https://repology.org/project/nibabel/versions
+         :alt: Gentoo (::science)
+      .. image:: https://repology.org/badge/version-for-repo/nix_unstable/python:nibabel.svg?header=nixpkgs%20unstable
+         :target: https://repology.org/project/python:nibabel/versions
+         :alt: nixpkgs unstable
+
+   * - License & DOI
+     -
+      .. image:: https://img.shields.io/pypi/l/nibabel.svg
+         :target: https://github.com/nipy/nibabel/blob/master/COPYING
+         :alt: License
+      .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.591597.svg
+         :target: https://doi.org/10.5281/zenodo.591597
+         :alt: Zenodo DOI
+
+.. Following contents should be copied from LONG_DESCRIPTION in nibabel/info.py
+
+
+Read and write access to common neuroimaging file formats, including:
+ANALYZE_ (plain, SPM99, SPM2 and later), GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_,
+MINC1_, MINC2_, `AFNI BRIK/HEAD`_, ECAT_ and Philips PAR/REC.
+In addition, NiBabel also supports FreeSurfer_'s MGH_, geometry, annotation and
+morphometry files, and provides some limited support for DICOM_.
+
+NiBabel's API gives full or selective access to header information (metadata),
+and image data is made available via NumPy arrays. For more information, see
+NiBabel's `documentation site`_ and `API reference`_.
+
+.. _API reference: https://nipy.org/nibabel/api.html
 .. _AFNI BRIK/HEAD: https://afni.nimh.nih.gov/pub/dist/src/README.attributes
-.. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
-.. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
+.. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
 .. _CIFTI-2: https://www.nitrc.org/projects/cifti/
+.. _DICOM: http://medical.nema.org/
+.. _documentation site: http://nipy.org/nibabel
+.. _ECAT: http://xmedcon.sourceforge.net/Docs/Ecat
+.. _Freesurfer: https://surfer.nmr.mgh.harvard.edu
+.. _GIFTI: https://www.nitrc.org/projects/gifti
+.. _MGH: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat
 .. _MINC1:
     https://en.wikibooks.org/wiki/MINC/Reference/MINC1_File_Format_Reference
 .. _MINC2:
     https://en.wikibooks.org/wiki/MINC/Reference/MINC2.0_File_Format_Reference
-.. _PyNIfTI: http://niftilib.sourceforge.net/pynifti/
-.. _GIFTI: https://www.nitrc.org/projects/gifti
-.. _MGH: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat
-.. _ECAT: http://xmedcon.sourceforge.net/Docs/Ecat
-.. _Freesurfer: https://surfer.nmr.mgh.harvard.edu
-.. _DICOM: http://medical.nema.org/
+.. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
+.. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
 
-The various image format classes give full or selective access to header
-(meta) information and access to the image data is made available via NumPy
-arrays.
+Installation
+============
 
-Website
-=======
+To install NiBabel's `current release`_ with ``pip``, run::
 
-Current documentation on nibabel can always be found at the `NIPY nibabel
-website <http://nipy.org/nibabel>`_.
+   pip install nibabel
 
-Mailing Lists
-=============
+To install the latest development version, run::
 
-Please send any questions or suggestions to the `neuroimaging mailing list
-<https://mail.python.org/mailman/listinfo/neuroimaging>`_.
+   pip install git+https://github.com/nipy/nibabel
 
-Code
-====
+When working on NiBabel itself, it may be useful to install in "editable" mode::
 
-Install nibabel with::
+   git clone https://github.com/nipy/nibabel.git
+   pip install -e ./nibabel
 
-    pip install nibabel
+For more information on previous releases, see the `release archive`_ or
+`development changelog`_.
 
-You may also be interested in:
+.. _current release: https://pypi.python.org/pypi/NiBabel
+.. _release archive: https://github.com/nipy/NiBabel/releases
+.. _development changelog: https://nipy.org/nibabel/changelog.html
 
-* the `nibabel code repository`_ on Github;
-* documentation_ for all releases and current development tree;
-* download the `current release`_ from pypi;
-* download `current development version`_ as a zip file;
-* downloads of all `available releases`_.
+Mailing List
+============
 
-.. _nibabel code repository: https://github.com/nipy/nibabel
-.. _Documentation: http://nipy.org/nibabel
-.. _current release: https://pypi.python.org/pypi/nibabel
-.. _current development version: https://github.com/nipy/nibabel/archive/master.zip
-.. _available releases: https://github.com/nipy/nibabel/releases
+Please send any questions or suggestions to the `neuroimaging mailing list
+<https://mail.python.org/mailman/listinfo/neuroimaging>`_.
 
 License
 =======
 
-Nibabel is licensed under the terms of the MIT license. Some code included
-with nibabel is licensed under the BSD license.  Please see the COPYING file
-in the nibabel distribution.
+NiBabel is licensed under the terms of the `MIT license
+<https://github.com/nipy/nibabel/blob/master/COPYING#nibabel>`__.
+Some code included with NiBabel is licensed under the `BSD license`_.
+For more information, please see the COPYING_ file.
 
-Citing nibabel
-==============
+.. _BSD license: https://opensource.org/licenses/BSD-3-Clause
+.. _COPYING: https://github.com/nipy/nibabel/blob/master/COPYING
 
-Please see the `available releases`_ for the release of nibabel that you are
-using.  Recent releases have a Zenodo_ `Digital Object Identifier`_ badge at
-the top of the release notes.  Click on the badge for more information.
+Citation
+========
+
+NiBabel releases have a Zenodo_ `Digital Object Identifier`_ (DOI) badge at
+the top of the release notes. Click on the badge for more information.
 
-.. _zenodo: https://zenodo.org
 .. _Digital Object Identifier: https://en.wikipedia.org/wiki/Digital_object_identifier
+.. _zenodo: https://zenodo.org

doc/source/index.rst

@@ -7,6 +7,10 @@
   #
   ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ###
 
+=======
+NiBabel
+=======
+
 .. include:: _long_description.inc
 
 Documentation

nibabel/info.py

@@ -1,7 +1,7 @@
-"""Define distribution parameters for nibabel, including package version
+"""Define static nibabel metadata for nibabel
 
-The long description parameter is used to fill settings in setup.py, the
-nibabel top-level docstring, and in building the docs.
+The long description parameter is used in the nibabel top-level docstring,
+and in building the docs.
 We exec this file in several places, so it cannot import nibabel or use
 relative imports.
 """
@@ -12,86 +12,79 @@
 # We also include this text in the docs by ``..include::`` in
 # ``docs/source/index.rst``.
 long_description = """
-=======
-NiBabel
-=======
+Read and write access to common neuroimaging file formats, including:
+ANALYZE_ (plain, SPM99, SPM2 and later), GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_,
+MINC1_, MINC2_, `AFNI BRIK/HEAD`_, ECAT_ and Philips PAR/REC.
+In addition, NiBabel also supports FreeSurfer_'s MGH_, geometry, annotation and
+morphometry files, and provides some limited support for DICOM_.
 
-Read / write access to some common neuroimaging file formats
+NiBabel's API gives full or selective access to header information (metadata),
+and image data is made available via NumPy arrays. For more information, see
+NiBabel's `documentation site`_ and `API reference`_.
 
-This package provides read +/- write access to some common medical and
-neuroimaging file formats, including: ANALYZE_ (plain, SPM99, SPM2 and later),
-GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_, MINC1_, MINC2_, `AFNI BRIK/HEAD`_, MGH_ and
-ECAT_ as well as Philips PAR/REC.  We can read and write FreeSurfer_ geometry,
-annotation and morphometry files.  There is some very limited support for
-DICOM_.  NiBabel is the successor of PyNIfTI_.
-
-.. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
+.. _API reference: https://nipy.org/nibabel/api.html
 .. _AFNI BRIK/HEAD: https://afni.nimh.nih.gov/pub/dist/src/README.attributes
-.. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
-.. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
+.. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
 .. _CIFTI-2: https://www.nitrc.org/projects/cifti/
+.. _DICOM: http://medical.nema.org/
+.. _documentation site: http://nipy.org/nibabel
+.. _ECAT: http://xmedcon.sourceforge.net/Docs/Ecat
+.. _Freesurfer: https://surfer.nmr.mgh.harvard.edu
+.. _GIFTI: https://www.nitrc.org/projects/gifti
+.. _MGH: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat
 .. _MINC1:
     https://en.wikibooks.org/wiki/MINC/Reference/MINC1_File_Format_Reference
 .. _MINC2:
     https://en.wikibooks.org/wiki/MINC/Reference/MINC2.0_File_Format_Reference
-.. _PyNIfTI: http://niftilib.sourceforge.net/pynifti/
-.. _GIFTI: https://www.nitrc.org/projects/gifti
-.. _MGH: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat
-.. _ECAT: http://xmedcon.sourceforge.net/Docs/Ecat
-.. _Freesurfer: https://surfer.nmr.mgh.harvard.edu
-.. _DICOM: http://medical.nema.org/
+.. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
+.. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
 
-The various image format classes give full or selective access to header
-(meta) information and access to the image data is made available via NumPy
-arrays.
+Installation
+============
 
-Website
-=======
+To install NiBabel's `current release`_ with ``pip``, run::
 
-Current documentation on nibabel can always be found at the `NIPY nibabel
-website <http://nipy.org/nibabel>`_.
+   pip install nibabel
 
-Mailing Lists
-=============
+To install the latest development version, run::
 
-Please send any questions or suggestions to the `neuroimaging mailing list
-<https://mail.python.org/mailman/listinfo/neuroimaging>`_.
+   pip install git+https://github.com/nipy/nibabel
 
-Code
-====
+When working on NiBabel itself, it may be useful to install in "editable" mode::
 
-Install nibabel with::
+   git clone https://github.com/nipy/nibabel.git
+   pip install -e ./nibabel
 
-    pip install nibabel
+For more information on previous releases, see the `release archive`_ or
+`development changelog`_.
 
-You may also be interested in:
+.. _current release: https://pypi.python.org/pypi/NiBabel
+.. _release archive: https://github.com/nipy/NiBabel/releases
+.. _development changelog: https://nipy.org/nibabel/changelog.html
 
-* the `nibabel code repository`_ on Github;
-* documentation_ for all releases and current development tree;
-* download the `current release`_ from pypi;
-* download `current development version`_ as a zip file;
-* downloads of all `available releases`_.
+Mailing List
+============
 
-.. _nibabel code repository: https://github.com/nipy/nibabel
-.. _Documentation: http://nipy.org/nibabel
-.. _current release: https://pypi.python.org/pypi/nibabel
-.. _current development version: https://github.com/nipy/nibabel/archive/master.zip
-.. _available releases: https://github.com/nipy/nibabel/releases
+Please send any questions or suggestions to the `neuroimaging mailing list
+<https://mail.python.org/mailman/listinfo/neuroimaging>`_.
 
 License
 =======
 
-Nibabel is licensed under the terms of the MIT license. Some code included
-with nibabel is licensed under the BSD license.  Please see the COPYING file
-in the nibabel distribution.
+NiBabel is licensed under the terms of the `MIT license
+<https://github.com/nipy/nibabel/blob/master/COPYING#nibabel>`__.
+Some code included with NiBabel is licensed under the `BSD license`_.
+For more information, please see the COPYING_ file.
 
-Citing nibabel
-==============
+.. _BSD license: https://opensource.org/licenses/BSD-3-Clause
+.. _COPYING: https://github.com/nipy/nibabel/blob/master/COPYING
 
-Please see the `available releases`_ for the release of nibabel that you are
-using.  Recent releases have a Zenodo_ `Digital Object Identifier`_ badge at
-the top of the release notes.  Click on the badge for more information.
+Citation
+========
+
+NiBabel releases have a Zenodo_ `Digital Object Identifier`_ (DOI) badge at
+the top of the release notes. Click on the badge for more information.
 
-.. _zenodo: https://zenodo.org
 .. _Digital Object Identifier: https://en.wikipedia.org/wiki/Digital_object_identifier
-"""
+.. _zenodo: https://zenodo.org
+"""   # noqa: E501