From 2c54187bb156da81d8ad35bc734d55928ebcb69e Mon Sep 17 00:00:00 2001
From: Aaron Ayres <aayres@enthought.com>
Date: Tue, 24 Nov 2020 14:59:56 -0700
Subject: [PATCH 1/4] adding a short documentation section about the io sub
 package

---
 docs/source/index.rst           |  1 +
 docs/source/io/introduction.rst | 27 +++++++++++++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 docs/source/io/introduction.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 7524bf023..1891a5802 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -10,6 +10,7 @@ AppTools Documentation
     undo/*
     selection/*
     naming/*
+    io/*
     api
 
 * :ref:`search`
diff --git a/docs/source/io/introduction.rst b/docs/source/io/introduction.rst
new file mode 100644
index 000000000..d682b0d42
--- /dev/null
+++ b/docs/source/io/introduction.rst
@@ -0,0 +1,27 @@
+io
+===
+
+The io package provides a traited |File| object provides properties and methods
+for common file path manipulation operations.  On Python 3 much of this
+functionality is provided by the `pathlib`_ module, and for new code we
+encourage users to investigate if `pathlib`_ can satisfy their usecase before
+they turn to the `apptools.io` |File| object
+
+io.h5
+-----
+The io.h5 sub-package provides a wrapper around `PyTables`_ with a
+dictionary-style mapping.  Note that this module has a decent amount of
+overlap with `zarr`_.
+
+..
+   external links
+
+.. _pathlib: https://docs.python.org/3/library/pathlib.html
+.. _PyTables: https://www.pytables.org/
+.. _zarr: https://zarr.readthedocs.io/en/stable/
+
+
+..
+   # substitutions
+
+.. |File| replace:: :class:`~apptools.io.file.File`

From 59b77f4755733e3ef7423fec7c0993a00ff7caf5 Mon Sep 17 00:00:00 2001
From: Aaron Ayres <aayres@enthought.com>
Date: Tue, 24 Nov 2020 15:26:35 -0700
Subject: [PATCH 2/4] add a news fragment

---
 docs/releases/upcoming/237.doc.rst | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 docs/releases/upcoming/237.doc.rst

diff --git a/docs/releases/upcoming/237.doc.rst b/docs/releases/upcoming/237.doc.rst
new file mode 100644
index 000000000..557595c8c
--- /dev/null
+++ b/docs/releases/upcoming/237.doc.rst
@@ -0,0 +1 @@
+Document the ``apptools.io`` and ``apptools.io.h5`` sub packages (#237)
\ No newline at end of file

From 82963572181bf84eee4f06277fedaedf2e407a48 Mon Sep 17 00:00:00 2001
From: Aaron Ayres <aayres@enthought.com>
Date: Wed, 25 Nov 2020 06:48:25 -0700
Subject: [PATCH 3/4] apply suggestions from code review

---
 docs/source/io/introduction.rst | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/source/io/introduction.rst b/docs/source/io/introduction.rst
index d682b0d42..a634ca9d5 100644
--- a/docs/source/io/introduction.rst
+++ b/docs/source/io/introduction.rst
@@ -1,24 +1,24 @@
 io
 ===
 
-The io package provides a traited |File| object provides properties and methods
-for common file path manipulation operations.  On Python 3 much of this
-functionality is provided by the `pathlib`_ module, and for new code we
-encourage users to investigate if `pathlib`_ can satisfy their usecase before
-they turn to the `apptools.io` |File| object
+The :mod:`apptools.io` package provides a traited |File| object provides
+properties and methods for common file path manipulation operations.  Much of
+this functionality was implemented before Python 3 `pathlib`_ standard library
+became available to provide similar support.  For new code we encourage users
+to investigate if `pathlib`_ can satisfy their use cases before they turn to
+the `apptools.io` |File| object
 
 io.h5
 -----
-The io.h5 sub-package provides a wrapper around `PyTables`_ with a
-dictionary-style mapping.  Note that this module has a decent amount of
-overlap with `zarr`_.
+The :mod:`apptools.io.h5` sub-package provides a wrapper around `PyTables`_
+with a dictionary-style mapping.
+
 
 ..
    external links
 
 .. _pathlib: https://docs.python.org/3/library/pathlib.html
 .. _PyTables: https://www.pytables.org/
-.. _zarr: https://zarr.readthedocs.io/en/stable/
 
 
 ..

From 743cb873215810347fba944772918ab51a007f96 Mon Sep 17 00:00:00 2001
From: Aaron Ayres <aayres@enthought.com>
Date: Wed, 25 Nov 2020 07:46:59 -0700
Subject: [PATCH 4/4] change io and io.h5 section titles to File I/O and HDF5
 File Support

---
 docs/source/io/introduction.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/source/io/introduction.rst b/docs/source/io/introduction.rst
index a634ca9d5..6bdd04ef5 100644
--- a/docs/source/io/introduction.rst
+++ b/docs/source/io/introduction.rst
@@ -1,5 +1,5 @@
-io
-===
+File I/O
+========
 
 The :mod:`apptools.io` package provides a traited |File| object provides
 properties and methods for common file path manipulation operations.  Much of
@@ -8,8 +8,9 @@ became available to provide similar support.  For new code we encourage users
 to investigate if `pathlib`_ can satisfy their use cases before they turn to
 the `apptools.io` |File| object
 
-io.h5
------
+HDF5 File Support
+-----------------
+
 The :mod:`apptools.io.h5` sub-package provides a wrapper around `PyTables`_
 with a dictionary-style mapping.