Merge pull request #258 from dlyssenko/provide_docstring_decorator

fixing doc build issues, errors, and providing docstring decorator

docs/Makefile

@@ -8,7 +8,7 @@ PAPER         =
 BUILDDIR      = _build
 APIDIR   	    = api_modules
 CLIENTDIR     = client_modules
-CWD						:= $(shell pwd)
+CWD						:= '$(shell pwd)'
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)

docs/conf.py

@@ -20,7 +20,7 @@
 # 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, '../pyeapi')
+sys.path.insert(0, os.path.abspath('..') )
 
 # -- General configuration ------------------------------------------------
 

docs/generate_modules.py

@@ -1,5 +1,4 @@
-#!/usr/bin/python
-from __future__ import absolute_import, division, print_function
+#!/usr/bin/python3
 
 from os import listdir, path, makedirs
 from os.path import isfile, join, exists

pyeapi/api/ipinterfaces.py

@@ -49,6 +49,7 @@
 import re
 
 from pyeapi.api import EntityCollection
+from pyeapi.utils import _interpolate_docstr
 
 IP_MTU_MIN = 68
 IP_MTU_MAX = 65535
@@ -217,6 +218,7 @@ def set_address(self, name, value=None, default=False, disable=False):
                                              default=default, disable=disable))
         return self.configure(commands)
 
+    @_interpolate_docstr( 'IP_MTU_MIN', 'IP_MTU_MAX', __name__ )
     def set_mtu(self, name, value=None, default=False, disable=False):
         """ Configures the interface IP MTU
 
@@ -225,7 +227,7 @@ def set_mtu(self, name, value=None, default=False, disable=False):
                 config to
 
             value (integer): The MTU value to set the interface to.  Accepted
-                values include IP_MTU_MIN (68) to IP_MTU_MAX (65535)
+                values include IP_MTU_MIN to IP_MTU_MAX
 
             default (bool): Configures the mtu parameter to its default
                 value using the EOS CLI default command

pyeapi/api/ospf.py

@@ -55,16 +55,20 @@ def get(self, vrf=None):
                 vrf (str): VRF name to return OSPF routing config for
            Returns:
                dict:
-                    keys: router_id (int): OSPF router-id
-                          vrf (str): VRF of the OSPF process
-                          networks (dict): All networks that
-                                           are advertised in OSPF
-                          ospf_process_id (int): OSPF proc id
-                          redistribution (dict): All protocols that
-                                                 are configured to be
-                                                 redistributed in OSPF
-                          shutdown (bool): Gives the current shutdown
-                                           off the process
+                    keys:
+                         router_id (int): OSPF router-id
+
+                         vrf (str): VRF of the OSPF process
+                         networks (dict): All networks that
+                         are advertised in OSPF
+
+                         ospf_process_id (int): OSPF proc id
+
+                         redistribution (dict): All protocols that
+                         are configured to be redistributed in OSPF
+
+                         shutdown (bool): Gives the current shutdown
+                         off the process
         """
         match = '^router ospf .*'
         if vrf:

pyeapi/utils.py

@@ -257,3 +257,37 @@ def __init__(self, *cli):
         assert len( cli ) >= 2, 'must be initialized with 2 or more arguments'
         self.variants = [ v if not isinstance(v,
             str) and isinstance(v, Iterable) else [v] for v in cli ]
+
+
+
+def _interpolate_docstr( *tkns ):
+    """Docstring decorator.
+    SYNOPSIS:
+    
+         MIN_MTU=68
+         MAX_MTU=65535
+         
+         @_interpolate_docstr( 'MIN_MTU', 'MAX_MTU', __name__ )
+         def mtu_check( val ):
+            "check mtu against its min value (MIN_MTU) and max value (MAX_MTU)"
+            ...
+         
+         print( mtu_check.__doc__ )
+         check mtu against its min value (68) and max value (65535)
+    
+    Note: `__name__` must be provided as the last argument because the decorator
+    could be imported, thus the current (importing) module needs to be resolved
+    """
+    def docstr_decorator( user_fn ):
+        """update user_fn_wrapper doc string with the interpolated user_fn's
+        """
+        def user_fn_wrapper( *args, **kwargs ):
+            return user_fn( *args, **kwargs )
+        module = sys.modules[ tkns[-1] ]
+        docstr = user_fn.__doc__
+        for tkn in tkns[:-1]:
+            sval = str( getattr(module, tkn) )
+            docstr = docstr.replace( tkn, sval )
+        user_fn_wrapper.__doc__ = docstr
+        return user_fn_wrapper
+    return docstr_decorator