add documentation about bin/h5fs that is used to produce a manpage draft
authoralain leufroy <alain@leufroy.fr>
Mon, 08 Apr 2013 10:20:00 +0200
changeset 60 65e48edd25cb
parent 56 5e495c685466
child 61 d7ad55206a47
add documentation about bin/h5fs that is used to produce a manpage
MANIFEST.in
debian/control
debian/rules
doc/h5fs.rst
--- a/MANIFEST.in	Sat Mar 30 02:52:36 2013 +0100
+++ b/MANIFEST.in	Mon Apr 08 10:20:00 2013 +0200
@@ -1,1 +1,2 @@
 recursive-include debian *
+include doc/h5fs.rst
\ No newline at end of file
--- a/debian/control	Sat Mar 30 02:52:36 2013 +0100
+++ b/debian/control	Mon Apr 08 10:20:00 2013 +0200
@@ -2,7 +2,7 @@
 Maintainer: alain leufroy <alain.leufroy@logilab.fr>
 Section: python
 Priority: optional
-Build-Depends: python (>= 2.6.6-3), debhelper (>= 7.4.3), fuse (>= 2.9.2), python-fuse, python-h5py, python-numpy
+Build-Depends: python (>= 2.6.6-3), debhelper (>= 7.4.3), fuse (>= 2.9.2), python-fuse, python-h5py, python-numpy, python-docutils
 Standards-Version: 3.9.1
 
 Package: h5fs
--- a/debian/rules	Sat Mar 30 02:52:36 2013 +0100
+++ b/debian/rules	Mon Apr 08 10:20:00 2013 +0200
@@ -8,4 +8,7 @@
 
 override_dh_auto_install:
 	python setup.py install --root=debian/h5fs --install-layout=deb --install-lib=/usr/share/h5fs --install-scripts=/usr/share/h5fs
+	mkdir -p debian/h5fs/usr/share/man/man1/
+	rst2man doc/h5fs.rst debian/h5fs/usr/share/man/man1/h5fs.1 && gzip debian/h5fs/usr/share/man/man1/h5fs.1
+
 override_dh_auto_build:
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/h5fs.rst	Mon Apr 08 10:20:00 2013 +0200
@@ -0,0 +1,121 @@
+.. use /usr/bin/rst2man (docutils) to build the manpage
+
+======
+ H5FS
+======
+
+
+------------------------------------------------
+mounts an HDF5 resource as a regular file system
+------------------------------------------------
+
+:Author: H5FS has been written by Alain Leufroy <alain.leufroy@logilab.fr>
+:Date:   2013-03-30
+:Copyright: LGPL-v3
+:Version: 0.1
+:Manual section: 1
+:Manual group: HDF5 Filesystem
+
+
+SYNOPSIS
+========
+
+  mounting
+    h5fs file mountpoint [options]
+
+  unmounting
+    fuserumount -u mountpoint
+
+
+DESCRIPTION
+===========
+
+H5FS (Hierarchical Data Format FileSystem) is a file system for Linux (and other
+operating systems with a FUSE implementation, such as Mac OS X or FreeBSD)
+capable of operations on an HDF5 file.
+
+On the local computer where the HDF5 file is mounted, the implementation makes
+use of the FUSE (Filesystem in Userspace) kernel module. The practical effect of
+this is that the end user can interact with the content of a HDF5 file in a
+natural way as HDF5 uses a filesystem-like data format to access the resources.
+
+GROUPS are exposed as folders and DATASETS are exposed as files.
+
+
+OPTIONS
+=======
+
+General options:
+----------------
+
+--help, -h
+  print help
+
+--version, -v
+  print version
+
+--debug, -d
+  start debug mode
+
+
+EXAMPLES
+========
+
+This example shows how to mount an HDF5 file ``/path/to/file.h5`` to
+``/tmp/mountpoint``::
+
+% mkdir /tmp/mountpoint
+% h5fs /path/to/file.h5 /tmp/mountpoint
+
+The filesystem is now mounted and visible at ``/tmp/mountpoint``. Assuming that the
+file contains a group "picture" with two datasets "image1" and "pallete", the
+resources can be listed using the *tree* program:
+
+::
+
+  % tree /tmp/mountpoint
+  /tmp/mountpoint
+  `-- picture
+      |-- image1.npy
+      `-- pallete.npy
+  
+  1 directories, 2 files
+
+The array of a dataset can be read using python and the numpy module:
+
+::
+
+  % python
+  >>> import numpy
+  >>> arr = numpy.load('/tmp/mountpoint/picture/image1.npy')
+  >>> arr.shape
+  (200, 400, 1)
+  >>> exit()
+
+To unmount the filesystem, use fusermount with the -u (unmount) option::
+
+  % fusermount -u /tmp/mountpoint
+  % rm -r /tmp/mountpoint
+
+
+LIMITATIONS
+===========
+
+#. All features of HDF5 are not yet implemented (attributes, links)
+#. Modifying resources are not yet implemented
+
+
+SEE ALSO
+========
+
+* ``man fusermount``
+* ``hdf5`` <http://www.hdfgroup.org>
+
+
+DISCLAIMER
+==========
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. Please refer to the "copyright" file distributed with H5FS
+for complete details.