add docstrings and static html documentation

src/materials.py

@@ -25,15 +25,32 @@ EPILOG = """\
 
 
 def absolute_path(filename):
-  """\
-  Get full path.
+  """Get full path.
+
+  :param filename: the file name to use
+  :type filename: str
+
+  :returns: str -- the absolute path
   """
   return os.path.join(os.path.abspath(os.path.dirname(__file__)), filename)
 
 
 def read_dir(directory, exclude=None, fullpath=False, extension=True):
-  """\
-  Read all files in directory as list
+  """Read all files in directory as list.
+
+  :param directory: the directory to read
+  :type directory: str
+
+  :param exclude: file names that should be excluded from the list (default value = None)
+  :type exclude: list or None
+
+  :param fullpath: get full path (default value = False)
+  :type fullpath: bool
+
+  :param extension: include file extension (default value = True)
+  :type extension: bool
+
+  :returns: list -- the list of files in the directory
   """
   result = []
   for file_name in os.listdir(directory):
@@ -47,24 +64,40 @@ def read_dir(directory, exclude=None, fullpath=False, extension=True):
 
 
 def print_list(data_list):
-  """\
-  Print list
+  """Print list.
+
+  :param data_list: the list to print
+  :type data_list: list
   """
   for data in data_list:
     print(data)
 
 
 def read_file(filename):
-  """\
-  Read file as string
+  """Read file as string.
+
+  :param filename: the name of the file to read
+  :type filename: str
+
+  :returns: str -- the content of the file
   """
   with open(filename) as data_file:
     return data_file.read()
 
 
 def read_material(materialname, fullpath=True):
-  """\
-  Read material file as string
+  """Read material file as string.
+
+  :param materialname: the name of the material to read
+  :type materialname: str
+
+  :param fullpath: use full path (default value = True)
+  :type fullpath: bool
+
+  :returns: str -- the content of the material
+
+  :raises OSError: raises os exception
+  :raises IOError: raises io exception
   """
   filename = os.path.join('data', materialname + '.json')
   if fullpath:
@@ -78,8 +111,12 @@ def read_material(materialname, fullpath=True):
 
 
 def load_material(materialname):
-  """\
-  Read material file and convert it to a Python object.
+  """Read material file and convert it to a Python object.
+
+  :param materialname: the material name to load
+  :type materialname: str
+
+  :returns: list or dict -- the content of the material
   """
   import json
 
@@ -87,8 +124,10 @@ def load_material(materialname):
 
 
 def print_material(data):
-  """\
-  Print material data (Python object).
+  """Print material data (Python object).
+
+  :param data: the material data
+  :type data: str or list or dict
   """
   import pprint
 
@@ -97,14 +136,26 @@ def print_material(data):
 
 
 def search_keys(data, keys):
-  """\
-  Search for json keys in string data
+  """Search for json keys in string data.
+
+  :param data: the data to search in
+  :type data: str
+
+  :param keys: the key to search for
+  :type keys: str or list or None
+
+  :results: dict -- the key value pair matching the given keys in the data
   """
   from json import loads
 
   def find_values(key, json_repr):
-    """\
-    Find values inside json string
+    """Find values inside json string.
+
+    :param key: the key to find in json string
+    :type key: int or str
+
+    :param json_repr: the json string to search in
+    :type json_repr: str
     """
     results = []
     def _decode_dict(a_dict):
@@ -128,8 +179,16 @@ def search_keys(data, keys):
 
 
 def print_dict(data_dict, print_keys=True, prespaces=0):
-  """\
-  Print one dimensional dict data.
+  """Print one dimensional dict data.
+
+  :param data_dict: the dict data to print
+  :type data_dict: dict
+
+  :param print_keys: print the keys (default value = True)
+  :type print_keys: bool
+
+  :param prespaces: number of spaces as prefix (default value = 0)
+  :type prespaces: int
   """
   for key, values in data_dict.items():
     for value in values:
@@ -139,9 +198,14 @@ def print_dict(data_dict, print_keys=True, prespaces=0):
 
 
 def print_quantity(quantity, prespaces=0):
-  """\
-  Print quantity.
-  Either a number or a list of two elements, the first the magnitude and the second the unit
+  """Print quantity.
+
+  :param quantity: the quantity to print. Either a number or a list of two
+    elements, the first the magnitude and the second the unit.
+  :type quantity: int or float or list
+
+  :param prespaces: number of spaces as prefix (default value = 0)
+  :type prespaces: int
   """
   if isinstance(quantity, list) and len(quantity) == 2:
     print(prespaces*' ' + '%s' % quantity[0] + ' ' + quantity[1])
@@ -150,9 +214,17 @@ def print_quantity(quantity, prespaces=0):
 
 
 def get_value(data, element):
-  """\
-  Get value of nested dictionary.
-  If element is itself a list of length one, the element of the list is returned
+  """Get value of nested dictionary.
+  If data element is itself a list of length one, the element of the list is
+  returned.
+
+  :param data: the data
+  :type data: dict
+
+  :param key: the key to get
+  :type key: str
+
+  :returns: int or float or list or dict -- element value of the dict
   """
   keys = element.split('/')
   for key in keys:
@@ -163,8 +235,7 @@ def get_value(data, element):
 
 
 def main():
-  """\
-  Main function
+  """Main function.
   """
   import argparse