add links to github issues and Shogun class list

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',        '')
+
+}

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