Repository: numpy/numpy

Issue:
DOC: Fix mistake in documentation of `*.npy` header.
The [documentation](https://docs.scipy.org/doc/numpy/neps/npy-format.html#format-specification-version-1-0) of the format contains the following paragraph:

> "The next HEADER_LEN bytes form the header data describing the array’s format. It is an ASCII string which contains a Python literal expression of a dictionary. It is terminated by a newline (‘n’) and padded with spaces (‘x20’) to make the total length of the magic string + 4 + HEADER_LEN be evenly divisible by **16** for alignment purposes."

In the code comments (and in the actual format), padding is done such that the sum of the length of the magic string, 4, and the HEADER_LEN, is evenly divisible by **64**, not 16, as shown [here](https://github.com/numpy/numpy/blob/master/numpy/lib/format.py#L105): 

This has caused me some headache while writing a custom .npy serializer..

Also, the wording "to make the total length of the magic string + 4 + HEADER_LEN" is a little confusing, as it makes it seem that the amount being referenced is equal to `total length of magic string` + `4` + `HEADER_LEN` as opposed to total length of `magic string + 4 + HEADER_LEN`.





Discussion:
This is something that changed since the initial release. Generally speaking, NEPs are proposal documents and, to the extent that they are documentation of code or formats, they document only what's being proposed. Once we do accept the NEP, whatever is useful long-term ought to be moved over into the official documentation, and the NEP should be frozen in place and not considered documentation of the released feature anymore.

It looks like we did move the documentation over into the docstrings, but we never added it to the numpy reference, and we're still [pointing to the NEP](https://docs.scipy.org/doc/numpy/reference/routines.io.html). Whoever wants to fix this, I would encourage them to expose the true documentation in `numpy.lib.format` and fix references to the NEP to this documentation.

Resolving patch:
diff --git a/numpy/lib/format.py b/numpy/lib/format.py
--- a/numpy/lib/format.py
+++ b/numpy/lib/format.py
@@ -1,5 +1,8 @@
 """
-Define a simple format for saving numpy arrays to disk with the full
+Binary Serialization
+====================
+
+A simple format for saving numpy arrays to disk with the full
 information about them.
 
 The ``.npy`` format is the standard binary file format in NumPy for
@@ -143,8 +146,10 @@
 
 Notes
 -----
-The ``.npy`` format, including reasons for creating it and a comparison of
-alternatives, is described fully in the "npy-format" NEP.
+The ``.npy`` format, including motivation for creating it and a comparison of
+alternatives, is described in the `"npy-format" NEP 
+<http://www.numpy.org/neps/nep-0001-npy-format.html>`_, however details have
+evolved with time and this document is more current.
 
 """
 from __future__ import division, absolute_import, print_function
diff --git a/numpy/lib/npyio.py b/numpy/lib/npyio.py
--- a/numpy/lib/npyio.py
+++ b/numpy/lib/npyio.py
@@ -475,9 +475,7 @@ def save(file, arr, allow_pickle=True, fix_imports=True):
 
     Notes
     -----
-    For a description of the ``.npy`` format, see the module docstring
-    of `numpy.lib.format` or the NumPy Enhancement Proposal
-    http://numpy.github.io/neps/npy-format.html
+    For a description of the ``.npy`` format, see :py:mod:`numpy.lib.format`
 
     Examples
     --------
@@ -561,9 +559,7 @@ def savez(file, *args, **kwds):
     The ``.npz`` file format is a zipped archive of files named after the
     variables they contain.  The archive is not compressed and each file
     in the archive contains one variable in ``.npy`` format. For a
-    description of the ``.npy`` format, see `numpy.lib.format` or the
-    NumPy Enhancement Proposal
-    http://numpy.github.io/neps/npy-format.html
+    description of the ``.npy`` format, see :py:mod:`numpy.lib.format`
 
     When opening the saved ``.npz`` file with `load` a `NpzFile` object is
     returned. This is a dictionary-like object which can be queried for
@@ -642,9 +638,9 @@ def savez_compressed(file, *args, **kwds):
     The ``.npz`` file format is a zipped archive of files named after the
     variables they contain.  The archive is compressed with
     ``zipfile.ZIP_DEFLATED`` and each file in the archive contains one variable
-    in ``.npy`` format. For a description of the ``.npy`` format, see
-    `numpy.lib.format` or the NumPy Enhancement Proposal
-    http://numpy.github.io/neps/npy-format.html
+    in ``.npy`` format. For a description of the ``.npy`` format, see 
+    :py:mod:`numpy.lib.format`
+
 
     When opening the saved ``.npz`` file with `load` a `NpzFile` object is
     returned. This is a dictionary-like object which can be queried for


Test patch: