ENH: Quick access to online documentation

statsmodels/api.py

@@ -30,6 +30,7 @@
 from .iolib.smpickle import load_pickle as load
 
 from .tools.print_version import show_versions
+from .tools.web import webdoc
 
 import os
 

statsmodels/compat/python.py

@@ -5,6 +5,7 @@
 import functools
 import itertools
 import sys
+import urllib
 
 PY3 = (sys.version_info[0] >= 3)
 PY3_2 = sys.version_info[:2] == (3, 2)
@@ -32,6 +33,7 @@
     import urllib.parse
     from urllib.request import HTTPError, urlretrieve
 
+
 if PY3:
     import io
     bytes = bytes
@@ -90,6 +92,7 @@ def lfilter(*args, **kwargs):
     urlopen = urllib.request.urlopen
     urljoin = urllib.parse.urljoin
     urlretrieve = urllib.request.urlretrieve
+    urlencode = urllib.parse.urlencode
     string_types = str
     input = input
 
@@ -130,6 +133,7 @@ def open_latin1(filename, mode='r'):
 
     urlopen = urllib2.urlopen
     urljoin = urlparse.urljoin
+    urlencode = urllib.urlencode
     HTTPError = urllib2.HTTPError
     string_types = basestring
 

statsmodels/tools/tests/test_web.py

@@ -0,0 +1,33 @@
+from statsmodels.tools.web import _generate_url, webdoc
+from statsmodels.regression.linear_model import OLS
+from unittest import TestCase
+from nose.tools import assert_equal, assert_raises
+from numpy import array
+
+class TestWeb(TestCase):
+    def test_string(self):
+        url = _generate_url('arch',True)
+        assert_equal(url, 'http://statsmodels.sourceforge.net/stable/search.html?q=arch&check_keywords=yes&area=default')
+        url = _generate_url('arch',False)
+        assert_equal(url, 'http://statsmodels.sourceforge.net/devel/search.html?q=arch&check_keywords=yes&area=default')
+        url = _generate_url('dickey fuller',False)
+        assert_equal(url, 'http://statsmodels.sourceforge.net/devel/search.html?q=dickey+fuller&check_keywords=yes&area=default')
+
+    def test_function(self):
+        url = _generate_url(OLS, True)
+        assert_equal(url, 'http://statsmodels.sourceforge.net/stable/generated/statsmodels.regression.linear_model.OLS.html')
+        url = _generate_url(OLS, False)
+        assert_equal(url, 'http://statsmodels.sourceforge.net/devel/generated/statsmodels.regression.linear_model.OLS.html')
+
+    def test_nothing(self):
+        url = _generate_url(None, True)
+        assert_equal(url, 'http://statsmodels.sourceforge.net/stable/')
+        url = _generate_url(None, False)
+        assert_equal(url, 'http://statsmodels.sourceforge.net/devel/')
+
+    def test_errors(self):
+        assert_raises(ValueError, webdoc, array, True)
+        assert_raises(ValueError, webdoc, 1, False)
+
+
+

statsmodels/tools/web.py

@@ -0,0 +1,77 @@
+"""
+Provides a function to open the system browser to either search or go directly
+to a function's reference
+"""
+import webbrowser
+
+from statsmodels.compat.python import urlencode
+from statsmodels.version import release
+
+BASE_URL = 'http://statsmodels.sourceforge.net/'
+
+
+def _generate_url(arg, stable):
+    """
+    Parse inputs and return a correctly formatted URL or an error if the input
+    is not understandable
+    """
+    url = BASE_URL
+    if stable:
+        url += 'stable/'
+    else:
+        url += 'devel/'
+
+    if arg is None:
+        return url
+    elif type(arg) is str:
+        url += 'search.html?'
+        url += urlencode({'q': arg})
+        url += '&check_keywords=yes&area=default'
+    else:
+        try:
+            func = arg
+            func_name = func.__name__
+            func_module = func.__module__
+            if not func_module.startswith('statsmodels.'):
+                return ValueError('Function must be from statsmodels')
+            url += 'generated/'
+            url += func_module + '.' + func_name + '.html'
+        except:
+            return ValueError('Input not understood')
+    return url
+
+
+def webdoc(arg=None, stable=None):
+    """
+    Opens a browser and displays online documentation
+
+    Parameters
+    ----------
+    arg, optional : string or statsmodels function
+        Either a string to search the documentation or a function
+    stable, optional : bool
+        Flag indicating whether to use the stable documentation (True) or
+        the development documentation (False).  If not provided, opens
+        the stable documentation if the current version of statsmodels is a
+        release
+
+    Examples
+    --------
+    >>> import statsmodels.api as sm
+    >>> sm.webdoc()  # Documention site
+    >>> sm.webdoc('glm')  # Search for glm in docs
+    >>> sm.webdoc(sm.OLS, stable=False)  # Go to generated help for OLS, devel
+
+    Notes
+    -----
+    By default, open stable documentation if the current version of statsmodels
+    is a release.  Otherwise opens the development documentation.
+
+    Uses the default system browser.
+    """
+    stable = release if stable is None else stable
+    url_or_error = _generate_url(arg, stable)
+    if isinstance(url_or_error, ValueError):
+        raise url_or_error
+    webbrowser.open(url_or_error)
+    return None