DOC: Restructure the documentation

Restuture the docs to have a simpler structure

Author: bashtage

CONTRIBUTING.rst

@@ -69,5 +69,5 @@ offers much more detailed information about the process.
 License
 ~~~~~~~
 
-Statsmodels is released under the
+statsmodels is released under the
 `Modified (3-clause) BSD license <https://www.opensource.org/licenses/BSD-3-Clause>`_.

LICENSE.txt

@@ -4,7 +4,7 @@ All rights reserved.
 Copyright (c) 2006-2008 Scipy Developers.
 All rights reserved.
 
-Copyright (c) 2009-2018 Statsmodels Developers.
+Copyright (c) 2009-2018 statsmodels Developers.
 All rights reserved.
 
 
@@ -16,7 +16,7 @@ modification, are permitted provided that the following conditions are met:
   b. Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
-  c. Neither the name of Statsmodels nor the names of its contributors
+  c. Neither the name of statsmodels nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.
 

README.rst

@@ -1,9 +1,9 @@
 |Travis Build Status| |Azure CI Build Status| |Appveyor Build Status| |Coveralls Coverage|
 
-About Statsmodels
+About statsmodels
 =================
 
-Statsmodels is a Python package that provides a complement to scipy for
+statsmodels is a Python package that provides a complement to scipy for
 statistical computations including descriptive statistics and estimation
 and inference for statistical models.
 

docs/Makefile

@@ -43,8 +43,6 @@ html:
 	@echo "Make static directory for images"
 	mkdir -p $(BUILDDIR)/html/_static
 	# generate the examples rst files
-	@echo "Generating reST from examples folder"
-	#$(TOOLSPATH)$(EXAMPLEBUILD)
 	@echo "Generating datasets from installed statsmodels.datasets"
 	$(TOOLSPATH)$(DATASETBUILD)
 	@echo "Executing notebooks from examples/notebooks folder"

docs/source/_static/icons/android-chrome-192x192.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<browserconfig>
+    <msapplication>
+        <tile>
+            <square150x150logo src="/_static/icons/mstile-150x150.png"/>
+            <TileColor>#2b5797</TileColor>
+        </tile>
+    </msapplication>
+</browserconfig>

docs/source/_static/icons/android-chrome-512x512.png

@@ -0,0 +1,20 @@
+{
+    "name": "statsmodels",
+    "short_name": "statsmodels",
+    "icons": [
+        {
+            "src": "/_static/icons/android-chrome-192x192.png",
+            "sizes": "192x192",
+            "type": "image/png"
+        },
+        {
+            "src": "/_static/icons/android-chrome-512x512.png",
+            "sizes": "512x512",
+            "type": "image/png"
+        }
+    ],
+    "theme_color": "#ffffff",
+    "background_color": "#ffffff",
+    "start_url": "https://statsmodels.org",
+    "display": "standalone"
+}

docs/source/_static/icons/apple-touch-icon.png

@@ -0,0 +1,12 @@
+{# Import the theme's layout. #}
+{% extends "!layout.html" %}
+
+{%- block htmltitle %}
+  {{ super() }}
+  <link rel="icon" type="image/png" sizes="32x32" href="/_static/icons/favicon-32x32.png">
+  <link rel="icon" type="image/png" sizes="16x16" href="/_static/icons/favicon-16x16.png">
+  <link rel="manifest" href="/_static/icons/site.webmanifest">
+  <link rel="mask-icon" href="/_static/icons/safari-pinned-tab.svg" color="#919191">
+  <meta name="msapplication-TileColor" content="#2b5797">
+  <meta name="msapplication-config" content="/_static/icons/browserconfig.xml">
+{%- endblock %}

docs/source/_static/icons/browserconfig.xml

@@ -5,7 +5,7 @@
 .. currentmodule:: statsmodels
 
 *****************
-About Statsmodels
+About statsmodels
 *****************
 
 Background

docs/source/_static/icons/favicon-16x16.png

@@ -1,17 +1,17 @@
-API
----
-The main ~statsmodels API is split into models:
+API Reference
+=============
+The main statsmodels API is split into models:
 
-* ``~statsmodels.api``: Cross-sectional models and methods. Canonically imported
-  using ``import ~statsmodels.api as sm``.
-* ``~statsmodels.tsa.api``: Time-series models and methods. Canonically imported
-  using ``import ~statsmodels.tsa.api as tsa``.
+* ``statsmodels.api``: Cross-sectional models and methods. Canonically imported
+  using ``import statsmodels.api as sm``.
+* ``statsmodels.tsa.api``: Time-series models and methods. Canonically imported
+  using ``import statsmodels.tsa.api as tsa``.
 
 The API focuses on models and the most frequently used statistical test, and tools.  See the
 detailed topic pages for a more complete list of available models, statistics, and tools.
 
 ``statsmodels.api``
-===================
+-------------------
 
 Regression
 ~~~~~~~~~~
@@ -107,7 +107,7 @@ Tools
 
 
 ``statsmodels.tsa.api``
-=======================
+-----------------------
 
 Statistics and Tests
 ~~~~~~~~~~~~~~~~~~~~
@@ -175,9 +175,9 @@ Tools
    ~statsmodels.tsa.tsatools.lagmat2ds
    ~statsmodels.tsa.seasonal.seasonal_decompose
    ~statsmodels.tsa.seasonal.STL
-   ~statsmodels.tsa.filters.bk_filter
-   ~statsmodels.tsa.filters.cf_filter
-   ~statsmodels.tsa.filters.hp_filter
+   ~statsmodels.tsa.filters.bk_filter.bkfilter
+   ~statsmodels.tsa.filters.cf_filter.cffilter
+   ~statsmodels.tsa.filters.hp_filter.hpfilter
 
 Markov Switching
 ~~~~~~~~~~~~~~~~
@@ -194,3 +194,138 @@ X12/X13 Interface
 
    ~statsmodels.tsa.x13.x13_arima_analysis
    ~statsmodels.tsa.x13.x13_arima_select_order
+
+.. _importpaths:
+
+Import Paths and Structure
+--------------------------
+
+We offer two ways of importing functions and classes from statsmodels:
+
+1. `API import for interactive use`_
+
+   + Allows tab completion
+
+2. `Direct import for programs`_
+
+   + Avoids importing unnecessary modules and commands
+
+API Import for interactive use
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For interactive use the recommended import is:
+
+.. code-block:: python
+
+    import statsmodels.api as sm
+
+Importing `statsmodels.api` will load most of the public parts of statsmodels.
+This makes most functions and classes conveniently available within one or two
+levels, without making the "sm" namespace too crowded.
+
+To see what functions and classes available, you can type the following (or use
+the namespace exploration features of IPython, Spyder, IDLE, etc.):
+
+.. code-block:: python
+
+    >>> dir(sm)
+    ['GLM', 'GLS', 'GLSAR', 'Logit', 'MNLogit', 'OLS', 'Poisson', 'Probit', 'RLM',
+    'WLS', '__builtins__', '__doc__', '__file__', '__name__', '__package__',
+    'add_constant', 'categorical', 'datasets', 'distributions', 'families',
+    'graphics', 'iolib', 'nonparametric', 'qqplot', 'regression', 'robust',
+    'stats', 'test', 'tools', 'tsa', 'version']
+
+    >>> dir(sm.graphics)
+    ['__builtins__', '__doc__', '__file__', '__name__', '__package__',
+    'abline_plot', 'beanplot', 'fboxplot', 'interaction_plot', 'qqplot',
+    'rainbow', 'rainbowplot', 'violinplot']
+
+    >>> dir(sm.tsa)
+    ['AR', 'ARMA', 'SVAR', 'VAR', '__builtins__', '__doc__',
+    '__file__', '__name__', '__package__', 'acf', 'acovf', 'add_lag',
+    'add_trend', 'adfuller', 'ccf', 'ccovf', 'datetools', 'detrend',
+    'filters', 'grangercausalitytests', 'interp', 'lagmat', 'lagmat2ds',
+    'pacf', 'pacf_ols', 'pacf_yw', 'periodogram', 'q_stat', 'stattools',
+    'tsatools', 'var']
+
+Notes
+^^^^^
+
+The `api` modules may not include all the public functionality of statsmodels. If
+you find something that should be added to the api, please file an issue on
+github or report it to the mailing list.
+
+The subpackages of statsmodels include `api.py` modules that are mainly
+intended to collect the imports needed for those subpackages. The `subpackage/api.py`
+files are imported into statsmodels api, for example ::
+
+     from .nonparametric import api as nonparametric
+
+Users do not need to load the `subpackage/api.py` modules directly.
+
+Direct import for programs
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``statsmodels`` submodules are arranged by topic (e.g. `discrete` for discrete
+choice models, or `tsa` for time series analysis). Our directory tree (stripped
+down) looks something like this::
+
+    statsmodels/
+        __init__.py
+        api.py
+        discrete/
+            __init__.py
+            discrete_model.py
+            tests/
+                results/
+        tsa/
+            __init__.py
+            api.py
+            tsatools.py
+            stattools.py
+            arima_model.py
+            arima_process.py
+            vector_ar/
+                __init__.py
+                var_model.py
+                tests/
+                    results/
+            tests/
+                results/
+        stats/
+            __init__.py
+            api.py
+            stattools.py
+            tests/
+        tools/
+            __init__.py
+            tools.py
+            decorators.py
+            tests/
+
+The submodules that can be import heavy contain an empty `__init__.py`, except
+for some testing code for running tests for the submodules. The intention is to
+change all directories to have an `api.py` and empty `__init__.py` in the next
+release.
+
+Import examples
+^^^^^^^^^^^^^^^
+
+Functions and classes::
+
+    from statsmodels.regression.linear_model import OLS, WLS
+    from statsmodels.tools.tools import rank, add_constant
+
+Modules ::
+
+    from statsmodels.datasets import macrodata
+    import statsmodels.stats import diagnostic
+
+Modules with aliases ::
+
+    import statsmodels.regression.linear_model as lm
+    import statsmodels.stats.diagnostic as smsdia
+    import statsmodels.stats.outliers_influence as oi
+
+We do not have currently a convention for aliases of submodules.
+