Changeset 1858

Timestamp:

08/05/10 11:46:40 (14 years ago)

Author:

Malte Marquarding

Message:

Adde more API documentation

Location:

trunk

Files:

• doc/source/api.rst (modified) (2 diffs)
• doc/source/conf.py (modified) (1 diff)
• doc/source/developer/index.rst (modified) (1 diff)
• doc/source/developer/scantable.rst (modified) (1 diff)
• python/asapplotter.py (modified) (4 diffs)
• python/env.py (modified) (4 diffs)
• python/logging.py (modified) (6 diffs)
• python/parameters.py (modified) (1 diff)

trunk/doc/source/api.rst

@@ -2 +2 @@
 API documentation
 =================
-
-Module :mod:`asap.logging`
-==========================
-
-.. automodule:: asap.logging
-   :members:
-   :undoc-members:
-
 
 Module :mod:`asap.scantable`
@@ -18 +10 @@
 ..   :undoc-members:
 ..   :inherited-members:
+
+Module :mod:`asap.env`
+======================
+
+.. automodule:: asap.env
+   :members:
+..   :undoc-members:
+
+Module :mod:`asap.parameters`
+=============================
+
+.. automodule:: asap.parameters
+   :members:
+   :undoc-members:
+
+Module :mod:`asap.logging`
+==========================
+
+.. automodule:: asap.logging
+   :members:
+..   :undoc-members:
+

trunk/doc/source/conf.py

@@ -209 +209 @@
 autoclass_content = "both"
 
+todo_include_todos = True
+
 # -- Options for manual page output --------------------------------------------
 

trunk/doc/source/developer/index.rst

@@ -7 +7 @@
 
    scantable
+   todo

trunk/doc/source/developer/scantable.rst

@@ -237 +237 @@
 * **FORMATTEDNAME** - *String()*
 
+.. todo:: add all sub-table descriptions
 
 ========================

trunk/python/asapplotter.py

@@ -14 +14 @@
     By default the plotter is set up to plot polarisations
     'colour stacked' and scantables across panels.
-    Note:
+
+    .. note::
+
         Currenly it only plots 'spectra' not Tsys or
         other variables.
+
     """
     def __init__(self, visible=None , **kwargs):
@@ -113 +116 @@
         self._plotter.tidy()
         self._plotter.show(hardrefresh=False)
-        print_log()
         return
 
@@ -352 +354 @@
 
     def set_panelling(self, what=None):
+        """Set the 'panelling' mode i.e. which type of spectra should be
+        spread across different panels.
+        """
+
         mode = what
         if mode is None:
@@ -382 +388 @@
 
     def set_stacking(self, what=None):
+        """Set the 'stacking' mode i.e. which type of spectra should be
+        overlayed.
+        """
         mode = what
         if mode is None:

trunk/python/env.py

@@ +1 @@
+"""This module has various functions for environment specific setings.
+"""
 __all__ = ["is_casapy", "is_ipython", "setup_env", "get_revision"]
 
@@ -7 +9 @@
 
 def is_casapy():
+    """Are we running inside casapy?"""
     try:
         from taskinit import casalog
@@ -14 +17 @@
 
 def is_ipython():
+    """Are we running inside IPython?"""
     return 'IPython' in sys.modules.keys()
 
 def setup_env():
+    """Set-up environment variables for casa and initialise ~/.asap on first
+    use.
+    """
     # Set up CASAPATH and first time use of asap i.e. ~/.asap/*
     plf = None
@@ -59 +66 @@
 
 def get_revision():
+    """Get the revision of the software. Only useful within casapy."""
     if not is_casapy:
         return ' unknown '

trunk/python/logging.py

@@ -1 @@
-__all__ = ["asaplog", "print_log", "print_log_dec"]
+"""This module presents a logging abstraction layer on top of casa.
+"""
+__all__ = ["asaplog", "print_log", "print_log_dec", "AsapLogger"]
 
 from asap.env import is_casapy
@@ -10 +12 @@
 
 
-class _asaplog(object):
-    """Wrapper object to allow for both casapy and asap logging"""
+class AsapLogger(object):
+    """Wrapper object to allow for both casapy and asap logging.
+
+    Inside casapy this will connect to `taskinit.casalog`. Otherwise it will
+    create its own casa log sink.
+
+    .. note:: Do instantiate a new one - use the :obj:`asaplog` instead.
+    
+    """
     def __init__(self):
         self._enabled = False
@@ -25 +34 @@
         """Post the messages to the logger. This will clear the buffered
         logs.
+
+        Parameters:
+
+            level:  The log level (severity). One of INFO, WARN, ERROR.
+
         """
         if not self._enabled:
@@ -41 +55 @@
 
     def push(self, msg, newline=True):
-        """Push logs into the buffer. post needs to be called to send them."""
+        """Push logs into the buffer. post needs to be called to send them.
+
+        Parameters:
+
+            msg:        the log message (string)
+
+            newline:    should we terminate with a newline (default yes)
+
+        """
         from asap import rcParams
         if self._enabled:
@@ -58 +80 @@
         self._enabled = flag
 
-asaplog = _asaplog()
+asaplog = AsapLogger()
+"""Default asap logger"""
 
 def print_log_dec(f, level='INFO'):
+    """Decorator which posts log at completion of the wrapped method.
+    Example::
+
+        @print_log_dec
+        def test(self):
+            do_stuff()
+            asaplog.push('testing...', False)
+            do_more_stuff()
+            asaplog.push('finished')
+    """
     @wraps_dec(f)
     def wrap_it(*args, **kw):
@@ -69 +102 @@
 
 def print_log(level='INFO'):
-    """Alias for asaplog.post."""
+    """Alias for asaplog.post(level)"""
     asaplog.post(level)

trunk/python/parameters.py

@@ +1 @@
+"""This module provides functions to set up resource parameters (rc).
+These can be set in a file .asaprc or using functions.
+"""
 __all__ = ["rc", "list_rcparameters", "rcParams", "rcParamsDefault"]