[h5py] 140/455: Updating docs; not working yet
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Thu Jul 2 18:19:26 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 6f81a68a30e814f77b6bec7db121bb1dca881772
Author: andrewcollette <andrew.collette at gmail.com>
Date: Fri Oct 17 21:48:24 2008 +0000
Updating docs; not working yet
---
docs/source/auto.rst | 6 --
docs/source/low.rst | 19 +++-
docs/source/low/h5.rst | 7 ++
docs/source/{ => low}/h5a.rst | 1 +
docs/source/{ => low}/h5d.rst | 0
docs/source/low/h5f.rst | 6 ++
docs/source/low/h5g.rst | 6 ++
docs/source/low/h5i.rst | 6 ++
docs/source/low/h5p.rst | 6 ++
docs/source/low/h5r.rst | 6 ++
docs/source/low/h5s.rst | 6 ++
docs/source/low/h5t.rst | 47 +++++++++
docs/source/low/h5z.rst | 6 ++
docs_api/Makefile | 70 +++++++++++++
{docs => docs_api}/source/automod.py | 22 ++++-
docs_api/source/conf.py | 185 +++++++++++++++++++++++++++++++++++
docs_api/source/index.rst | 19 ++++
h5py/h5a.pyx | 5 +-
h5py/h5d.pyx | 7 +-
h5py/h5f.pyx | 33 ++++---
h5py/version.py | 11 +++
21 files changed, 446 insertions(+), 28 deletions(-)
diff --git a/docs/source/auto.rst b/docs/source/auto.rst
deleted file mode 100644
index c43a790..0000000
--- a/docs/source/auto.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-.. toctree::
- :maxdepth: 2
-
- h5a
- h5d
-
diff --git a/docs/source/low.rst b/docs/source/low.rst
index 717b311..8a05eb1 100644
--- a/docs/source/low.rst
+++ b/docs/source/low.rst
@@ -7,8 +7,6 @@ calls into HDF5 directly. A lot of effort has been put into making even this
component useful in a Python context. It provides the most general interface
to HDF5, including the vast majority of the C library.
-The definitive documentation for this level is available through docstrings.
-`Auto-generated HTML documentation`__ based on these is available.
You'll probably also find the `official HDF5 documentation`__ useful as a guide
to how the library itself operates. In particular, the HDF5 User Guide is
an excellent description of each major component.
@@ -16,6 +14,23 @@ an excellent description of each major component.
__ http://h5py.alfven.org/docs
__ http://hdf.ncsa.uiuc.edu/HDF5/doc/index.html
+Low-level API reference
+=======================
+
+.. toctree::
+ :maxdepth: 2
+
+ low/h5
+ low/h5a
+ low/h5d
+ low/h5f
+ low/h5g
+ low/h5i
+ low/h5p
+ low/h5r
+ low/h5s
+ low/h5t
+ low/h5z
Library organization
====================
diff --git a/docs/source/low/h5.rst b/docs/source/low/h5.rst
new file mode 100644
index 0000000..1afec92
--- /dev/null
+++ b/docs/source/low/h5.rst
@@ -0,0 +1,7 @@
+Module H5
+=========
+
+.. automodule:: h5py.h5
+ :members:
+.. autoclass:: ObjectID
+
diff --git a/docs/source/h5a.rst b/docs/source/low/h5a.rst
similarity index 98%
rename from docs/source/h5a.rst
rename to docs/source/low/h5a.rst
index 2be39e1..f2f59ec 100644
--- a/docs/source/h5a.rst
+++ b/docs/source/low/h5a.rst
@@ -3,3 +3,4 @@ Module H5A
.. automodule:: h5py.h5a
:members:
+
diff --git a/docs/source/h5d.rst b/docs/source/low/h5d.rst
similarity index 100%
rename from docs/source/h5d.rst
rename to docs/source/low/h5d.rst
diff --git a/docs/source/low/h5f.rst b/docs/source/low/h5f.rst
new file mode 100644
index 0000000..e15e149
--- /dev/null
+++ b/docs/source/low/h5f.rst
@@ -0,0 +1,6 @@
+Module H5F
+==========
+
+.. automodule:: h5py.h5f
+ :members:
+
diff --git a/docs/source/low/h5g.rst b/docs/source/low/h5g.rst
new file mode 100644
index 0000000..88f06ad
--- /dev/null
+++ b/docs/source/low/h5g.rst
@@ -0,0 +1,6 @@
+Module H5G
+==========
+
+.. automodule:: h5py.h5g
+ :members:
+
diff --git a/docs/source/low/h5i.rst b/docs/source/low/h5i.rst
new file mode 100644
index 0000000..310a9c4
--- /dev/null
+++ b/docs/source/low/h5i.rst
@@ -0,0 +1,6 @@
+Module H5I
+==========
+
+.. automodule:: h5py.h5i
+ :members:
+
diff --git a/docs/source/low/h5p.rst b/docs/source/low/h5p.rst
new file mode 100644
index 0000000..93cad18
--- /dev/null
+++ b/docs/source/low/h5p.rst
@@ -0,0 +1,6 @@
+Module H5P
+==========
+
+.. automodule:: h5py.h5p
+ :members:
+
diff --git a/docs/source/low/h5r.rst b/docs/source/low/h5r.rst
new file mode 100644
index 0000000..8d9392b
--- /dev/null
+++ b/docs/source/low/h5r.rst
@@ -0,0 +1,6 @@
+Module H5R
+==========
+
+.. automodule:: h5py.h5r
+ :members:
+
diff --git a/docs/source/low/h5s.rst b/docs/source/low/h5s.rst
new file mode 100644
index 0000000..6516cc3
--- /dev/null
+++ b/docs/source/low/h5s.rst
@@ -0,0 +1,6 @@
+Module H5S
+==========
+
+.. automodule:: h5py.h5s
+ :members:
+
diff --git a/docs/source/low/h5t.rst b/docs/source/low/h5t.rst
new file mode 100644
index 0000000..c5dee7d
--- /dev/null
+++ b/docs/source/low/h5t.rst
@@ -0,0 +1,47 @@
+Module H5T
+==========
+
+.. automodule:: h5py.h5t
+ :members:
+
+Module constants
+----------------
+
+::
+
+ NO_CLASS = H5T_NO_CLASS
+ INTEGER = H5T_INTEGER
+ FLOAT = H5T_FLOAT
+ TIME = H5T_TIME
+ STRING = H5T_STRING
+ BITFIELD = H5T_BITFIELD
+ OPAQUE = H5T_OPAQUE
+ COMPOUND = H5T_COMPOUND
+ REFERENCE = H5T_REFERENCE
+ ENUM = H5T_ENUM
+ VLEN = H5T_VLEN
+ ARRAY = H5T_ARRAY
+
+ # Enumeration H5T_sign_t
+ SGN_NONE = H5T_SGN_NONE
+ SGN_2 = H5T_SGN_2
+
+ # Enumeration H5T_order_t
+ ORDER_LE = H5T_ORDER_LE
+ ORDER_BE = H5T_ORDER_BE
+ ORDER_VAX = H5T_ORDER_VAX
+ ORDER_NONE = H5T_ORDER_NONE
+
+ DIR_DEFAULT = H5T_DIR_DEFAULT
+ DIR_ASCEND = H5T_DIR_ASCEND
+ DIR_DESCEND = H5T_DIR_DESCEND
+
+ # Enumeration H5T_str_t
+ STR_NULLTERM = H5T_STR_NULLTERM
+ STR_NULLPAD = H5T_STR_NULLPAD
+ STR_SPACEPAD = H5T_STR_SPACEPAD
+
+ # Enumeration H5T_norm_t
+ NORM_IMPLIED = H5T_NORM_IMPLIED
+ NORM_MSBSET = H5T_NORM_MSBSET
+ NORM_NONE = H5T_NORM_NONE
diff --git a/docs/source/low/h5z.rst b/docs/source/low/h5z.rst
new file mode 100644
index 0000000..228dba1
--- /dev/null
+++ b/docs/source/low/h5z.rst
@@ -0,0 +1,6 @@
+Module H5Z
+==========
+
+.. automodule:: h5py.h5z
+ :members:
+
diff --git a/docs_api/Makefile b/docs_api/Makefile
new file mode 100644
index 0000000..0b09677
--- /dev/null
+++ b/docs_api/Makefile
@@ -0,0 +1,70 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " pickle to make pickle files (usable by e.g. sphinx-web)"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " changes to make an overview over all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+
+clean:
+ -rm -rf build/*
+
+html:
+ mkdir -p build/html build/doctrees
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
+ @echo
+ @echo "Build finished. The HTML pages are in build/html."
+
+pickle:
+ mkdir -p build/pickle build/doctrees
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files or run"
+ @echo " sphinx-web build/pickle"
+ @echo "to start the sphinx-web server."
+
+web: pickle
+
+htmlhelp:
+ mkdir -p build/htmlhelp build/doctrees
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in build/htmlhelp."
+
+latex:
+ mkdir -p build/latex build/doctrees
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in build/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes:
+ mkdir -p build/changes build/doctrees
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
+ @echo
+ @echo "The overview file is in build/changes."
+
+linkcheck:
+ mkdir -p build/linkcheck build/doctrees
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in build/linkcheck/output.txt."
diff --git a/docs/source/automod.py b/docs_api/source/automod.py
similarity index 64%
rename from docs/source/automod.py
rename to docs_api/source/automod.py
index 93d45a2..f2b9388 100644
--- a/docs/source/automod.py
+++ b/docs_api/source/automod.py
@@ -18,9 +18,14 @@ def setup(spx):
lines[:] = final_lines
def proc_sig(app, what, name, obj, options, signature, return_annotation):
- if what in ("function","method") and obj.__doc__.strip().startswith('('):
+
+ def getsig(docstring):
+ """ Get sig, return from a docstring, or None. """
+ if docstring is None or not docstring.strip().startswith('('):
+ return None
+
lines = []
- for line in obj.__doc__.split("\n"):
+ for line in docstring.split("\n"):
if len(line.strip()) == 0:
break
lines.append(line)
@@ -34,6 +39,19 @@ def setup(spx):
if len(sig) == 2: sig = sig[0]+" "+sig[1] # stupid bug in autodoc
return (sig, ret)
+ if what not in ("function", "method"):
+ return None
+
+ sigtuple = getsig(obj.__doc__)
+
+ # If it's a built-in fuction it MUST have a docstring or
+ # Sphinx shits a giant red box into the HTML
+ if sigtuple is None and \
+ (not (hasattr(obj, 'im_func') or hasattr(obj, 'func_code'))):
+ return ('(...)', '')
+
+ return sigtuple
+
spx.connect('autodoc-process-signature', proc_sig)
spx.connect('autodoc-process-docstring', proc_doc)
diff --git a/docs_api/source/conf.py b/docs_api/source/conf.py
new file mode 100644
index 0000000..2496f51
--- /dev/null
+++ b/docs_api/source/conf.py
@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+#
+# h5py documentation build configuration file, created by
+# sphinx-quickstart on Tue Aug 5 14:14:15 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys, os
+
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+#sys.path.append(os.path.abspath('some/directory'))
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+sys.path += [os.path.abspath('.')]
+extensions = ['sphinx.ext.autodoc', 'automod']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+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.3'
+# The full version, including alpha/beta/rc tags.
+release = '0.3.1'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directories, that shouldn't be searched
+# for source files.
+#exclude_dirs = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+html_use_modindex = False
+
+# If false, no index is generated.
+html_use_index = False
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'h5pydoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', 'h5py.tex', 'h5py Documentation',
+ 'Andrew Collette', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+
+
+
+
diff --git a/docs_api/source/index.rst b/docs_api/source/index.rst
new file mode 100644
index 0000000..baff5ce
--- /dev/null
+++ b/docs_api/source/index.rst
@@ -0,0 +1,19 @@
+.. h5py documentation master file, created by sphinx-quickstart on Fri Oct 17 14:45:28 2008.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to h5py's documentation!
+================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/h5py/h5a.pyx b/h5py/h5a.pyx
index 8c65085..29f1d69 100644
--- a/h5py/h5a.pyx
+++ b/h5py/h5a.pyx
@@ -10,10 +10,11 @@
#
#-
-
+__doc__=\
"""
Provides access to the low-level HDF5 "H5A" attribute interface.
"""
+__all__ = ['create','AttrID']
include "config.pxi"
include "sync.pxi"
@@ -212,7 +213,7 @@ def iterate(ObjectID loc not None, object func, int index=0):
Tip: To make your code forward-compatible with later versions of this
function (which supply more arguments to the callback), add an
- additional *args parameter.
+ additional ``*args`` parameter.
"""
if index < 0:
raise ValueError("Starting index must be a non-negative integer.")
diff --git a/h5py/h5d.pyx b/h5py/h5d.pyx
index 30f1ade..48533b0 100644
--- a/h5py/h5d.pyx
+++ b/h5py/h5d.pyx
@@ -292,9 +292,10 @@ cdef class DatasetID(ObjectID):
Determine if space has been allocated for a dataset.
Return value is one of:
- SPACE_STATUS_NOT_ALLOCATED
- SPACE_STATUS_PART_ALLOCATED
- SPACE_STATUS_ALLOCATED
+
+ * SPACE_STATUS_NOT_ALLOCATED
+ * SPACE_STATUS_PART_ALLOCATED
+ * SPACE_STATUS_ALLOCATED
"""
cdef H5D_space_status_t status
H5Dget_space_status(self.id, &status)
diff --git a/h5py/h5f.pyx b/h5py/h5f.pyx
index 68b97d3..4434300 100644
--- a/h5py/h5f.pyx
+++ b/h5py/h5f.pyx
@@ -57,8 +57,12 @@ def open(char* name, unsigned int flags=H5F_ACC_RDWR, PropFAID fapl=None):
""" (STRING name, UINT flags=ACC_RDWR, PropFAID fapl=None)
=> FileID
- Open an existing HDF5 file. Keyword "flags" may be ACC_RWDR or
- ACC_RDONLY. Keyword fapl may be a file access property list.
+ Open an existing HDF5 file. Keyword "flags" may be:
+
+ * ACC_RWDR or
+ * ACC_RDONLY.
+
+ Keyword fapl may be a file access property list.
"""
IF H5PY_DEBUG:
import logging
@@ -72,9 +76,10 @@ def create(char* name, int flags=H5F_ACC_TRUNC, PropFCID fcpl=None,
PropFAID fapl=None)
=> FileID
- Create a new HDF5 file. Keyword "flags" may be either:
- ACC_TRUNC: Truncate an existing file, discarding its data
- ACC_EXCL: Fail if a conflicting file exists
+ Create a new HDF5 file. Keyword "flags" may be:
+
+ * ACC_TRUNC: Truncate an existing file, discarding its data
+ * ACC_EXCL: Fail if a conflicting file exists
To keep the behavior in line with that of Python's built-in functions,
the default is ACC_TRUNC. Be careful!
@@ -91,8 +96,9 @@ def flush(ObjectID obj not None, int scope=H5F_SCOPE_LOCAL):
Tell the HDF5 library to flush file buffers to disk. "obj" may
be the file identifier, or the identifier of any object residing in
the file. Keyword "scope" may be:
- SCOPE_LOCAL: Flush only the given file
- SCOPE_GLOBAL: Flush the entire virtual file
+
+ * SCOPE_LOCAL: Flush only the given file
+ * SCOPE_GLOBAL: Flush the entire virtual file
"""
H5Fflush(obj.id, <H5F_scope_t>scope)
@@ -147,10 +153,10 @@ def get_obj_count(object where=OBJ_ALL, int types=H5F_OBJ_ALL):
Get the number of open objects.
- where: Either a FileID instance representing an HDF5 file, or the
- special constant OBJ_ALL, to count objects in all files.
+ * where: Either a FileID instance representing an HDF5 file, or the
+ special constant OBJ_ALL, to count objects in all files.
- type: Specify what kinds of object to include. May be one of OBJ_*,
+ * type: Specify what kinds of object to include. May be one of OBJ_*,
or any bitwise combination (e.g. OBJ_FILE | OBJ_ATTR).
The special value OBJ_ALL matches all object types, and
@@ -224,10 +230,11 @@ cdef class FileID(ObjectID):
file identifiers are provided as functions in the h5f module.
Properties:
- name: File name on disk
+ * name: File name on disk
- Hashable: Yes, unique to the file (but not the access mode)
- Equality: Hash comparison
+ Behavior:
+ * Hashable: Yes, unique to the file (but not the access mode)
+ * Equality: Hash comparison
"""
property name:
diff --git a/h5py/version.py b/h5py/version.py
new file mode 100644
index 0000000..62ebd1c
--- /dev/null
+++ b/h5py/version.py
@@ -0,0 +1,11 @@
+import h5 as _h5
+
+version_tuple = _h5._version_tuple
+version = "%d.%d.%d" % version_tuple
+
+hdf5_version_tuple = _h5._hdf5_version_tuple
+hdf5_version = "%d.%d.%d" % hdf5_version_tuple
+
+api_version_tuple = _h5._api_version_tuple
+api_version = "%d.%d" % api_version_tuple
+
--
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