Add matrix market to readwrite reference (#4934)

* Add matrix_market reference stub.

* Add R/W examples to matrix_market stub.

* Add matrix market to toctree.

* Remove irrelevant factoid.

* Re-name according to review suggestion.

2 files changed, 101 insertions, 0 deletions

diff --git a/doc/reference/readwrite/index.rst b/doc/reference/readwrite/index.rst
index 163e45ca..76a3f217 100644
--- a/doc/reference/readwrite/index.rst
+++ b/doc/reference/readwrite/index.rst
@@ -19,3 +19,4 @@ Reading and writing graphs
    sparsegraph6
    pajek
    nx_shp
+   matrix_market
diff --git a/doc/reference/readwrite/matrix_market.rst b/doc/reference/readwrite/matrix_market.rst
new file mode 100644
index 00000000..d3450699
--- /dev/null
+++ b/doc/reference/readwrite/matrix_market.rst
@@ -0,0 +1,100 @@
+*************
+Matrix Market
+*************
+
+The `Matrix Market`_ exchange format is a text-based file format described by
+NIST.
+Matrix Market supports both a **coordinate format** for sparse matrices and
+an **array format** for dense matrices.
+The :mod:`scipy.io` module provides the `scipy.io.mmread` and `scipy.io.mmwrite`
+functions to read and write data in Matrix Market format, respectively.
+These functions work with either `numpy.ndarray` or `scipy.sparse.coo_matrix`
+objects depending on whether the data is in **array** or **coordinate** format.
+These functions can be combined with those of NetworkX's `~networkx.convert_matrix`
+module to read and write Graphs in Matrix Market format.
+
+.. _Matrix Market: https://math.nist.gov/MatrixMarket/formats.html
+
+Examples
+========
+
+Reading and writing graphs using Matrix Market's **array format** for dense
+matrices::
+
+    >>> import scipy as sp
+    >>> import scipy.io  # for mmread() and mmwrite()
+    >>> import io  # Use BytesIO as a stand-in for a Python file object
+    >>> fh = io.BytesIO()
+
+    >>> G = nx.complete_graph(5)
+    >>> a = nx.to_numpy_array(G)
+    >>> print(a)
+    [[0. 1. 1. 1. 1.]
+     [1. 0. 1. 1. 1.]
+     [1. 1. 0. 1. 1.]
+     [1. 1. 1. 0. 1.]
+     [1. 1. 1. 1. 0.]]
+
+    >>> # Write to file in Matrix Market array format
+    >>> sp.io.mmwrite(fh, a)
+    >>> print(fh.getvalue().decode('utf-8'))  # file contents
+    %%MatrixMarket matrix array real symmetric
+    %
+    5 5
+    0.0000000000000000e+00
+    1.0000000000000000e+00
+    1.0000000000000000e+00
+    1.0000000000000000e+00
+    1.0000000000000000e+00
+    0.0000000000000000e+00
+    1.0000000000000000e+00
+    1.0000000000000000e+00
+    1.0000000000000000e+00
+    0.0000000000000000e+00
+    1.0000000000000000e+00
+    1.0000000000000000e+00
+    0.0000000000000000e+00
+    1.0000000000000000e+00
+    0.0000000000000000e+00
+
+    >>> # Read from file
+    >>> fh.seek(0)
+    >>> H = nx.from_numpy_array(sp.io.mmread(fh))
+    >>> H.edges() == G.edges()
+    True
+
+Reading and writing graphs using Matrix Market's **coordinate format** for
+sparse matrices::
+
+    >>> import scipy as sp
+    >>> import scipy.io  # for mmread() and mmwrite()
+    >>> import io  # Use BytesIO as a stand-in for a Python file object
+    >>> fh = io.BytesIO()
+
+    >>> G = nx.path_graph(5)
+    >>> m = nx.to_scipy_sparse_matrix(G)
+    >>> print(m)
+      (0, 1)        1
+      (1, 0)        1
+      (1, 2)        1
+      (2, 1)        1
+      (2, 3)        1
+      (3, 2)        1
+      (3, 4)        1
+      (4, 3)        1
+
+    >>> sp.io.mmwrite(fh, m)
+    >>> print(fh.getvalue().decode('utf-8'))  # file contents
+    %%MatrixMarket matrix coordinate integer symmetric
+    %
+    5 5 4
+    2 1 1
+    3 2 1
+    4 3 1
+    5 4 1
+
+    >>> # Read from file
+    >>> fh.seek(0)
+    >>> H = nx.from_scipy_sparse_matrix(sp.io.mmread(fh))
+    >>> H.edges() == G.edges()
+    True