Merge pull request #447 from achilleas-k/docs-redesign

Docs redesign

docs/source/conf.py

@@ -21,13 +21,7 @@
 # html options
 htmlhelp_basename       = 'nixio'
 try:
-    import alabaster
-
-    html_theme_path     = [alabaster.get_path()]
-    html_static_path    = ['_static']
-    extensions          += ['alabaster']
-    html_theme          = 'alabaster'
-
+    html_theme          = 'sphinx_rtd_theme'
     html_sidebars       = {
         '**': [
                 'about.html', 'navigation.html', 'searchbox.html',

docs/source/index.rst

@@ -2,14 +2,13 @@
 NIXIO Python Package for NIX Datafiles
 ======================================
 
-The nixpy module contains the python binding to the nix c++ library. In order
-to use it you also have to have the nix library installed. 
+The NIXPy module is a reimplementation of the `NIX C++ library <https://nixio.readthedocs.io>`_.
 
 
 Getting started
 ===============
 
-The following sections should help you getting started with nixpy. 
+The following sections should help you getting started with NIXPy.
 
 .. toctree::
    :maxdepth: 2
@@ -18,19 +17,24 @@ The following sections should help you getting started with nixpy.
    overview
    tutorial
 
-API Documentation
-=================
-The API documentation for Data and Metadata
+High Level API Reference
+========================
+
+User API documentation for Data and Metadata
 
 .. toctree::
    :maxdepth: 2
 
-   api_data
-   api_metadata
+   user_api
+
+
+Advanced
+========
+
+Internal NIXIO API Developer Documentation
+------------------------------------------
 
-Internal API Developer Documentation
-====================================
-The API documentation of internal modules, for developers
+The API documentation of internal modules, for NIXPy developers.
 
 .. toctree::
    :maxdepth: 2

docs/source/overview.rst

@@ -1,6 +1,6 @@
-======== 
+========
 Overview
-======== 
+========
 
 Design Principles
 =================
@@ -9,7 +9,7 @@ The design of the data model tries to draw on similarities of
 different data types and structures and and come up with *entities*
 that are as generic and versatile as meaningful. At the same time we
 aim for clearly established links between different entities to keep the
-model as expressive as possible. 
+model as expressive as possible.
 
 Most entities of the NIX-model have a *name* and a *type* field which
 are meant to provide information about the entity. While the name can
@@ -64,7 +64,7 @@ unique id (UUID).
 
 
 Storing data
-"""""""""""" 
+""""""""""""
 
 The heart of our data model is an entity called **DataArray**. This is
 the entity that actually stores all data. It can take n-dimensional
@@ -85,7 +85,7 @@ Using this call will create a **DataArray**, set name and type, set
 the *dataType* according to the dtype of the passed data, and store
 the data in the file. You can also create empty **DataArrays** to take
 up data-to-be-recorded. In this case you have to provide the space
-that will be needed in advance. 
+that will be needed in advance.
 
 .. code-block:: python
 
@@ -142,7 +142,7 @@ irregular intervals, and (iii) data that belongs to categories.
         dim.unit = "s"
 
 The **SampledDimension** can also be used to desribe space dimensions,
-e.g. in case of images. 
+e.g. in case of images.
 
 If the data was sampled at irregular intervals the sample points of
 the x-axis are defined using the *ticks* property of a
@@ -364,3 +364,17 @@ the tag's position is given in *ms*.
 
         #for compound units we can do
         tag.units=["mV/cm"]
+
+
+Metadata
+========
+
+The model for storing metadata is largely equivalent to the `odML`_ (open metadata Markup Language) model. In brief: the
+model consists of so called Properties that contain Values much like a key-value pair (plus some additional fields).
+These Properties can be grouped into Sections which themselves can be nested to built a tree-structure. Sections are
+defined by a name and a type (e.g. a stimulus-type section will contain information that is related to a stimulus).
+The basic feature of the odML approach is that it defines the model but not the items that are described or the terms
+that are used in this. On the other hand where standardization is required each Section can be based on an
+odML-terminology that standardizes without restricting to the terms defined within the terminology.
+
+.. _odML: http://www.frontiersin.org/Neuroinformatics/10.3389/fninf.2011.00016

docs/source/api_data.rst → docs/source/user_api.rst

@@ -1,8 +1,6 @@
-==========================
-API Documentation for Data
-==========================
-
-TODO write something about the data model
+========================
+High Level API Reference
+========================
 
 
 File
@@ -256,3 +254,60 @@ Group API
     :inherited-members:
     :undoc-members:
 
+
+Section
+=======
+
+Metadata stored in a NIX file can be accessed directly from an open file.
+
+Create and delete sub sections
+------------------------------
+
+.. code-block:: python
+   :linenos:
+
+   sub = section.create_section("a name", "type")
+   del section.sections[sub]
+
+Add and remove properties
+-------------------------
+
+Properties  can be created using the create_property method. Existing properties can be accessed and deleted
+directly from the respective section.
+
+.. code-block:: python
+   :linenos:
+
+   section.create_property("one", [1])
+   section.create_property("two", [2])
+
+   # iterate over properties
+   for p in section:
+      print(p)
+
+   # access by name
+   one = section["one"]
+
+   # convert properties into a dict
+   dct = dict(section.items())
+
+   # delete properties
+   del section["one"]
+   del section["two"]
+   
+Section API
+-----------
+
+.. autoclass:: nixio.Section
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+Property
+========
+
+.. autoclass:: nixio.Property
+    :members:
+    :inherited-members:
+    :undoc-members:
+

nixio/info.json

@@ -3,7 +3,7 @@
     "STATUS": "Release",
     "RELEASE": "1.5.dev Release",
     "AUTHOR": "Christian Kellner, Adrian Stoewer, Andrey Sobolev, Jan Grewe, Balint Morvai, Achilleas Koutsou",
-    "COPYRIGHT": "2014-2019, German Neuroinformatics Node, Christian Kellner, Adrian Stoewer, Andrey Sobolev, Jan Grewe, Balint Morvai, Achilleas Koutsou",
+    "COPYRIGHT": "2014-2020, German Neuroinformatics Node, Christian Kellner, Adrian Stoewer, Andrey Sobolev, Jan Grewe, Balint Morvai, Achilleas Koutsou",
     "CONTACT": "[email protected]",
     "BRIEF": "Python reimplementation of NIXIO (http://g-node.github.io/nix/)",
     "HOMEPAGE": "https://github.com/G-Node/nixpy"