Merge pull request #286 from mpsonntag/1.4doc

Documentation updates for 1.4 release

Author: jgrewe

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011-2014, German Neuroinformatics Node (G-Node)
+Copyright (c) 2011-2018, German Neuroinformatics Node (G-Node)
 
 All rights reserved.
 

README.rst

@@ -17,6 +17,15 @@ available on `GitHub <https://github.com/G-Node/python-odml>`_. If you are not f
 with the version control system **git**, but still want to use it, have a look at the
 documentation available on the `git-scm website <https://git-scm.com/>`_.
 
+
+Breaking changes
+----------------
+
+odML Version 1.4 introduced breaking format and API changes compared to the previous
+versions of odML. Files saved in the previous format versions can be converted to a 1.4
+compatible format using the version converter from the odml/tools package.
+
+
 Dependencies
 ------------
 

doc/base-classes.rst

@@ -10,16 +10,13 @@ Again each Property can have multiple Values.
 
 The odml Module contains wrappers, that are shortcuts for creating the main objects::
 
-    >>> from odml import Document, Section, Property, Value
+    >>> from odml import Document, Section, Property
     >>> Document(version=0.9, author="Kermit")
     <Doc 0.9 by Kermit (0 sections)>
 
 Several modules exist to extend the implementation.
 The ones included in the library are those:
 
-* :py:mod:`odml.tools.event` provides event capabilities, allowing to add change-listeners to objects
-* :py:mod:`odml.tools.nodes` provides a tree-interface used by the gui with functions like next() and position()
-
 Document
 --------
 .. autoclass:: odml.doc.BaseDocument
@@ -40,11 +37,3 @@ Property
    :members:
    :inherited-members:
    :undoc-members:
-
-Value
------
-.. autoclass:: odml.value.BaseValue
-   :members:
-   :inherited-members:
-   :undoc-members:
-

doc/conf.py

@@ -11,17 +11,20 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import os
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
+
+
 class DocStringInheritor(type):
-    '''A variation on
+    """A variation on
     http://groups.google.com/group/comp.lang.python/msg/26f7b4fcb4d66c95
     by Paul McGuire
-    '''
+    """
     def __new__(meta, name, bases, clsdict):
         if not('__doc__' in clsdict and clsdict['__doc__']):
             for mro_cls in (mro_cls for base in bases for mro_cls in base.mro()):
@@ -38,8 +41,6 @@ def __new__(meta, name, bases, clsdict):
                         attribute.__doc__=doc
                         break
         return type.__new__(meta, name, bases, clsdict)
-#import odml.doc
-#odml.doc.BaseDocument = DocStringInheritor("BaseDocument", odml.doc.BaseDocument.__bases__, dict(odml.doc.BaseDocument.__dict__))
 
 # -- General configuration -----------------------------------------------------
 
@@ -61,7 +62,7 @@ def __new__(meta, name, bases, clsdict):
 
 # General information about the project.
 project = u'python-odml'
-copyright = u'2011, Hagen Fritsch'
+copyright = u'2011-2018, German Neuroinformatics Node (G-Node); based on work by Hagen Fritsch'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/example_odMLs/THGTTG.odml

@@ -2,6 +2,7 @@
 <?xml-stylesheet  type="text/xsl" href="odmlTerms.xsl"?>
 <?xml-stylesheet  type="text/xsl" href="odml.xsl"?>
 <odML version="1.1">
+  <repository>http://portal.g-node.org/odml/terminologies/v1.1/terminologies.xml</repository>
   <version>42</version>
   <section>
     <name>TheCrew</name>

doc/example_odMLs/ex_1.odml

@@ -3,7 +3,7 @@
 <?xml-stylesheet  type="text/xsl" href="odml.xsl"?>
 <odML version="1.1">
   <author>D. N. Adams</author>
-  <repository>http://portal.g-node.org/odml/terminologies/v1.0/terminologies.xml</repository>
+  <repository>http://portal.g-node.org/odml/terminologies/v1.1/terminologies.xml</repository>
   <section>
     <property>
       <type>person</type>

doc/example_odMLs/ex_1.rdf

@@ -83,5 +83,5 @@ odml:d98afe9b-3982-44bf-9373-12aaa4798628 a rdf:Bag ;
         "Tricia Marie McMillan",
         "Zaphod Beeblebrox" .
 
-<https://g-node.org/projects/odml-rdf#7e0e07c7-7501-454e-88e7-cfa072db94c1> a <http://portal.g-node.org/odml/terminologies/v1.0/terminologies.xml> .
+<https://g-node.org/projects/odml-rdf#7e0e07c7-7501-454e-88e7-cfa072db94c1> a <http://portal.g-node.org/odml/terminologies/v1.1/terminologies.xml> .
 

doc/example_odMLs/ex_2.odml

@@ -2,7 +2,7 @@
 <?xml-stylesheet  type="text/xsl" href="odmlTerms.xsl"?>
 <?xml-stylesheet  type="text/xsl" href="odml.xsl"?>
 <odML version="1.1">
-  <repository>http://portal.g-node.org/odml/terminologies/v1.0/terminologies.xml</repository>
+  <repository>http://portal.g-node.org/odml/terminologies/v1.1/terminologies.xml</repository>
   <section>
     <definition>Information on the crew</definition>
     <section>

doc/example_odMLs/thgttg.py

@@ -7,26 +7,31 @@
 @author: zehl
 """
 
+import datetime
+import os
+import odml
 import sys
+
+
 if len(sys.argv) != 2:
-	print("You have to provide the absolute path to the odml-python module ", 
-	      "your command line.")
-else:
-	odml_pythonpath = sys.argv[-1]
-sys.path.append(odml_pythonpath)
+    print("Please provide an existing directory for the example odml file.")
+    quit()
 
-import os
-import odml
-import datetime
+output_directory = sys.argv[-1]
+if not os.path.isdir(output_directory):
+    print("Please provide an existing directory for the example odml file.")
+    quit()
 
+save_to = os.path.join(output_directory, "THGTTG.odml")
 
-odmlrepo = 'http://portal.g-node.org/odml/terminologies/v1.0/terminologies.xml'
+
+odmlrepo = 'http://portal.g-node.org/odml/terminologies/v1.1/terminologies.xml'
 
 # CREATE A DOCUMENT
 doc = odml.Document(author="D. N. Adams",
                     date=datetime.date(1979, 10, 12),
-                    version=42)
-#                    repository=odmlrepo)
+                    version=42,
+                    repository=odmlrepo)
 
 # CREATE AND APPEND THE MAIN SECTIONs
 doc.append(odml.Section(name="TheCrew",
@@ -304,7 +309,5 @@
                             dtype=odml.DType.string,
                             definition="Manufacturer of robots"))
 
-save_to = os.path.join(odml_pythonpath, "doc", "example_odMLs", "THGTTG.odml")
-
 odml.save(doc, save_to)