Skip to content

Commit 3f1c6f9

Browse files
ZviBaratzZviBaratz
authored
Merge pull request #1195 from ZviBaratz/doc/readme
DOC: README update
2 parents 504776c + 6d1fd30 commit 3f1c6f9

File tree

4 files changed

+177
-141
lines changed

4 files changed

+177
-141
lines changed

‎README.rst

+121-82
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,149 @@
11
.. -*- rest -*-
22
.. vim:syntax=rst
33
4-
.. image:: https://codecov.io/gh/nipy/nibabel/branch/master/graph/badge.svg
5-
:target: https://codecov.io/gh/nipy/nibabel
6-
7-
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.591597.svg
8-
:target: https://doi.org/10.5281/zenodo.591597
9-
10-
.. image:: https://repology.org/badge/version-for-repo/aur/python:nibabel.svg?header=Arch%20%28%41%55%52%29
11-
:target: https://repology.org/project/python:nibabel/versions
12-
:alt: Arch (AUR)
13-
14-
.. image:: https://repology.org/badge/version-for-repo/debian_unstable/nibabel.svg?header=Debian%20Unstable
15-
:target: https://repology.org/project/nibabel/versions
16-
:alt: Debian Unstable package
17-
18-
.. image:: https://repology.org/badge/version-for-repo/gentoo_ovl_science/nibabel.svg?header=Gentoo%20%28%3A%3Ascience%29
19-
:target: https://repology.org/project/nibabel/versions
20-
:alt: Gentoo (::science)
21-
22-
.. image:: https://repology.org/badge/version-for-repo/nix_unstable/python:nibabel.svg?header=nixpkgs%20unstable
23-
:target: https://repology.org/project/python:nibabel/versions
24-
:alt: nixpkgs unstable
25-
26-
.. Following contents should be from LONG_DESCRIPTION in nibabel/info.py
27-
28-
29-
=======
30-
NiBabel
31-
=======
32-
33-
Read / write access to some common neuroimaging file formats
34-
35-
This package provides read +/- write access to some common medical and
36-
neuroimaging file formats, including: ANALYZE_ (plain, SPM99, SPM2 and later),
37-
GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_, MINC1_, MINC2_, `AFNI BRIK/HEAD`_, MGH_ and
38-
ECAT_ as well as Philips PAR/REC. We can read and write FreeSurfer_ geometry,
39-
annotation and morphometry files. There is some very limited support for
40-
DICOM_. NiBabel is the successor of PyNIfTI_.
41-
42-
.. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
4+
.. image:: doc/pics/logo.png
5+
:target: https://nipy.org/nibabel
6+
:alt: NiBabel logo
7+
8+
.. list-table::
9+
:widths: 20 80
10+
:header-rows: 0
11+
12+
* - Code
13+
-
14+
.. image:: https://img.shields.io/pypi/pyversions/nibabel.svg
15+
:target: https://pypi.python.org/pypi/nibabel/
16+
:alt: PyPI - Python Version
17+
.. image:: https://img.shields.io/badge/code%20style-blue-blue.svg
18+
:target: https://blue.readthedocs.io/en/latest/
19+
:alt: code style: blue
20+
.. image:: https://img.shields.io/badge/imports-isort-1674b1
21+
:target: https://pycqa.github.io/isort/
22+
:alt: imports: isort
23+
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
24+
:target: https://github.com/pre-commit/pre-commit
25+
:alt: pre-commit
26+
27+
* - Tests
28+
-
29+
.. image:: https://github.com/nipy/NiBabel/actions/workflows/stable.yml/badge.svg
30+
:target: https://github.com/nipy/NiBabel/actions/workflows/stable.yml
31+
:alt: stable tests
32+
.. image:: https://codecov.io/gh/nipy/NiBabel/branch/master/graph/badge.svg
33+
:target: https://codecov.io/gh/nipy/NiBabel
34+
:alt: codecov badge
35+
36+
* - PyPI
37+
-
38+
.. image:: https://img.shields.io/pypi/v/nibabel.svg
39+
:target: https://pypi.python.org/pypi/nibabel/
40+
:alt: PyPI version
41+
.. image:: https://img.shields.io/pypi/dm/nibabel.svg
42+
:target: https://pypistats.org/packages/nibabel
43+
:alt: PyPI - Downloads
44+
45+
* - Packages
46+
-
47+
.. image:: https://img.shields.io/conda/vn/conda-forge/nibabel
48+
:target: https://anaconda.org/conda-forge/nibabel
49+
:alt: Conda package
50+
.. image:: https://repology.org/badge/version-for-repo/debian_unstable/nibabel.svg?header=Debian%20Unstable
51+
:target: https://repology.org/project/nibabel/versions
52+
:alt: Debian Unstable package
53+
.. image:: https://repology.org/badge/version-for-repo/aur/python:nibabel.svg?header=Arch%20%28%41%55%52%29
54+
:target: https://repology.org/project/python:nibabel/versions
55+
:alt: Arch (AUR)
56+
.. image:: https://repology.org/badge/version-for-repo/gentoo_ovl_science/nibabel.svg?header=Gentoo%20%28%3A%3Ascience%29
57+
:target: https://repology.org/project/nibabel/versions
58+
:alt: Gentoo (::science)
59+
.. image:: https://repology.org/badge/version-for-repo/nix_unstable/python:nibabel.svg?header=nixpkgs%20unstable
60+
:target: https://repology.org/project/python:nibabel/versions
61+
:alt: nixpkgs unstable
62+
63+
* - License & DOI
64+
-
65+
.. image:: https://img.shields.io/pypi/l/nibabel.svg
66+
:target: https://github.com/nipy/nibabel/blob/master/COPYING
67+
:alt: License
68+
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.591597.svg
69+
:target: https://doi.org/10.5281/zenodo.591597
70+
:alt: Zenodo DOI
71+
72+
.. Following contents should be copied from LONG_DESCRIPTION in nibabel/info.py
73+
74+
75+
Read and write access to common neuroimaging file formats, including:
76+
ANALYZE_ (plain, SPM99, SPM2 and later), GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_,
77+
MINC1_, MINC2_, `AFNI BRIK/HEAD`_, ECAT_ and Philips PAR/REC.
78+
In addition, NiBabel also supports FreeSurfer_'s MGH_, geometry, annotation and
79+
morphometry files, and provides some limited support for DICOM_.
80+
81+
NiBabel's API gives full or selective access to header information (metadata),
82+
and image data is made available via NumPy arrays. For more information, see
83+
NiBabel's `documentation site`_ and `API reference`_.
84+
85+
.. _API reference: https://nipy.org/nibabel/api.html
4386
.. _AFNI BRIK/HEAD: https://afni.nimh.nih.gov/pub/dist/src/README.attributes
44-
.. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
45-
.. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
87+
.. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
4688
.. _CIFTI-2: https://www.nitrc.org/projects/cifti/
89+
.. _DICOM: http://medical.nema.org/
90+
.. _documentation site: http://nipy.org/nibabel
91+
.. _ECAT: http://xmedcon.sourceforge.net/Docs/Ecat
92+
.. _Freesurfer: https://surfer.nmr.mgh.harvard.edu
93+
.. _GIFTI: https://www.nitrc.org/projects/gifti
94+
.. _MGH: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat
4795
.. _MINC1:
4896
https://en.wikibooks.org/wiki/MINC/Reference/MINC1_File_Format_Reference
4997
.. _MINC2:
5098
https://en.wikibooks.org/wiki/MINC/Reference/MINC2.0_File_Format_Reference
51-
.. _PyNIfTI: http://niftilib.sourceforge.net/pynifti/
52-
.. _GIFTI: https://www.nitrc.org/projects/gifti
53-
.. _MGH: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat
54-
.. _ECAT: http://xmedcon.sourceforge.net/Docs/Ecat
55-
.. _Freesurfer: https://surfer.nmr.mgh.harvard.edu
56-
.. _DICOM: http://medical.nema.org/
99+
.. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
100+
.. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
57101

58-
The various image format classes give full or selective access to header
59-
(meta) information and access to the image data is made available via NumPy
60-
arrays.
102+
Installation
103+
============
61104

62-
Website
63-
=======
105+
To install NiBabel's `current release`_ with ``pip``, run::
64106

65-
Current documentation on nibabel can always be found at the `NIPY nibabel
66-
website <http://nipy.org/nibabel>`_.
107+
pip install nibabel
67108

68-
Mailing Lists
69-
=============
109+
To install the latest development version, run::
70110

71-
Please send any questions or suggestions to the `neuroimaging mailing list
72-
<https://mail.python.org/mailman/listinfo/neuroimaging>`_.
111+
pip install git+https://github.com/nipy/nibabel
73112

74-
Code
75-
====
113+
When working on NiBabel itself, it may be useful to install in "editable" mode::
76114

77-
Install nibabel with::
115+
git clone https://github.com/nipy/nibabel.git
116+
pip install -e ./nibabel
78117

79-
pip install nibabel
118+
For more information on previous releases, see the `release archive`_ or
119+
`development changelog`_.
80120

81-
You may also be interested in:
121+
.. _current release: https://pypi.python.org/pypi/NiBabel
122+
.. _release archive: https://github.com/nipy/NiBabel/releases
123+
.. _development changelog: https://nipy.org/nibabel/changelog.html
82124

83-
* the `nibabel code repository`_ on Github;
84-
* documentation_ for all releases and current development tree;
85-
* download the `current release`_ from pypi;
86-
* download `current development version`_ as a zip file;
87-
* downloads of all `available releases`_.
125+
Mailing List
126+
============
88127

89-
.. _nibabel code repository: https://github.com/nipy/nibabel
90-
.. _Documentation: http://nipy.org/nibabel
91-
.. _current release: https://pypi.python.org/pypi/nibabel
92-
.. _current development version: https://github.com/nipy/nibabel/archive/master.zip
93-
.. _available releases: https://github.com/nipy/nibabel/releases
128+
Please send any questions or suggestions to the `neuroimaging mailing list
129+
<https://mail.python.org/mailman/listinfo/neuroimaging>`_.
94130

95131
License
96132
=======
97133

98-
Nibabel is licensed under the terms of the MIT license. Some code included
99-
with nibabel is licensed under the BSD license. Please see the COPYING file
100-
in the nibabel distribution.
134+
NiBabel is licensed under the terms of the `MIT license
135+
<https://github.com/nipy/nibabel/blob/master/COPYING#nibabel>`__.
136+
Some code included with NiBabel is licensed under the `BSD license`_.
137+
For more information, please see the COPYING_ file.
101138

102-
Citing nibabel
103-
==============
139+
.. _BSD license: https://opensource.org/licenses/BSD-3-Clause
140+
.. _COPYING: https://github.com/nipy/nibabel/blob/master/COPYING
104141

105-
Please see the `available releases`_ for the release of nibabel that you are
106-
using. Recent releases have a Zenodo_ `Digital Object Identifier`_ badge at
107-
the top of the release notes. Click on the badge for more information.
142+
Citation
143+
========
144+
145+
NiBabel releases have a Zenodo_ `Digital Object Identifier`_ (DOI) badge at
146+
the top of the release notes. Click on the badge for more information.
108147

109-
.. _zenodo: https://zenodo.org
110148
.. _Digital Object Identifier: https://en.wikipedia.org/wiki/Digital_object_identifier
149+
.. _zenodo: https://zenodo.org

‎doc/pics/logo.png

34.7 KB
Loading

‎doc/source/index.rst

+4
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@
77
#
88
### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ###
99
10+
=======
11+
NiBabel
12+
=======
13+
1014
.. include:: _long_description.inc
1115

1216
Documentation

‎nibabel/info.py

+52-59
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
"""Define distribution parameters for nibabel, including package version
1+
"""Define static nibabel metadata for nibabel
22
3-
The long description parameter is used to fill settings in setup.py, the
4-
nibabel top-level docstring, and in building the docs.
3+
The long description parameter is used in the nibabel top-level docstring,
4+
and in building the docs.
55
We exec this file in several places, so it cannot import nibabel or use
66
relative imports.
77
"""
@@ -12,86 +12,79 @@
1212
# We also include this text in the docs by ``..include::`` in
1313
# ``docs/source/index.rst``.
1414
long_description = """
15-
=======
16-
NiBabel
17-
=======
15+
Read and write access to common neuroimaging file formats, including:
16+
ANALYZE_ (plain, SPM99, SPM2 and later), GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_,
17+
MINC1_, MINC2_, `AFNI BRIK/HEAD`_, ECAT_ and Philips PAR/REC.
18+
In addition, NiBabel also supports FreeSurfer_'s MGH_, geometry, annotation and
19+
morphometry files, and provides some limited support for DICOM_.
1820
19-
Read / write access to some common neuroimaging file formats
21+
NiBabel's API gives full or selective access to header information (metadata),
22+
and image data is made available via NumPy arrays. For more information, see
23+
NiBabel's `documentation site`_ and `API reference`_.
2024
21-
This package provides read +/- write access to some common medical and
22-
neuroimaging file formats, including: ANALYZE_ (plain, SPM99, SPM2 and later),
23-
GIFTI_, NIfTI1_, NIfTI2_, `CIFTI-2`_, MINC1_, MINC2_, `AFNI BRIK/HEAD`_, MGH_ and
24-
ECAT_ as well as Philips PAR/REC. We can read and write FreeSurfer_ geometry,
25-
annotation and morphometry files. There is some very limited support for
26-
DICOM_. NiBabel is the successor of PyNIfTI_.
27-
28-
.. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
25+
.. _API reference: https://nipy.org/nibabel/api.html
2926
.. _AFNI BRIK/HEAD: https://afni.nimh.nih.gov/pub/dist/src/README.attributes
30-
.. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
31-
.. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
27+
.. _ANALYZE: http://www.grahamwideman.com/gw/brain/analyze/formatdoc.htm
3228
.. _CIFTI-2: https://www.nitrc.org/projects/cifti/
29+
.. _DICOM: http://medical.nema.org/
30+
.. _documentation site: http://nipy.org/nibabel
31+
.. _ECAT: http://xmedcon.sourceforge.net/Docs/Ecat
32+
.. _Freesurfer: https://surfer.nmr.mgh.harvard.edu
33+
.. _GIFTI: https://www.nitrc.org/projects/gifti
34+
.. _MGH: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat
3335
.. _MINC1:
3436
https://en.wikibooks.org/wiki/MINC/Reference/MINC1_File_Format_Reference
3537
.. _MINC2:
3638
https://en.wikibooks.org/wiki/MINC/Reference/MINC2.0_File_Format_Reference
37-
.. _PyNIfTI: http://niftilib.sourceforge.net/pynifti/
38-
.. _GIFTI: https://www.nitrc.org/projects/gifti
39-
.. _MGH: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat
40-
.. _ECAT: http://xmedcon.sourceforge.net/Docs/Ecat
41-
.. _Freesurfer: https://surfer.nmr.mgh.harvard.edu
42-
.. _DICOM: http://medical.nema.org/
39+
.. _NIfTI1: http://nifti.nimh.nih.gov/nifti-1/
40+
.. _NIfTI2: http://nifti.nimh.nih.gov/nifti-2/
4341
44-
The various image format classes give full or selective access to header
45-
(meta) information and access to the image data is made available via NumPy
46-
arrays.
42+
Installation
43+
============
4744
48-
Website
49-
=======
45+
To install NiBabel's `current release`_ with ``pip``, run::
5046
51-
Current documentation on nibabel can always be found at the `NIPY nibabel
52-
website <http://nipy.org/nibabel>`_.
47+
pip install nibabel
5348
54-
Mailing Lists
55-
=============
49+
To install the latest development version, run::
5650
57-
Please send any questions or suggestions to the `neuroimaging mailing list
58-
<https://mail.python.org/mailman/listinfo/neuroimaging>`_.
51+
pip install git+https://github.com/nipy/nibabel
5952
60-
Code
61-
====
53+
When working on NiBabel itself, it may be useful to install in "editable" mode::
6254
63-
Install nibabel with::
55+
git clone https://github.com/nipy/nibabel.git
56+
pip install -e ./nibabel
6457
65-
pip install nibabel
58+
For more information on previous releases, see the `release archive`_ or
59+
`development changelog`_.
6660
67-
You may also be interested in:
61+
.. _current release: https://pypi.python.org/pypi/NiBabel
62+
.. _release archive: https://github.com/nipy/NiBabel/releases
63+
.. _development changelog: https://nipy.org/nibabel/changelog.html
6864
69-
* the `nibabel code repository`_ on Github;
70-
* documentation_ for all releases and current development tree;
71-
* download the `current release`_ from pypi;
72-
* download `current development version`_ as a zip file;
73-
* downloads of all `available releases`_.
65+
Mailing List
66+
============
7467
75-
.. _nibabel code repository: https://github.com/nipy/nibabel
76-
.. _Documentation: http://nipy.org/nibabel
77-
.. _current release: https://pypi.python.org/pypi/nibabel
78-
.. _current development version: https://github.com/nipy/nibabel/archive/master.zip
79-
.. _available releases: https://github.com/nipy/nibabel/releases
68+
Please send any questions or suggestions to the `neuroimaging mailing list
69+
<https://mail.python.org/mailman/listinfo/neuroimaging>`_.
8070
8171
License
8272
=======
8373
84-
Nibabel is licensed under the terms of the MIT license. Some code included
85-
with nibabel is licensed under the BSD license. Please see the COPYING file
86-
in the nibabel distribution.
74+
NiBabel is licensed under the terms of the `MIT license
75+
<https://github.com/nipy/nibabel/blob/master/COPYING#nibabel>`__.
76+
Some code included with NiBabel is licensed under the `BSD license`_.
77+
For more information, please see the COPYING_ file.
8778
88-
Citing nibabel
89-
==============
79+
.. _BSD license: https://opensource.org/licenses/BSD-3-Clause
80+
.. _COPYING: https://github.com/nipy/nibabel/blob/master/COPYING
9081
91-
Please see the `available releases`_ for the release of nibabel that you are
92-
using. Recent releases have a Zenodo_ `Digital Object Identifier`_ badge at
93-
the top of the release notes. Click on the badge for more information.
82+
Citation
83+
========
84+
85+
NiBabel releases have a Zenodo_ `Digital Object Identifier`_ (DOI) badge at
86+
the top of the release notes. Click on the badge for more information.
9487
95-
.. _zenodo: https://zenodo.org
9688
.. _Digital Object Identifier: https://en.wikipedia.org/wiki/Digital_object_identifier
97-
"""
89+
.. _zenodo: https://zenodo.org
90+
""" # noqa: E501

0 commit comments

Comments
 (0)