First pass at documentation

Author: Frankie Robertson

docs/background.rst

@@ -0,0 +1,21 @@
+Background and API design
+=========================
+
+There have been long standing efficiency issues with scikit-learn's. In
+particular, the `ball tree`_ and `k-d tree`_ to not scale well to high
+dimensional spaces. The decision was taken that the best way to integrate other
+techniques was to allow all applicable unsupervised estimators methods to take
+a sparse matrix, typically being a KNN-graph of the points, but potentially
+being any estimate. These `slides from PyParis 2018`_ explain some background,
+while `issue #10463`_ and `pull request #10482`_ give discussion, justification
+and benchmarks and more detail regarding the approach.
+
+The main advantage of this technique is that the sparse matrix/KNN-graph can be built transformer from the data, and these to be sequenced using the scikit-learn pipeline mechanism. This approach allows for, for example parameter search to be done on the KNN-graph construction technique together with the estimator. Typically the transformer should closely follow the interface of KNeighborsTransformer. The `exact contract is outlined in the user guide`_.  .  There is also `an example notebook with early versions of the transformers in this library`_.
+
+.. _`ball tree`: https://en.wikipedia.org/wiki/Ball_tree
+.. _`k-d tree`: https://en.wikipedia.org/wiki/K-d_tree
+.. _`slides from PyParis 2018`: https://tomdlt.github.io/decks/2018_pyparis/
+.. _`issue #10463`: https://github.com/scikit-learn/scikit-learn/issues/10463
+.. _`pull request #10482`: https://github.com/scikit-learn/scikit-learn/pull/10482
+.. _`exact contract is outlined in the user guide`: https://scikit-learn.org/stable/modules/neighbors.html#neighbors-transformer
+.. _`an example notebook with early versions of the transformers in this library`: https://scikit-learn.org/stable/auto_examples/neighbors/approximate_nearest_neighbors.html#sphx-glr-auto-examples-neighbors-approximate-nearest-neighbors-py

docs/clustering.rst

@@ -0,0 +1,9 @@
+Clustering
+==========
+
+While it is possible to use the transformers of the sklearn_ann.kneighbors module together with clustering algorithms from scikit-learn directly, there is often a mismatch between techniques like DBSCAN, which require for each node its neighbors within a certain radius, and kNN-graph which has a fixed number of. This mismatch may result in k being set to high, to make sure that, slowing things down.
+
+This module contains an implementation of RNN-DBSCAN, which is based on the kNN-graph structure.
+
+.. automodule:: sklearn_ann.cluster.rnn_dbscan
+   :members:

docs/conf.py

@@ -14,6 +14,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import sphinx_rtd_theme
+
 
 # -- Project information -----------------------------------------------------
 
@@ -28,6 +30,11 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'numpydoc',
+    'sphinx_issues',
+    'sphinx.ext.viewcode',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -44,9 +51,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static']
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+autodoc_mock_imports = ["annoy", "faiss", "pynndescent", "nmslib"]

docs/index.rst

@@ -14,6 +14,17 @@ sklearn-ann
   :start-after: inclusion-marker-do-not-remove
 
 
+User Guide
+---------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   background
+   kneighbors
+   clustering
+
+
 Indices and tables
 ==================
 

docs/kneighbors.rst

@@ -0,0 +1,71 @@
+Implementations of the KNeighborsTransformer interface
+======================================================
+
+This module contains transformers which transform from array-like structures of
+shape (n_samples, n_features) to KNN-graphs encoded as scipy.sparse.csr_matrix.
+They conform to the KNeighborsTransformer interface. Each submodule in this
+module provides facilities for exactly one external nearest neighbour library.
+
+Annoy
+-----
+
+`Annoy (Approximate Nearest Neighbors Oh Yeah)`_ is a C++ library with Python
+bindings to search for points in space that are close to a given query point. The originates from Spotify.
+It uses a forest of random projection trees.
+
+.. _`Annoy (Approximate Nearest Neighbors Oh Yeah)`: https://github.com/spotify/annoy
+
+
+.. automodule:: sklearn_ann.kneighbors.annoy
+   :members:
+
+FAISS
+-----
+
+`FAISS (Facebook AI Similarity Search)`_ is a library for efficient similarity
+search and clustering of dense vectors. The project originates from Facebook AI
+Research (FAIR). It contains multiple algorithms including algorithms for
+exact/brute force nearest neighbour, methods based on quantization and product
+quantization, and methods based on Hierarchical Navigable Small World graphs
+(HNSW). There are some `guidelines on how to choose the best index for your
+purposes`.
+
+.. _`FAISS (Facebook AI Similarity Search)`: https://github.com/facebookresearch/faiss/wiki/Guidelines-to-choose-an-index
+
+.. _`guidelines on how to choose the best index for your purposes`: https://github.com/facebookresearch/faiss/wiki/Guidelines-to-choose-an-index
+
+
+.. automodule:: sklearn_ann.kneighbors.faiss
+   :members:
+
+nmslib
+------
+
+`nmslib (non-metric space library)` is a library for similarity search support
+metric and non-metric spaces. It contains multiple algorithms.
+
+
+.. automodule:: sklearn_ann.kneighbors.nmslib
+   :members:
+
+PyNNDescent
+-----------
+
+`PyNNDescent`_ is a Python nearest neighbor descent for approximate nearest
+neighbors. It iteratively improves kNN-graph using the transitive property,
+using random projections for initialisation. This transformer is actually
+implemented as part of PyNNDescent, and simply re-exported here for (foolish)
+consistency. If you only need this transformer, just use PyNNDescent directly.
+
+
+.. automodule:: sklearn_ann.kneighbors.pynndescent
+   :members:
+
+sklearn
+-------
+
+`scikit-learn` itself contains ball tree and k-d indices. KNeighborsTransformer is re-exported here specialised for these two types of index for consistency.
+
+
+.. automodule:: sklearn_ann.kneighbors.sklearn
+   :members: