Merge pull request #371 from rasbt/doc-improvements

Doc improvements

docs/cinder/css/base.css

@@ -5,7 +5,7 @@ body {
 h1[id]:before, h2[id]:before, h3[id]:before, h4[id]:before, h5[id]:before, h6[id]:before {
     content: "";
     display: block;
-    margin-top: -75px;
+    margin-top: 0px;
     height: 75px;
 }
 

docs/make_api.py

@@ -21,6 +21,21 @@ def _obj_name(obj):
         return obj.__name__
 
 
+def make_markdown_url(line_string, s):
+    """
+    Turns an URL starting with s into
+    a markdown link
+    """
+    new_line = []
+    old_line = line_string.split(' ')
+    for token in old_line:
+        if not token.startswith(s):
+            new_line.append(token)
+        else:
+            new_line.append('[%s](%s)' % (token, token))
+    return ' '.join(new_line)
+
+
 def docstring_to_markdown(docstring):
     """Convert a Python object's docstring to markdown
 
@@ -44,6 +59,7 @@ def docstring_to_markdown(docstring):
 
         elif line.startswith('>>>'):
             line = '    %s' % line
+
         new_docstring_lst.append(line)
 
     param_encountered = False
@@ -63,6 +79,17 @@ def docstring_to_markdown(docstring):
 
     clean_lst = []
     for line in new_docstring_lst:
+
+        if 'http://rasbt.github.io/' in line:
+            line = make_markdown_url(line_string=line,
+                                     s='http://rasbt.github.io/')
+
+            if len(clean_lst) > 0 and \
+                    clean_lst[-1].lstrip().startswith(
+                        'For more usage examples'):
+                clean_lst[-1] = clean_lst[-1].lstrip()
+                line = line.lstrip()
+
         if line.startswith('\n>>>'):
             clean_lst.append('\n')
             clean_lst.append('    ' + line[1:])
@@ -72,7 +99,6 @@ def docstring_to_markdown(docstring):
             clean_lst.append(line[4:])
         elif set(line.strip()) not in ({'-'}, {'='}):
             clean_lst.append(line)
-
     return clean_lst
 
 
@@ -349,7 +375,9 @@ def summarize_methdods_and_functions(api_modules, out_dir,
             new_output.append(str_above_header)
         for p in sorted(module_paths):
             with open(p, 'r') as r:
+
                 new_output.extend(r.readlines())
+                new_output.extend(['\n', '\n', '\n'])
 
         msg = ''
         if not os.path.isfile(out_f):

docs/mkdocs.yml

@@ -15,14 +15,20 @@ theme_dir: cinder
 site_favicon: favicon.ico
 
 markdown_extensions:
-  - extra
   - tables
   - fenced_code
   - mdx_math:
       enable_dollar_delimiter: True #for use of inline $..$
 extra_javascript:
   - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML
   - mathjaxhelper.js
+extra_css:
+  - cinder/css/base.css
+  - cinder/css/bootstrap-custom.css
+  - cinder/css/bootstrap-custom.min.css
+  - cinder/css/cinder.css
+  - cinder/css/font-awesome-4.0.3.css
+  - cinder/css/highlight.css
 
 copyright: Copyright &copy; 2014-2018 <a href="http://sebastianraschka.com">Sebastian Raschka</a>
 google_analytics: ['UA-38457794-2', 'rasbt.github.io/mlxtend/']

docs/sources/CHANGELOG.md

@@ -35,6 +35,7 @@ The CHANGELOG for the current development version is available at
 
 - Various changes in the documentation and documentation tools to fix formatting issues ([#363](https://github.com/rasbt/mlxtend/pull/363))
 - Fixes a bug where the `StackingCVClassifier`'s meta features were not stored in the original order when `shuffle=True` ([#370](https://github.com/rasbt/mlxtend/pull/370))
+- Many documentation improvements, including links to the User Guides in the API docs ([#371](https://github.com/rasbt/mlxtend/pull/371))
 
 
 

docs/sources/user_guide/classifier/Adaline.ipynb

@@ -498,6 +498,11 @@
       "\n",
       "    Sum of squared errors after each epoch.\n",
       "\n",
+      "**Examples**\n",
+      "\n",
+      "For usage examples, please see\n",
+      "    [http://rasbt.github.io/mlxtend/user_guide/classifier/Adaline/](http://rasbt.github.io/mlxtend/user_guide/classifier/Adaline/)\n",
+      "\n",
       "### Methods\n",
       "\n",
       "<hr>\n",
@@ -579,15 +584,6 @@
     "with open('../../api_modules/mlxtend.classifier/Adaline.md', 'r') as f:\n",
     "    print(f.read())"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
@@ -606,7 +602,19 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.1"
+   "version": "3.6.4"
+  },
+  "toc": {
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": false
   }
  },
  "nbformat": 4,

docs/sources/user_guide/classifier/EnsembleVoteClassifier.ipynb

@@ -891,7 +891,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [
     {
@@ -987,6 +987,9 @@
       "    [1 1 1 2 2 2]\n",
       "    >>>\n",
       "\n",
+      "For more usage examples, please see\n",
+      "[http://rasbt.github.io/mlxtend/user_guide/classifier/EnsembleVoteClassifier/](http://rasbt.github.io/mlxtend/user_guide/classifier/EnsembleVoteClassifier/)\n",
+      "\n",
       "### Methods\n",
       "\n",
       "<hr>\n",
@@ -1187,6 +1190,18 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.6.4"
+  },
+  "toc": {
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": false
   }
  },
  "nbformat": 4,

docs/sources/user_guide/classifier/LogisticRegression.ipynb

@@ -759,6 +759,11 @@
       "    List of floats with cross_entropy cost (sgd or gd) for every\n",
       "    epoch.\n",
       "\n",
+      "**Examples**\n",
+      "\n",
+      "For usage examples, please see\n",
+      "    [http://rasbt.github.io/mlxtend/user_guide/classifier/LogisticRegression/](http://rasbt.github.io/mlxtend/user_guide/classifier/LogisticRegression/)\n",
+      "\n",
       "### Methods\n",
       "\n",
       "<hr>\n",
@@ -858,15 +863,6 @@
     "with open('../../api_modules/mlxtend.classifier/LogisticRegression.md', 'r') as f:\n",
     "    print(f.read())"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
@@ -886,7 +882,19 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.1"
+   "version": "3.6.4"
+  },
+  "toc": {
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": false
   }
  },
  "nbformat": 4,

docs/sources/user_guide/classifier/MultiLayerPerceptron.ipynb

@@ -668,6 +668,11 @@
       "    List of floats; the mean categorical cross entropy\n",
       "    cost after each epoch.\n",
       "\n",
+      "**Examples**\n",
+      "\n",
+      "For usage examples, please see\n",
+      "    [http://rasbt.github.io/mlxtend/user_guide/classifier/MultiLayerPerceptron/](http://rasbt.github.io/mlxtend/user_guide/classifier/MultiLayerPerceptron/)\n",
+      "\n",
       "### Methods\n",
       "\n",
       "<hr>\n",
@@ -795,7 +800,19 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.1"
+   "version": "3.6.4"
+  },
+  "toc": {
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": false
   }
  },
  "nbformat": 4,

docs/sources/user_guide/classifier/Perceptron.ipynb

@@ -363,6 +363,11 @@
       "\n",
       "    Number of misclassifications in every epoch.\n",
       "\n",
+      "**Examples**\n",
+      "\n",
+      "For usage examples, please see\n",
+      "    [http://rasbt.github.io/mlxtend/user_guide/classifier/Perceptron/](http://rasbt.github.io/mlxtend/user_guide/classifier/Perceptron/)\n",
+      "\n",
       "### Methods\n",
       "\n",
       "<hr>\n",
@@ -472,7 +477,19 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.1"
+   "version": "3.6.4"
+  },
+  "toc": {
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": false
   }
  },
  "nbformat": 4,

docs/sources/user_guide/classifier/SoftmaxRegression.ipynb

@@ -713,6 +713,11 @@
       "\n",
       "    List of floats, the average cross_entropy for each epoch.\n",
       "\n",
+      "**Examples**\n",
+      "\n",
+      "For usage examples, please see\n",
+      "    [http://rasbt.github.io/mlxtend/user_guide/classifier/SoftmaxRegression/](http://rasbt.github.io/mlxtend/user_guide/classifier/SoftmaxRegression/)\n",
+      "\n",
       "### Methods\n",
       "\n",
       "<hr>\n",
@@ -840,7 +845,19 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.1"
+   "version": "3.6.4"
+  },
+  "toc": {
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": false
   }
  },
  "nbformat": 4,

docs/sources/user_guide/classifier/StackingCVClassifier.ipynb

@@ -630,6 +630,11 @@
       "    number of samples\n",
       "    in training data and n_classifiers is the number of classfiers.\n",
       "\n",
+      "**Examples**\n",
+      "\n",
+      "For usage examples, please see\n",
+      "    [http://rasbt.github.io/mlxtend/user_guide/classifier/StackingCVClassifier/](http://rasbt.github.io/mlxtend/user_guide/classifier/StackingCVClassifier/)\n",
+      "\n",
       "### Methods\n",
       "\n",
       "<hr>\n",
@@ -805,6 +810,13 @@
     "with open('../../api_modules/mlxtend.classifier/StackingCVClassifier.md', 'r') as f:\n",
     "    print(f.read())"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {