Added core docs template

docs/conf.py

@@ -38,7 +38,7 @@ def get_version():
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinxcontrib.plantuml',
-    #    'sphinx.ext.intersphinx',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
 ]
 
@@ -110,6 +110,10 @@ def which(name, flags=os.X_OK):
     # install it
     subprocess.call(["fc-cache", "-vf", fontdir])
 
+napoleon_use_ivar = True
+
+autoclass_content = "both"
+
 autodoc_member_order = 'bysource'
 
 # Add any paths that contain templates here, relative to this directory.
@@ -136,9 +140,9 @@ def which(name, flags=os.X_OK):
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# intersphinx_mapping = {
-#    'python': ('http://python.readthedocs.org/en/v2.7.2/', None),
-#}
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/2.7/', None),
+}
 
 # -- Options for HTML output ----------------------------------------------
 

docs/dev/core.rst

@@ -0,0 +1,12 @@
+Core API
+========
+
+.. module:: malcolm.core
+
+Many classes in Malcolm use the same baseclass that implements some logging
+methods:
+
+.. autoclass:: Loggable
+    :members:
+
+Add more classes here...

docs/index.rst

@@ -41,6 +41,7 @@ The main documentation for the site is organised into a few sections:
 
     dev/tags
     dev/types
+    dev/core
     dev/contributing
     dev/release_notes
 

malcolm/core/__init__.py

@@ -0,0 +1 @@
+from loggable import Loggable

malcolm/core/loggable.py

@@ -5,6 +5,10 @@ class Loggable(object):
     """Utility class that provides a named logger for a class instance"""
 
     def __init__(self, logger_name):
+        """
+        Args:
+            logger_name (str): Name of the logger to appear in log messages
+        """
         super(Loggable, self).__init__()
         # The name that we will pass to the logger
         self._logger_name = None
@@ -16,10 +20,27 @@ def set_logger_name(self, logger_name):
         """Change the name of the logger that log_* should call
 
         Args:
-            logger_name (str): Name of the logger
+            logger_name (str): Name of the logger to appear in log messages
         """
         self._logger_name = logger_name
         self._logger = logging.getLogger(self._logger_name)
-        # set self.log_debug = self._logger.debug etc.
-        for n in "debug warning info error exception".split():
-            setattr(self, "log_%s" % n, getattr(self._logger, n))
+
+    def log_debug(self, msg, *args, **kwargs):
+        """Call :meth:`logging.Logger.debug`"""
+        self._logger.debug(msg, *args, **kwargs)
+
+    def log_info(self, msg, *args, **kwargs):
+        """Call :meth:`logging.Logger.info`"""
+        self._logger.info(msg, *args, **kwargs)
+
+    def log_warning(self, msg, *args, **kwargs):
+        """Call :meth:`logging.Logger.warning`"""
+        self._logger.warning(msg, *args, **kwargs)
+
+    def log_error(self, msg, *args, **kwargs):
+        """Call :meth:`logging.Logger.error`"""
+        self._logger.error(msg, *args, **kwargs)
+
+    def log_exception(self, msg, *args, **kwargs):
+        """Call :meth:`logging.Logger.exception`"""
+        self._logger.exception(msg, *args, **kwargs)

tests/test_core/test_loggable.py

@@ -21,10 +21,12 @@ def test_init(self, mock_logging):
         mock_logging.getLogger.assert_called_once_with("foo")
 
     @patch("malcolm.core.loggable.logging")
-    def test_debug_calls_logger_function(self, mock_logging):
+    def test_calls_logger_function(self, mock_logging):
         l = Loggable("bar")
-        l.log_debug("hello")
-        l._logger.debug.assert_called_once_with("hello")
+        for n in "debug info warning error exception".split():
+            m = getattr(l, "log_%s" % n)
+            m("hello", n)
+            getattr(l._logger, n).assert_called_once_with("hello", n)
 
 if __name__ == "__main__":
     unittest.main(verbosity=2)