Merge pull request statsmodels#6126 from bashtage/more-docs

DOC: Update templates and add missing API functions

Author: bashtage

docs/source/_templates/autosummary/attribute.rst

@@ -4,7 +4,5 @@
 
 .. currentmodule:: {{ module }}
 
-attribute
-
 .. auto{{ objtype }}:: {{ objname }}
 

docs/source/_templates/autosummary/member.rst

@@ -4,8 +4,6 @@
 
 .. currentmodule:: {{ module }}
 
-member
-
 .. auto{{ objtype }}:: {{ objname }}
 
 

docs/source/_templates/autosummary/method.rst

@@ -4,7 +4,5 @@
 
 .. currentmodule:: {{ module }}
 
-method
-
 .. auto{{ objtype }}:: {{ objname }}
 

docs/source/gee.rst

@@ -69,6 +69,8 @@ Model Class
    :toctree: generated/
 
    GEE
+   NominalGEE
+   OrdinalGEE
 
 .. module:: statsmodels.genmod.qif
    :synopsis: Quadratic inference functions

docs/source/gettingstarted.rst

@@ -175,6 +175,17 @@ plot of partial regression for a set of regressors by:
     sm.graphics.plot_partregress('Lottery', 'Wealth', ['Region', 'Literacy'],
                                  data=df, obs_labels=False)
 
+Documentation
+-------------
+Documentation can be accessed from an IPython session
+using :func:`~statsmodels.tools.web.webdoc`.
+
+.. autosummary::
+   :nosignatures:
+   :toctree: generated/
+
+   ~statsmodels.tools.web.webdoc
+
 More
 ----
 

statsmodels/genmod/generalized_estimating_equations.py

@@ -472,8 +472,8 @@ def _check_args(endog, exog, groups, time, offset, exposure):
 class GEE(base.Model):
 
     __doc__ = (
-        "    Estimation of marginal regression models using Generalized\n"
-        "    Estimating Equations (GEE).\n" + _gee_init_doc %
+        "    Marginal Regression Model using Generalized Estimating "
+        "Equations.\n" + _gee_init_doc %
         {'extra_params': base._missing_param_doc,
          'family_doc': _gee_family_doc,
          'example': _gee_example})
@@ -2346,8 +2346,7 @@ class GEEResultsWrapper(lm.RegressionResultsWrapper):
 class OrdinalGEE(GEE):
 
     __doc__ = (
-        "    Estimation of ordinal response marginal regression models\n"
-        "    using Generalized Estimating Equations (GEE).\n" +
+        "    Ordinal Response Marginal Regression Model using GEE\n" +
         _gee_init_doc % {'extra_params': base._missing_param_doc,
                          'family_doc': _gee_ordinal_family_doc,
                          'example': _gee_ordinal_example})
@@ -2628,8 +2627,7 @@ class OrdinalGEEResultsWrapper(GEEResultsWrapper):
 class NominalGEE(GEE):
 
     __doc__ = (
-        "    Estimation of nominal response marginal regression models\n"
-        "    using Generalized Estimating Equations (GEE).\n" +
+        "    Nominal Response Marginal Regression Model using GEE.\n" +
         _gee_init_doc % {'extra_params': base._missing_param_doc,
                          'family_doc': _gee_nominal_family_doc,
                          'example': _gee_nominal_example})

statsmodels/tools/tests/test_web.py

@@ -1,22 +1,35 @@
-from statsmodels.tools.web import _generate_url, webdoc
-from statsmodels.regression.linear_model import OLS
-from numpy import array
 import pytest
+from numpy import array
+
+from statsmodels.regression.linear_model import OLS
+from statsmodels.tools.web import _generate_url, webdoc
+
 
 class TestWeb(object):
+    stable = 'https://www.statsmodels.org/stable/'
+    devel = 'https://www.statsmodels.org/devel/'
+
     def test_string(self):
-        url = _generate_url('arch',True)
-        assert url == 'https://www.statsmodels.org/stable/search.html?q=arch&check_keywords=yes&area=default'
-        url = _generate_url('arch',False)
-        assert url == 'https://www.statsmodels.org/devel/search.html?q=arch&check_keywords=yes&area=default'
-        url = _generate_url('dickey fuller',False)
-        assert url == 'https://www.statsmodels.org/devel/search.html?q=dickey+fuller&check_keywords=yes&area=default'
+        url = _generate_url('arch', True)
+        assert url == self.stable + 'search.html?q=' \
+                                    'arch&check_keywords=yes&area=default'
+        url = _generate_url('arch', False)
+        assert url == self.devel + 'search.html?q=' \
+                                   'arch&check_keywords=yes&area=default'
+        url = _generate_url('dickey fuller', False)
+        assert url == (self.devel +
+                       'search.html?q='
+                       'dickey+fuller&check_keywords=yes&area=default')
 
     def test_function(self):
         url = _generate_url(OLS, True)
-        assert url == 'https://www.statsmodels.org/stable/generated/statsmodels.regression.linear_model.OLS.html'
+        assert url == (self.stable
+                       + 'generated/'
+                         'statsmodels.regression.linear_model.OLS.html')
         url = _generate_url(OLS, False)
-        assert url == 'https://www.statsmodels.org/devel/generated/statsmodels.regression.linear_model.OLS.html'
+        assert url == (self.devel
+                       + 'generated/'
+                         'statsmodels.regression.linear_model.OLS.html')
 
     def test_nothing(self):
         url = _generate_url(None, True)

statsmodels/tools/tools.py

@@ -74,11 +74,11 @@ def drop_missing(Y, X=None, axis=1):
 # TODO: add name validator (ie., bad names for datasets.grunfeld)
 def categorical(data, col=None, dictnames=False, drop=False):
     """
-    Construct a dummy matrix given an array of categorical variables.
+    Construct a dummy matrix from categorical variables
 
     Parameters
     ----------
-    data : array
+    data : array_like
         A structured array, recarray, array, Series or DataFrame.  This can be
         either a 1d vector of the categorical variable or a 2d array with
         the column specifying the categorical variable specified by the col
@@ -98,14 +98,15 @@ def categorical(data, col=None, dictnames=False, drop=False):
 
     Returns
     -------
-    dummy_matrix, [dictnames, optional]
+    dummy_matrix : array_like
         A matrix of dummy (indicator/binary) float variables for the
-        categorical data.  If dictnames is True, then the dictionary
-        is returned as well.
+        categorical data.
+    dictnames :  dict[int, str], optional
+        Mapping between column numbers and categorical names.
 
     Notes
     -----
-    This returns a dummy variable for EVERY distinct variable.  If a
+    This returns a dummy variable for *each* distinct variable.  If a
     a structured or recarray is provided, the names for the new variable is the
     old variable name - underscore - category name.  So if the a variable
     'vote' had answers as 'yes' or 'no' then the returned array would have to
@@ -120,11 +121,11 @@ def categorical(data, col=None, dictnames=False, drop=False):
     Univariate examples
 
     >>> import string
-    >>> string_var = [string.ascii_lowercase[0:5], \
-                      string.ascii_lowercase[5:10], \
-                      string.ascii_lowercase[10:15], \
-                      string.ascii_lowercase[15:20],   \
-                      string.ascii_lowercase[20:25]]
+    >>> string_var = [string.ascii_lowercase[0:5],
+    ...               string.ascii_lowercase[5:10],
+    ...               string.ascii_lowercase[10:15],
+    ...               string.ascii_lowercase[15:20],
+    ...               string.ascii_lowercase[20:25]]
     >>> string_var *= 5
     >>> string_var = np.asarray(sorted(string_var))
     >>> design = sm.tools.categorical(string_var, drop=True)
@@ -137,8 +138,9 @@ def categorical(data, col=None, dictnames=False, drop=False):
     With a structured array
 
     >>> num = np.random.randn(25,2)
-    >>> struct_ar = np.zeros((25,1), dtype=[('var1', 'f4'),('var2', 'f4'),  \
-                    ('instrument','f4'),('str_instr','a5')])
+    >>> struct_ar = np.zeros((25,1),
+    ...                      dtype=[('var1', 'f4'),('var2', 'f4'),
+    ...                             ('instrument','f4'),('str_instr','a5')])
     >>> struct_ar['var1'] = num[:,0][:,None]
     >>> struct_ar['var2'] = num[:,1][:,None]
     >>> struct_ar['instrument'] = instr[:,None]

statsmodels/tools/web.py

@@ -2,6 +2,8 @@
 Provides a function to open the system browser to either search or go directly
 to a function's reference
 """
+from statsmodels.compat.pandas import deprecate_kwarg
+
 import webbrowser
 from urllib.parse import urlencode
 
@@ -10,7 +12,7 @@
 BASE_URL = 'https://www.statsmodels.org/'
 
 
-def _generate_url(arg, stable):
+def _generate_url(func, stable):
     """
     Parse inputs and return a correctly formatted URL or raises ValueError
     if the input is not understandable
@@ -21,15 +23,15 @@ def _generate_url(arg, stable):
     else:
         url += 'devel/'
 
-    if arg is None:
+    if func is None:
         return url
-    elif isinstance(arg, str):
+    elif isinstance(func, str):
         url += 'search.html?'
-        url += urlencode({'q': arg})
+        url += urlencode({'q': func})
         url += '&check_keywords=yes&area=default'
     else:
         try:
-            func = arg
+            func = func
             func_name = func.__name__
             func_module = func.__module__
             if not func_module.startswith('statsmodels.'):
@@ -41,15 +43,16 @@ def _generate_url(arg, stable):
     return url
 
 
-def webdoc(arg=None, stable=None):
+@deprecate_kwarg('arg', 'func')
+def webdoc(func=None, stable=None):
     """
     Opens a browser and displays online documentation
 
     Parameters
     ----------
-    arg, optional : str or statsmodels function
+    func : {str, callable}
         Either a string to search the documentation or a function
-    stable, optional : bool
+    stable : 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
@@ -58,18 +61,27 @@ def webdoc(arg=None, stable=None):
     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
+
+    Documentation site
+
+    >>> sm.webdoc()
+
+    Search for glm in docs
+
+    >>> sm.webdoc('glm')
+
+    Go to current generated help for OLS
+
+    >>> sm.webdoc(sm.OLS, stable=False)
 
     Notes
     -----
-    By default, open stable documentation if the current version of statsmodels
-    is a release.  Otherwise opens the development documentation.
+    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 = __version__ if 'dev' not in __version__ else stable
-    url_or_error = _generate_url(arg, stable)
+    url_or_error = _generate_url(func, stable)
     webbrowser.open(url_or_error)
     return None