From eebff44a0735c0e8f6d2eee0ab278361b0cc5831 Mon Sep 17 00:00:00 2001
From: Heiko Strathmann <heiko.strathmann@gmail.com>
Date: Sun, 21 Feb 2016 13:29:17 +0000
Subject: [PATCH] add links to github issues and Shogun class list

---
 doc/sphinx/source/conf.py                     | 18 +++++++++++++++++-
 doc/sphinx/source/examples/classifier/knn.rst |  6 ++++--
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py
index 64e54b270a9..359867acfa0 100644
--- a/doc/sphinx/source/conf.py
+++ b/doc/sphinx/source/conf.py
@@ -27,9 +27,17 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    # we use pngmath because it allows for custom latex preambles
     'sphinx.ext.pngmath',
+    
+    # our own plugin that loads snippets from meta-language generated listings
     'sgexample',
+    
+    # bibtex citations support
     'sphinxcontrib.bibtex',
+    
+    # to create automatic links to Shogun class docs
+    'sphinx.ext.extlinks', 
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -208,7 +216,8 @@
 # 'preamble': '',
 }
 
-# only makes sense for png math
+# Custom latex operators only makes sense for png math
+# TODO: load those from a file
 pngmath_latex_preamble = r'\DeclareMathOperator*{\argmin}{arg\,min}' \
                        + r'\DeclareMathOperator*{\argmax}{arg\,max}'
 
@@ -276,3 +285,10 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# options for external link plugin
+extlinks = {
+'sgissue': ('https://github.com/shogun-toolbox/shogun/issues/%s',        'issue '),
+'sgclass': ('http://www.shogun-toolbox.org/doc/en/latest/classshogun_1_1%s.html',        '')
+
+}
diff --git a/doc/sphinx/source/examples/classifier/knn.rst b/doc/sphinx/source/examples/classifier/knn.rst
index d253a486404..e3c1cf0ebca 100644
--- a/doc/sphinx/source/examples/classifier/knn.rst
+++ b/doc/sphinx/source/examples/classifier/knn.rst
@@ -12,6 +12,8 @@ For :math:`k=1`, the label for a test point :math:`x^*` is predicted to be the s
    
 See Chapter 14 in :cite:`barber2012bayesian` for a detailed introduction.
 
+See :sgissue:`2996` for known issues.
+
 -------
 Example
 -------
@@ -20,11 +22,11 @@ Load some training and test data.
 
 .. sgexample:: knn.sg:load_data
 
-In order to run KNN, we need to choose a distance, for example CEuclideanDistance, or other sub-classes of CDistance. The distance is initialized with the data we want to classify.
+In order to run :sgclass:`CKNN`, we need to choose a distance, for example :sgclass:`CEuclideanDistance`, or other sub-classes of :sgclass:`CDistance`. The distance is initialized with the data we want to classify.
 
 .. sgexample:: knn.sg:choose_distance
 
-Once we have chosen a distance, we create an instance of the CKNN classifier, passing it training data and labels.
+Once we have chosen a distance, we create an instance of the :sgclass:`CKNN` classifier, passing it training data and labels.
 
 .. sgexample:: knn.sg:create_instance