[h5py] 454/455: Doc updates and fixes

[Ghislain Vaillant]

This is an automated email from the git hooks/post-receive script.

ghisvail-guest pushed a commit to annotated tag 1.3.0
in repository h5py.

commit 8eb330d0077f892d6b40493fca36b52a1f8d5c58
Author: andrewcollette <andrew.collette at gmail.com>
Date:   Mon Mar 15 04:10:32 2010 +0000

    Doc updates and fixes
---
 docs/source/_static/h5py.css | 27 ++++++++++++++++++++++
 docs/source/conf.py          |  2 ++
 docs/source/guide/compat.rst |  2 +-
 docs/source/guide/group.rst  |  2 ++
 docs/source/guide/quick.rst  | 53 +++++++++++++++++++++++++-------------------
 h5py/highlevel.py            | 16 ++++++++-----
 6 files changed, 72 insertions(+), 30 deletions(-)

diff --git a/docs/source/_static/h5py.css b/docs/source/_static/h5py.css
new file mode 100644
index 0000000..0805a73
--- /dev/null
+++ b/docs/source/_static/h5py.css
@@ -0,0 +1,27 @@
+
+ at import url("agogo.css");
+
+/* Agogo lists are all scrunched up */
+ul.simple {
+    margin: 10px;
+}
+
+/* No more plain HTML tables */
+table.docutils {
+    
+    border-collapse: collapse;
+    border: 1px #555;
+}
+
+table.docutils td {
+    padding: 4px;
+}
+
+/* Italic links are distracting to read */
+a.reference em {
+    font-style: normal;
+}
+
+dl.docutils dt {
+    text-decoration: underline;
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 7602321..b0f875c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -102,6 +102,8 @@ pygments_style = 'sphinx'
 # Sphinx are currently 'default' and 'sphinxdoc'.
 html_theme = 'agogo'
 
+html_style = 'h5py.css'
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
diff --git a/docs/source/guide/compat.rst b/docs/source/guide/compat.rst
index ccb5c62..472f031 100644
--- a/docs/source/guide/compat.rst
+++ b/docs/source/guide/compat.rst
@@ -1,5 +1,5 @@
 *******************
-Compatibility Guide
+Compatibility Notes
 *******************
 
 File compatibility
diff --git a/docs/source/guide/group.rst b/docs/source/guide/group.rst
index f871f7a..c757914 100644
--- a/docs/source/guide/group.rst
+++ b/docs/source/guide/group.rst
@@ -66,6 +66,8 @@ Group objects implement the following subset of the Python "mapping" interface:
 - :meth:`__delitem__() <Group.__delitem__>`
 - :meth:`get() <Group.get>`
 
+.. _softlinks:
+
 Soft links
 ----------
 
diff --git a/docs/source/guide/quick.rst b/docs/source/guide/quick.rst
index 655dcec..08f6386 100644
--- a/docs/source/guide/quick.rst
+++ b/docs/source/guide/quick.rst
@@ -19,19 +19,25 @@ What is HDF5?
 
 It's a filesystem for your data.
 
-Only two kinds of objects are stored in HDF5 files: 
-*datasets*, which are homogenous, regular arrays of data (just like
-NumPy arrays), and *groups*, which are containers that store datasets and
-other groups.  Each file is organized using a filesystem metaphor; groups
-are like folders, and datasets are like files.  The syntax for accessing
-objects in the file is the traditional POSIX filesystem syntax.  Here
-are some examples::
+More accurately, it's a widely used scientific file format for archiving and
+sharing large amounts of numerical data.  HDF5 files contain *datasets*, which
+are homogenous, regular arrays of data (like NumPy arrays), and *groups*,
+which are containers that store datasets and other groups.
+
+In this sense, the structure of an HDF5 file is analagous to a POSIX filesystem.
+In fact, this is exactly the syntax used by HDF5 itself to locate resources::
 
     /                       (Root group)
     /MyGroup                (Subgroup)
     /MyGroup/DS1            (Dataset stored in subgroup)
     /MyGroup/Subgroup/DS2   (and so on)
 
+HDF5 also has a well-developed type system, supporting integers and floats
+of all the normal sizes and byte orders, as well as more advanced constructs
+like compound and array types.  The library handles all type conversion
+internally; you can read and write data without having to worry about things
+like endian-ness or precision.
+
 What is h5py?
 =============
 
@@ -56,9 +62,11 @@ Getting data into HDF5
 
 First, install h5py by following the :ref:`installation instructions <build>`.
 
-Since an example is worth a thousand words, here's how to make a new file,
-and create an integer dataset inside it.  The new dataset has shape (100, 100),
-is located in the file at ``"/MyDataset"``, and initialized to the value 42.
+Since examples are better than long-winded explanations, here's how to:
+
+    * Make a new file
+    * Create an integer dataset, with shape (100,100)
+    * Initialize the dataset to the value 42
 
     >>> import h5py
     >>> f = h5py.File('myfile.hdf5')
@@ -71,8 +79,8 @@ including "r", "w", and "a" (the default):
     >>> f = h5py.File('file1.hdf5', 'w')    # overwrite any existing file
     >>> f = h5py.File('file2.hdf5', 'r')    # open read-only
 
-The dataset object ``dset`` here represents a new 2-d HDF5 dataset.  Some
-features will be familiar to NumPy users::
+The :ref:`Dataset <datasets>` object ``dset`` here represents a new 2-d HDF5
+dataset.  Some features will be familiar to NumPy users::
 
     >>> dset.shape
     (100, 100)
@@ -165,15 +173,6 @@ you have to manually delete the existing object first::
     >>> del f['NewGroup']
     >>> grp = f.create_group("NewGroup")
 
-This restriction reflects HDF5's lack of transactional support, and will not
-change.
-
-.. note::
-
-    Most HDF5 versions don't support automatic creation of intermediate
-    groups; you can't yet do ``f.create_group('foo/bar/baz')`` unless both
-    groups "foo" and "bar" already exist.
-
 Attributes
 ==========
 
@@ -201,8 +200,16 @@ unlike group members, you can directly overwrite existing attributes:
 
     >>> dset.attrs["Name"] = "New Name"
 
-More information
-================
+Other stuff
+===========
+
+In addition to this basic behavior, HDF5 has a lot of other goodies.  Some
+of these features are:
+
+* :ref:`Compressed datasets <dsetfeatures>`
+* :ref:`Soft and external links <softlinks>`
+* :ref:`Object and region references <refs>`
+
 
 Full documentation on files, groups, datasets and attributes is available
 in the section ":ref:`h5pyreference`".
diff --git a/h5py/highlevel.py b/h5py/highlevel.py
index 45f058e..90e161a 100644
--- a/h5py/highlevel.py
+++ b/h5py/highlevel.py
@@ -1410,12 +1410,16 @@ class AttributeManager(_DictCompat):
     def create(self, name, data, shape=None, dtype=None):
         """ Create a new attribute, overwriting any existing attribute.
 
-        name:   Name of the new attribute (required)
-        data:   An array to initialize the attribute (required)
-        shape:  Shape of the attribute.  Overrides data.shape if both are
-                given.  The total number of points must be unchanged.
-        dtype:  Data type of the attribute.  Overrides data.dtype if both
-                are given.  Must be conversion-compatible with data.dtype.
+        name
+            Name of the new attribute (required)
+        data
+            An array to initialize the attribute (required)
+        shape
+            Shape of the attribute.  Overrides data.shape if both are
+            given.  The total number of points must be unchanged.
+        dtype
+            Data type of the attribute.  Overrides data.dtype if both
+            are given.  Must be conversion-compatible with data.dtype.
         """
         register_thread()
         with phil:

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/h5py.git