[h5py] 153/455: Doc fixes
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Thu Jul 2 18:19:27 UTC 2015
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 3777b40553ca9cf4b5217eceeaad0001250c82c9
Author: andrewcollette <andrew.collette at gmail.com>
Date: Mon Nov 10 04:16:13 2008 +0000
Doc fixes
---
docs/source/_static/h5py.css | 11 +++++++++++
docs/source/api/index.rst | 34 ++++++++++++++++++----------------
docs/source/automod.py | 2 +-
docs/source/conf.py | 8 ++++----
docs/source/guide/index.rst | 36 ++++--------------------------------
h5py/h5a.pyx | 20 ++++++++++----------
setup.py | 15 ++++++++++-----
7 files changed, 58 insertions(+), 68 deletions(-)
diff --git a/docs/source/_static/h5py.css b/docs/source/_static/h5py.css
index c2907f5..58ee017 100644
--- a/docs/source/_static/h5py.css
+++ b/docs/source/_static/h5py.css
@@ -27,6 +27,14 @@ a:hover {
color: #2491CF;
}
+/* Italic reference links are annoying */
+
+.reference em {
+ font-style: normal;
+}
+
+/* Custom header CSS */
+
#tophdr {
background: #fff;
height: 3.0em;
@@ -53,12 +61,15 @@ a:hover {
#tophdr p a {
color: #222;
+ text-decoration: underline;
}
#tophdr p a:hover {
color: #444;
}
+/* End custom header CSS */
+
pre {
font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
font-size: 0.95em;
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index 1a77b8b..cd30092 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -1,24 +1,27 @@
-Low-level (``h5py.h5*``) guide
-==============================
-While the `high-level component`__ provides a friendly, NumPy-like interface
+.. _api_ref:
+
+***********************
+Low-level API reference
+***********************
+
+While the :ref:`high-level component <user_guide>` provides a friendly,
+NumPy-like interface
to HDF5, the major accomplishment of h5py is the low-level interface. This
is the most powerful and flexible way to access HDF5, and is as close as you
can get the the library without having to actually write C code.
-__ http://h5py.alfven.org
-
The goal of this layer is to provide access to (almost) the entire HDF5 C API,
while retaining a Pythonic, object-oriented style. Emphasis has been placed
on clean design and exhaustive documentation. Programmers familiar with the
HDF5 C API should find themselves at home.
-You'll probably also find the `official HDF5 documentation`__ useful as a guide
+You'll probably also find the
+`official HDF5 documentation <http://www.hdfgroup.com/HDF5>`_
+useful as a guide
to how the library itself operates. In particular, the HDF5 User Guide is
an excellent description of each major component.
-__ http://hdf.ncsa.uiuc.edu/HDF5/doc/index.html
-
Version of this documentation
-----------------------------
@@ -31,15 +34,14 @@ than force you to use either version, h5py can be compiled in one of two
available. When compiled against HDF5 1.8 (``--api=18``), many new features
are available.
-The `1.6 mode`_ and `1.8 mode`_ are therefore documented separately.
-
-.. _`1.6 mode`: http://h5py.alfven.org/doc16
-.. _`1.8 mode`: http://h5py.alfven.org/doc18
+Despite the major differences between these two versions of HDF5, the library
+has been designed for compatibility; the new feature set is a strict superset of
+the old. Code written against 1.6 will continue to work with 1.8.
-Despite the major differences between these two versions of HDF5, the
-signatures of all routines in the "1.6 API" mode of h5py are
-forward-compatible with the "1.8 API" mode. Code written against the 1.6 mode
-should work fine when moving to 1.8.
+Keep in mind that since this documentation is generated against the most recent
+(1.8) API version available, some routines, arguments, keywords and even
+data structures documented here may not be available in earlier versions.
+Wherever possible, this is documented.
Low-level API reference
-----------------------
diff --git a/docs/source/automod.py b/docs/source/automod.py
index 6d41901..fcf74a5 100644
--- a/docs/source/automod.py
+++ b/docs/source/automod.py
@@ -210,7 +210,7 @@ def setup(spx):
del lines[:]
for line in final_lines:
- line = replace_param(line)
+ #line = replace_param(line)
line = replace_constant(line, mod)
line = replace_module(line)
line = replace_class(line)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index dfe2134..e2bbc0b 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -39,16 +39,16 @@ source_suffix = '.rst'
master_doc = 'index'
# General substitutions.
-project = 'h5py Low-Level API'
+project = 'h5py'
copyright = '2008, Andrew Collette'
# The default replacements for |version| and |release|, also used in various
# other places throughout the built documents.
#
# The short X.Y version.
-version = '0.4'
+version = '1.0'
# The full version, including alpha/beta/rc tags.
-release = '0.4.0'
+release = '1.0.0'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
@@ -91,7 +91,7 @@ html_style = 'h5py.css'
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
-#html_title = None
+html_title = "HDF5 for Python 1.0"
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
diff --git a/docs/source/guide/index.rst b/docs/source/guide/index.rst
index e4c5324..fbd9413 100644
--- a/docs/source/guide/index.rst
+++ b/docs/source/guide/index.rst
@@ -1,37 +1,9 @@
+.. _user_guide:
-Python bindings for the HDF5 library
-====================================
-
-The `HDF5 library`__ is a versatile, mature library designed for the storage
-of numerical data. The h5py package provides a simple, Pythonic interface to
-HDF5. A straightforward high-level interface allows the manipulation of
-HDF5 files, groups and datasets using established Python and NumPy metaphors.
-
-__ http://www.hdfgroup.com/HDF5
-
-Additionally, the library offers a low-level interface which exposes the
-majority of the HDF5 C API in a Pythonic, object-oriented fashion. This
-interface is documented `separately`__.
-
-__ http://h5py.alfven.org/docs
-
-The major design goals for h5py are simplicity and interoperability. You don't
-need to learn any new concepts beyond the basic principles of HDF5 and NumPy
-arrays, and the files you create with h5py can be opened with any other
-HDF5-aware program.
-
-* `Downloads for Unix/Windows, and bug tracker (Google Code)`__
-* `Alternate Windows installers`__
-* `Low-level API documentation`__
-
-* Mail: "h5py" at the domain "alfven" dot "org"
-
-__ http://h5py.googlecode.com
-__ http://h5py.alfven.org/windows/
-__ http://h5py.alfven.org/docs/
-
-Contents:
+**********
+User Guide
+**********
.. toctree::
:maxdepth: 2
diff --git a/h5py/h5a.pyx b/h5py/h5a.pyx
index f57b826..68e24ec 100644
--- a/h5py/h5a.pyx
+++ b/h5py/h5a.pyx
@@ -44,10 +44,10 @@ IF H5PY_18API:
Create a new attribute, attached to an existing object.
- + STRING obj_name (".")
+ STRING obj_name (".")
Attach attribute to this group member instead
- + PropID lapl
+ PropID lapl
Link access property list for obj_name
"""
@@ -181,15 +181,15 @@ IF H5PY_18API:
Remove an attribute from an object. Specify exactly one of "name"
or "index". Keyword-only arguments:
- + STRING obj_name (".")
+ STRING obj_name (".")
Attribute is attached to this group member
- + PropID lapl (None)
+ PropID lapl (None)
Link access property list for obj_name
- + INT index_type (h5.INDEX_NAME)
+ INT index_type (h5.INDEX_NAME)
- + INT order (h5.ITER_NATIVE)
+ INT order (h5.ITER_NATIVE)
"""
if name != NULL and index < 0:
H5Adelete_by_name(loc.id, obj_name, name, pdefault(lapl))
@@ -254,16 +254,16 @@ IF H5PY_18API:
2. If you have the parent object, supply it and exactly one of
either name or index.
- + STRING obj_name (".")
+ STRING obj_name (".")
Use this group member instead
- + PropID lapl (None)
+ PropID lapl (None)
Link access property list for obj_name
- + INT index_type (h5.INDEX_NAME)
+ INT index_type (h5.INDEX_NAME)
Which index to use
- + INT order (h5.ITER_NATIVE)
+ INT order (h5.ITER_NATIVE)
What order the index is in
"""
cdef AttrInfo info = AttrInfo()
diff --git a/setup.py b/setup.py
index e524268..0a4c560 100644
--- a/setup.py
+++ b/setup.py
@@ -368,9 +368,12 @@ class doc(Command):
description = "Rebuild documentation"
- user_options = []
+ user_options = [('rebuild', 'r', "Rebuild from scratch")]
+ boolean_options = ['rebuild']
+
def initialize_options(self):
- pass
+ self.rebuild = False
+
def finalize_options(self):
pass
@@ -380,9 +383,8 @@ class doc(Command):
buildobj.run()
pth = op.abspath(buildobj.build_lib)
- for x in ('docs/html', 'docs/build'):
- if op.exists(x):
- shutil.rmtree(x)
+ if self.rebuild and op.exists('docs/build'):
+ shutil.rmtree('docs/build')
cmd = "export H5PY_PATH=%s; cd docs; make html" % pth
@@ -390,6 +392,9 @@ class doc(Command):
if retval != 0:
fatal("Can't build documentation")
+ if op.exists('docs/html'):
+ shutil.rmtree('docs/html')
+
shutil.copytree('docs/build/html', 'docs/html')
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/h5py.git
More information about the debian-science-commits
mailing list