diff --git a/.gitignore b/.gitignore index 8257bc927..2258d2351 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,9 @@ manifest.json # Auto-generated tutorials /docs/source/tutorials/ +# Auto-generated from sphinx.ext.autosummary +/docs/source/_autosummary + ### Python ### # Byte-compiled / optimized / DLL files __pycache__/ diff --git a/docs/Makefile b/docs/Makefile index f01af1f8b..0832de2bb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -46,7 +46,7 @@ help: @echo " apidoc to build RST from source code" clean: - -rm -rf $(BUILDDIR)/* $(RSTDIR)/$(PKGNAME)*.rst $(GALLERYDIR)/*.hdf5 $(GALLERYDIR)/*.sqlite $(RSTDIR)/tutorials + -rm -rf $(BUILDDIR)/* $(RSTDIR)/$(PKGNAME)*.rst $(GALLERYDIR)/*.hdf5 $(GALLERYDIR)/*.sqlite $(RSTDIR)/_autosummary $(RSTDIR)/tutorials html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/make.bat b/docs/make.bat index dc48f5b3e..8c60fe202 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -54,6 +54,7 @@ if "%1" == "clean" ( del /q %GALLERYDIR%\*.hdf5 del /q %GALLERYDIR%\*.sqlite rmdir /q /s %RSTDIR%\tutorials + rmdir /q /s %RSTDIR%\_autosummary goto end ) diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 000000000..9e5ccf2f5 --- /dev/null +++ b/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,61 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + :noindex: + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Module Attributes') }} + + .. autosummary:: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/docs/source/api_docs.rst b/docs/source/api_docs.rst index 119c86401..aef289335 100644 --- a/docs/source/api_docs.rst +++ b/docs/source/api_docs.rst @@ -4,20 +4,104 @@ API Documentation ================== -.. toctree:: - :maxdepth: 2 - :caption: HDMF Modules - - Common data types - Base container classes - Build layer - Specification layer - I/O layer - Data I/O utilities - Development utilities - Validation utilities - Testing utilities - Full list of HDMF package contents +.. include:: _autosummary/hdmf.rst + + +Common Data Structures +====================== + +The `hdmf-common-schema `_ defines a collection of reusable data +structures---e.g., :py:class:`~hdfm.common.table.DynamicTable` for extensible data tables---that are useful +for defining new data standards. The following modules define the user API for these common data types +defined in `hdmf-common-schema`_ + +.. autosummary:: + :toctree: _autosummary + :recursive: + + hdmf.common + hdmf.common.io + +I/O +==== + +The following modules define I/O backend functionality for reading/writing data. HDMF defines with +:py:class:`~hdmf.backends.io.HDMFIO` a generic, extensible interface for I/O backends. +:py:class:~hdmf.backends.io.hdf5.h5tools.HDF5IO` then implements :py:class:`~hdmf.backends.io.HDMFIO` to +support storing HDMF data in HDF5. HDMFs decouples the I/O backends from the data API and format schema. +I.e., an I/O backend only needs to be able to interact with :py:mod:`~hdmf.build.builders` describing +common data primitives (e.g., Groups, Datasets, Attributes etc.), but does not need to know anything +about the specifics of a particiular data standard. + +.. autosummary:: + :toctree: _autosummary + :recursive: + + hdmf.backends + hdmf.backends.hdf5 + +Data translation +================ + +The role of the data translation is to translate and integrate data between data APIs (i.e., Containers), +format schema, and data I.O. Given a data Container the data translation generates :py:mod:`~hdmf.build.builders` +for I/O using the relevant :py:mod:`~hdmf.build.objectmapper` to translate attributes from the container +to definitions in a format schema. Conversely, given a collection of :py:mod:`~hdmf.build.builders`, the +data translation will construct corresponding frontend :py:mod:`~hdmf.container` using +:py:mod:`~hdmf.build.objectmapper` to translate fields in the format schema to :py:mod:`~hdmf.container` attributes. +The :py:mod:`~hdmf.build.manager` then defines functionality to manage the build process to translate containers +to builders and vice-versa. + +.. autosummary:: + :toctree: _autosummary + :recursive: + + hdmf.build + +Data Format Specification +========================= + +The following modules define data structures and functionality for specifying format schema +:py:mod:`~hdmf.spec.spec`, managing and reading collections of schema definitions via :py:mod:`~hdmf.spec.namespace` +and :py:mod:`~hdmf.spec.catalog`, and writing schema via :py:mod:`~hdmf.spec.write`. + +.. autosummary:: + :toctree: _autosummary + :recursive: + + hdmf.spec + +Data API +======== + +The modules contained directly at the main hdmf level are used to create user APIs for data standards and +to enhance interaction with data. + +.. autosummary:: + :toctree: _autosummary + :recursive: + + hdmf + hdmf.container + hdmf.utils + hdmf.data_utils + hdmf.array + hdmf.region + hdmf.monitor + hdmf.query + hdmf.region + +Testing and Validation Utilities +================================ + +Components used to facilitate the definition of unit tests, validation of data files, and validation of format schema. + +.. autosummary:: + :toctree: _autosummary + :recursive: + + hdmf.validate + hdmf.testing :ref:`modindex` diff --git a/docs/source/conf.py b/docs/source/conf.py index caff737e7..966576919 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -49,6 +49,7 @@ # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ "sphinx.ext.autodoc", + "sphinx.ext.autosummary", "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinx_gallery.gen_gallery", @@ -79,6 +80,9 @@ "zarr": ("https://zarr.readthedocs.io/en/stable/", None), } +# Enable sphinx.ext.autosummary to generate automatic summary for pynwb API docs +autosummary_generate = True + # these links cannot be checked in github actions linkcheck_ignore = [ "https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key", diff --git a/src/hdmf/__init__.py b/src/hdmf/__init__.py index 6fc72a117..3bbc22327 100644 --- a/src/hdmf/__init__.py +++ b/src/hdmf/__init__.py @@ -1,3 +1,8 @@ +""" +The Hierarchical Data Modeling Framework, or HDMF, is a Python package for working with hierarchical data. +It provides APIs for specifying data models, reading and writing data to different storage backends, +and representing data with Python objects. +""" from . import query from .backends.hdf5.h5_utils import H5Dataset, H5RegionSlicer from .container import Container, Data, DataRegion, HERDManager @@ -12,6 +17,7 @@ is_method=False, ) def get_region_slicer(**kwargs): + """get_region_slicer is deprecated and will be removed in HDMF 4.0""" import warnings # noqa: E402 warnings.warn( diff --git a/src/hdmf/backends/__init__.py b/src/hdmf/backends/__init__.py index 030a2daee..0f29afdc0 100644 --- a/src/hdmf/backends/__init__.py +++ b/src/hdmf/backends/__init__.py @@ -1 +1,2 @@ +"""Package for defining new I/O backends for HDMF and using existing backends, e.g., for HDF5. """ from . import hdf5 diff --git a/src/hdmf/backends/hdf5/__init__.py b/src/hdmf/backends/hdf5/__init__.py index 6abfc8c85..faa9e6207 100644 --- a/src/hdmf/backends/hdf5/__init__.py +++ b/src/hdmf/backends/hdf5/__init__.py @@ -1,3 +1,4 @@ +"""HDF5 backend for reading and writing HDMF data files""" from . import h5_utils, h5tools from .h5_utils import H5RegionSlicer, H5DataIO from .h5tools import HDF5IO, H5SpecWriter, H5SpecReader diff --git a/src/hdmf/backends/hdf5/h5tools.py b/src/hdmf/backends/hdf5/h5tools.py index 05ce36e13..323954e32 100644 --- a/src/hdmf/backends/hdf5/h5tools.py +++ b/src/hdmf/backends/hdf5/h5tools.py @@ -1,3 +1,4 @@ +"""Module implementing the main HDF5IO HDF5 backend for HDMF""" import logging import os.path import warnings @@ -35,6 +36,7 @@ class HDF5IO(HDMFIO): + """HDMF I/O backend for reading and writing HDMF builders to/from HDF5 files.""" __ns_spec_path = 'namespace' # path to the namespace dataset within a namespace group diff --git a/src/hdmf/backends/io.py b/src/hdmf/backends/io.py index 35023066f..42974d223 100644 --- a/src/hdmf/backends/io.py +++ b/src/hdmf/backends/io.py @@ -1,3 +1,4 @@ +"""Module defining the base classes for defining an HDMF I/O backend""" from abc import ABCMeta, abstractmethod import os from pathlib import Path @@ -10,6 +11,17 @@ class HDMFIO(metaclass=ABCMeta): + """ + Base class for implementing a new I/O backend for HDMF + + Derived classes must implement the following abstract methods: + + * :py:meth:`~hdmf.backends.io.HDMFIO.read_builder` + * :py:meth:`~hdmf.backends.io.HDMFIO.write_builder` + * :py:meth:`~hdmf.backends.io.HDMFIO.open` + * :py:meth:`~hdmf.backends.io.HDMFIO.close` + * :py:meth:`~hdmf.backends.io.HDMFIO.can_read` + """ @staticmethod @abstractmethod diff --git a/src/hdmf/backends/warnings.py b/src/hdmf/backends/warnings.py index 77a711584..c00cf2741 100644 --- a/src/hdmf/backends/warnings.py +++ b/src/hdmf/backends/warnings.py @@ -1,3 +1,6 @@ +"""Collection of warning classes for HDMF I/O""" + + class BrokenLinkWarning(UserWarning): """ Raised when a group has a key with a None value. diff --git a/src/hdmf/build/__init__.py b/src/hdmf/build/__init__.py index ea5d21152..0bea066a1 100644 --- a/src/hdmf/build/__init__.py +++ b/src/hdmf/build/__init__.py @@ -1,3 +1,4 @@ +"""Package for managing the data translation process between frontend Containers and I/O Builders based on the schema""" from .builders import Builder, DatasetBuilder, GroupBuilder, LinkBuilder, ReferenceBuilder, RegionBuilder from .classgenerator import CustomClassGenerator, MCIClassGenerator from .errors import (BuildError, OrphanContainerBuildError, ReferenceTargetNotBuiltError, ContainerConfigurationError, diff --git a/src/hdmf/build/builders.py b/src/hdmf/build/builders.py index 73c683bbd..32fc936c6 100644 --- a/src/hdmf/build/builders.py +++ b/src/hdmf/build/builders.py @@ -1,3 +1,4 @@ +"""Module defining the Builder datastrucures used to represent data for I/O, e.g., GroupBuilder, DatasetBuilder etc.""" import copy as _copy import itertools as _itertools import posixpath as _posixpath @@ -12,6 +13,7 @@ class Builder(dict, metaclass=ABCMeta): + """Base interface class for all Builder types""" @docval({'name': 'name', 'type': str, 'doc': 'the name of the group'}, {'name': 'parent', 'type': 'hdmf.build.builders.Builder', 'doc': 'the parent builder of this Builder', @@ -75,6 +77,8 @@ def __repr__(self): class BaseBuilder(Builder, metaclass=ABCMeta): + """Base class for Builders that support attributes, e.g,. DatasetBuilder and GroupBuilder """ + __attribute = 'attributes' # self dictionary key for attributes @docval({'name': 'name', 'type': str, 'doc': 'The name of the builder.'}, diff --git a/src/hdmf/build/classgenerator.py b/src/hdmf/build/classgenerator.py index d2e7d4fc0..af7bce8fa 100644 --- a/src/hdmf/build/classgenerator.py +++ b/src/hdmf/build/classgenerator.py @@ -1,3 +1,4 @@ +"""Module iplementing functionaltiy for automatically generating Container classes from type Specs""" from copy import deepcopy from datetime import datetime, date diff --git a/src/hdmf/build/manager.py b/src/hdmf/build/manager.py index a26de3279..c87e1e606 100644 --- a/src/hdmf/build/manager.py +++ b/src/hdmf/build/manager.py @@ -1,3 +1,4 @@ +"""Collection of classes used to manage the data translation process, e.g., BuildManager and TypeMap. """ import logging from collections import OrderedDict, deque from copy import copy diff --git a/src/hdmf/build/map.py b/src/hdmf/build/map.py index 5267609f5..57fd09c40 100644 --- a/src/hdmf/build/map.py +++ b/src/hdmf/build/map.py @@ -1,3 +1,4 @@ +"""DEPRECATED: Classes in map.py should be imported from :py:mod:`~hdmf.build` instead""" # this prevents breaking of code that imports these classes directly from map.py from .manager import Proxy, BuildManager, TypeSource, TypeMap # noqa: F401 from .objectmapper import ObjectMapper # noqa: F401 diff --git a/src/hdmf/build/objectmapper.py b/src/hdmf/build/objectmapper.py index fed678d41..4c4060a69 100644 --- a/src/hdmf/build/objectmapper.py +++ b/src/hdmf/build/objectmapper.py @@ -1,3 +1,5 @@ +"""Module defining the base ObjectMapper for mapping between Spec objects and AbstractContainer attributes""" + import logging import re import warnings diff --git a/src/hdmf/common/__init__.py b/src/hdmf/common/__init__.py index 248ca1095..48e95955c 100644 --- a/src/hdmf/common/__init__.py +++ b/src/hdmf/common/__init__.py @@ -1,5 +1,5 @@ -'''This package will contain functions, classes, and objects -for reading and writing data in according to the HDMF-common specification +''' +Package for reading and writing data in accordance with the HDMF-common-schema specification ''' import os.path from copy import deepcopy @@ -96,6 +96,11 @@ def _dec(cls): def __get_resources(): + """ + Get the available schema resources + + :returns: Dict with information about the available namespace YAML file(s) + """ try: from importlib.resources import files except ImportError: @@ -112,7 +117,7 @@ def __get_resources(): def _get_resources(): - # LEGACY: Needed to support legacy implementation. + """LEGACY: Needed to support legacy implementation, use :py:meth:`~hdmf.common.__get_resources` instead. """ return __get_resources() @@ -129,6 +134,11 @@ def load_namespaces(**kwargs): def available_namespaces(): + """ + Get the names of the namespaces available in the NamespaceCatalog in the global __TYPE_MAP. + + :return: Tuple of strings with the names of the available namespaces + """ return __TYPE_MAP.namespace_catalog.namespaces diff --git a/src/hdmf/common/io/__init__.py b/src/hdmf/common/io/__init__.py index 27c13df27..38ccb73fb 100644 --- a/src/hdmf/common/io/__init__.py +++ b/src/hdmf/common/io/__init__.py @@ -1,3 +1,6 @@ +""" +Object mapper definitions for mapping hdmf-common Containers to Builders and vice-verse +""" from . import multi from . import table from . import resources diff --git a/src/hdmf/common/io/alignedtable.py b/src/hdmf/common/io/alignedtable.py index 3ff7f8d3f..e98f509ad 100644 --- a/src/hdmf/common/io/alignedtable.py +++ b/src/hdmf/common/io/alignedtable.py @@ -1,3 +1,4 @@ +"""Object mapper definitions for types implemented in :py:mod:`~hdmf.common.alignedtable`""" from .. import register_map from ..alignedtable import AlignedDynamicTable from .table import DynamicTableMap diff --git a/src/hdmf/common/io/multi.py b/src/hdmf/common/io/multi.py index c2493255d..b06279ac9 100644 --- a/src/hdmf/common/io/multi.py +++ b/src/hdmf/common/io/multi.py @@ -1,3 +1,4 @@ +"""Object mapper definitions for types implemented in :py:mod:`~hdmf.common.multi`""" from .. import register_map from ..multi import SimpleMultiContainer from ...build import ObjectMapper diff --git a/src/hdmf/common/io/resources.py b/src/hdmf/common/io/resources.py index 673a65f38..b9212ab5c 100644 --- a/src/hdmf/common/io/resources.py +++ b/src/hdmf/common/io/resources.py @@ -1,3 +1,4 @@ +"""Object mapper definitions for types implemented in :py:mod:`~hdmf.common.resources`""" from .. import register_map from ..resources import HERD, KeyTable, FileTable, ObjectTable, ObjectKeyTable, EntityTable, EntityKeyTable from ...build import ObjectMapper diff --git a/src/hdmf/common/io/table.py b/src/hdmf/common/io/table.py index 50395ba24..1185609db 100644 --- a/src/hdmf/common/io/table.py +++ b/src/hdmf/common/io/table.py @@ -1,3 +1,4 @@ +"""Object mapper definitions for types implemented in :py:mod:`~hdmf.common.table`""" from .. import register_map from ..table import DynamicTable, VectorData, VectorIndex, DynamicTableRegion from ...build import ObjectMapper, BuildManager, CustomClassGenerator diff --git a/src/hdmf/common/multi.py b/src/hdmf/common/multi.py index 598b3cc93..fca35a23a 100644 --- a/src/hdmf/common/multi.py +++ b/src/hdmf/common/multi.py @@ -1,3 +1,4 @@ +"""Module for multi-Container interfaces that usually manage multiple instances of set of particular Container types""" from . import register_class from ..container import Container, Data, MultiContainerInterface from ..utils import docval, popargs, AllowPositional diff --git a/src/hdmf/common/resources.py b/src/hdmf/common/resources.py index fdca4bb81..520923963 100644 --- a/src/hdmf/common/resources.py +++ b/src/hdmf/common/resources.py @@ -1,3 +1,4 @@ +"""Module with data structures for managing links to external resources, e.g., ontologies or persistent identifiers""" import pandas as pd import numpy as np from . import register_class, EXP_NAMESPACE diff --git a/src/hdmf/common/sparse.py b/src/hdmf/common/sparse.py index db38d12e8..684cf0651 100644 --- a/src/hdmf/common/sparse.py +++ b/src/hdmf/common/sparse.py @@ -1,3 +1,4 @@ +"""Module with data structures for stroring sparse matrices """ import scipy.sparse as sps from . import register_class from ..container import Container diff --git a/src/hdmf/container.py b/src/hdmf/container.py index ca2c5252b..a5e4a6d71 100644 --- a/src/hdmf/container.py +++ b/src/hdmf/container.py @@ -1,3 +1,4 @@ +"""Module with base classes for creating frontend data APIs based on the concept of Containers""" import types from abc import abstractmethod from collections import OrderedDict diff --git a/src/hdmf/data_utils.py b/src/hdmf/data_utils.py index 23f0b4019..9cfcf5140 100644 --- a/src/hdmf/data_utils.py +++ b/src/hdmf/data_utils.py @@ -1,3 +1,4 @@ +"""Module with data utilities, e.g., dataset I/O wrappers for iterative write and for defining I/O properties""" import copy import math from abc import ABCMeta, abstractmethod diff --git a/src/hdmf/region.py b/src/hdmf/region.py index 9feeba401..890a29154 100644 --- a/src/hdmf/region.py +++ b/src/hdmf/region.py @@ -1,3 +1,4 @@ +"""Module with dataset wrapper classes used to support lazy evaluation of data slicing operations on read.""" from abc import ABCMeta, abstractmethod from operator import itemgetter diff --git a/src/hdmf/spec/__init__.py b/src/hdmf/spec/__init__.py index 09ad6d073..c6f250314 100644 --- a/src/hdmf/spec/__init__.py +++ b/src/hdmf/spec/__init__.py @@ -1,3 +1,4 @@ +"""Package for creating format schema, managing collections of scheme definitions, and reading/writing schema.""" from .catalog import SpecCatalog from .namespace import NamespaceCatalog, SpecNamespace, SpecReader from .spec import (AttributeSpec, DatasetSpec, DtypeHelper, DtypeSpec, GroupSpec, LinkSpec, diff --git a/src/hdmf/spec/catalog.py b/src/hdmf/spec/catalog.py index 636eb3bc0..f828de346 100644 --- a/src/hdmf/spec/catalog.py +++ b/src/hdmf/spec/catalog.py @@ -1,3 +1,4 @@ +"""Catalog for managing a collection of format specifications""" import copy from collections import OrderedDict diff --git a/src/hdmf/spec/namespace.py b/src/hdmf/spec/namespace.py index a2ae0bd37..e520ed8e0 100644 --- a/src/hdmf/spec/namespace.py +++ b/src/hdmf/spec/namespace.py @@ -1,3 +1,4 @@ +"""Collection of classes for specifying , managing, and reading namespaces, e.g, SpecNamespace, NamespaceCatalog etc.""" import os.path import ruamel.yaml as yaml import string @@ -29,7 +30,7 @@ class SpecNamespace(dict): """ - A namespace for specifications + Specify a namespace for specifications """ __types_key = 'data_types' @@ -173,7 +174,7 @@ def build_namespace(cls, **spec_dict): class SpecReader(metaclass=ABCMeta): - + """Base interface for implementing reader classes for format specifications""" @docval({'name': 'source', 'type': str, 'doc': 'the source from which this reader reads from'}) def __init__(self, **kwargs): self.__source = getargs('source', kwargs) @@ -192,6 +193,7 @@ def read_namespace(self): class YAMLSpecReader(SpecReader): + """Read specification from YAML""" @docval({'name': 'indir', 'type': str, 'doc': 'the path spec files are relative to', 'default': '.'}) def __init__(self, **kwargs): @@ -223,6 +225,7 @@ def __get_spec_path(self, spec_path): class NamespaceCatalog: + """A catalog for storing multiple Namespaces""" @docval({'name': 'group_spec_cls', 'type': type, 'doc': 'the class to use for group specifications', 'default': GroupSpec}, diff --git a/src/hdmf/spec/spec.py b/src/hdmf/spec/spec.py index 585fc6494..b9297029c 100644 --- a/src/hdmf/spec/spec.py +++ b/src/hdmf/spec/spec.py @@ -1,3 +1,4 @@ +"""Collection of classes for representing and creating format specifications, e.g. GroupSpec, DatasetSpec etc.""" import re from abc import ABCMeta from collections import OrderedDict @@ -19,11 +20,19 @@ class DtypeHelper: - # Dict where the keys are the primary data type and the values are list of strings with synonyms for the dtype - # make sure keys are consistent between hdmf.spec.spec.DtypeHelper.primary_dtype_synonyms, - # hdmf.build.objectmapper.ObjectMapper.__dtypes, hdmf.build.manager.TypeMap._spec_dtype_map, - # hdmf.validate.validator.__allowable, and backend dtype maps - # see https://hdmf-schema-language.readthedocs.io/en/latest/description.html#dtype + """ + Utility class with helper functions and attributes used when specifying data types. + + This class is usually not instantiated but defines a collection of static helpers. + """ + + """ + Dict where the keys are the primary data type and the values are list of strings with synonyms for the dtype + make sure keys are consistent between hdmf.spec.spec.DtypeHelper.primary_dtype_synonyms, + hdmf.build.objectmapper.ObjectMapper.__dtypes, hdmf.build.manager.TypeMap._spec_dtype_map, + hdmf.validate.validator.__allowable, and backend dtype maps + see https://hdmf-schema-language.readthedocs.io/en/latest/description.html#dtype + """ primary_dtype_synonyms = { 'float': ["float", "float32"], 'double': ["double", "float64"], @@ -176,6 +185,7 @@ def path(self): class RefSpec(ConstructableDict): + """Specification for object- and region-reference data types used with DatasetSpec and AttributedSpec""" __allowable_types = ('object', 'region') @docval(*_ref_args) @@ -792,6 +802,7 @@ def build_const_args(cls, spec_dict): class LinkSpec(Spec): + """Specification for Links""" @docval(*_link_args) def __init__(self, **kwargs): diff --git a/src/hdmf/spec/write.py b/src/hdmf/spec/write.py index d397c9f26..ef843f7f8 100644 --- a/src/hdmf/spec/write.py +++ b/src/hdmf/spec/write.py @@ -1,3 +1,8 @@ +""" +Collection of classes to export format specifications to YAML/JSON + +For reading namespace from file see :py:mod:`~hdmf.spec.namespace` +""" import copy import json import os.path diff --git a/src/hdmf/testing/__init__.py b/src/hdmf/testing/__init__.py index cdf746388..c345dc49f 100644 --- a/src/hdmf/testing/__init__.py +++ b/src/hdmf/testing/__init__.py @@ -1,2 +1,3 @@ +"""Package with utility functions and classes to facilitate the creation of tests""" from .testcase import TestCase, H5RoundTripMixin from .utils import remove_test_file diff --git a/src/hdmf/utils.py b/src/hdmf/utils.py index 5e0b61539..c33a05144 100644 --- a/src/hdmf/utils.py +++ b/src/hdmf/utils.py @@ -1,3 +1,6 @@ +""" +Module with utility functions and classes for creating frontend data functionality (e.g., docval or LabelledDiced) +""" import collections import copy as _copy import types diff --git a/src/hdmf/validate/__init__.py b/src/hdmf/validate/__init__.py index cb515cea8..34212d7e2 100644 --- a/src/hdmf/validate/__init__.py +++ b/src/hdmf/validate/__init__.py @@ -1,3 +1,4 @@ +"""Package defining functionality for validating files generated with HDMF""" from . import errors from .errors import * # noqa: F403 from .validator import ValidatorMap, Validator, AttributeValidator, DatasetValidator, GroupValidator