[MRG] Enhance documentation (#208)

* Add link to algorithm in the title of sections

* Separate supervised and weakly supervised algorithms in Package Overview

* Improve doc

* Fix plot_metric_example

* Update links with the new pages

* Use random init for LMNN

* Update remaining num_dims

* Add description of the API for Weakly Supervised and Supervised algorithms

* Remove  to have the list of methods in the description of the class

* Fix: Update wronly merged lmnn with None instead of 'auto' in init

* Add some documentation about generating pairs and quadruplets

* Add base module quick description

* Put classes rather than modules

* Add docstrings at top of algos

* Update name of API details to Package Contents

* Update name of API details to Package Contents

Author: wdevazelhes

.gitignore

@@ -7,3 +7,4 @@ htmlcov/
 .cache/
 .pytest_cache/
 doc/auto_examples/*
+doc/generated/*

doc/_templates/class.rst

@@ -0,0 +1,16 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :inherited-members:
+   :special-members: __init__
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div style='clear:both'></div>

doc/conf.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 import sys
+import os
 
 extensions = [
     'sphinx.ext.autodoc',
@@ -28,7 +29,6 @@
 exclude_patterns = ['_build']
 pygments_style = 'sphinx'
 todo_include_todos = True
-numpydoc_show_class_members = False
 
 # Options for HTML output
 html_theme = 'sphinx_rtd_theme'
@@ -50,3 +50,16 @@
     'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
     'scikit-learn': ('https://scikit-learn.org/stable/', None)
 }
+
+
+# sphinx-gallery configuration
+sphinx_gallery_conf = {
+    # to generate mini-galleries at the end of each docstring in the API
+    # section: (see https://sphinx-gallery.github.io/configuration.html
+    # #references-to-examples)
+    'doc_module': 'metric_learn',
+    'backreferences_dir': os.path.join('generated'),
+}
+
+# generate autosummary even if no references
+autosummary_generate = True

doc/index.rst

@@ -25,7 +25,7 @@ Documentation outline
 .. toctree::
    :maxdepth: 2
 
-   Package Overview <metric_learn>
+   Package Contents <metric_learn>
 
 .. toctree::
    :maxdepth: 2