update doc formatting

docs/conf.py

@@ -14,20 +14,24 @@
 #
 import os
 import sys
+import inspect
 
 sys.path.insert(0, os.path.abspath(".."))
+import numpy_ml
 
 
+gh_url = "https://github.com/ddbourgin/numpy-ml"
+
 # -- Project information -----------------------------------------------------
 
 project = "numpy-ml"
 copyright = "2019, David Bourgin"
 author = "David Bourgin"
 
 # The short X.Y version
-version = ""
+version = "0.1"
 # The full version, including alpha/beta/rc tags
-release = ""
+release = "0.1.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -47,12 +51,46 @@
     "sphinx.ext.coverage",
     "sphinx.ext.mathjax",
     "sphinx.ext.ifconfig",
-    "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
     "sphinx.ext.napoleon",
+    "sphinx.ext.linkcode"
     #  "numpydoc",
 ]
 
+# Try to link to source code on GitHub
+def linkcode_resolve(domain, info):
+    if domain != "py":
+        return None
+
+    module = info.get("module", None)
+    fullname = info.get("fullname", None)
+
+    if not module or not fullname:
+        return None
+
+    obj = sys.modules.get(module, None)
+    if obj is None:
+        return None
+
+    for part in fullname.split("."):
+        obj = getattr(obj, part)
+        if isinstance(obj, property):
+            obj = obj.fget
+
+    try:
+        file = inspect.getsourcefile(obj)
+        if file is None:
+            return None
+    except:
+        return None
+
+    file = os.path.relpath(file, start=os.path.dirname(numpy_ml.__file__))
+    source, line_start = inspect.getsourcelines(obj)
+    line_end = line_start + len(source) - 1
+    filename = f"numpy_ml/{file}#L{line_start}-L{line_end}"
+    return f"{gh_url}/blob/master/{filename}"
+
+
 # Napoleon settings
 # https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html#sphinxcontrib.napoleon.Config
 napoleon_google_docstring = False
@@ -136,13 +174,14 @@
 }
 
 html_theme_options = {
-    #  'logo': 'logo.png',
     "github_user": "ddbourgin",
     "github_repo": "numpy-ml",
     "description": "Machine learning, in NumPy",
-    #  'analytics_id': "", XXX: TODO
     "github_button": True,
     "show_powered_by": False,
+    "fixed_sidebar": True,
+    "analytics_id": "UA-65839510-3",
+    #  'logo': 'logo.png',
 }
 
 

docs/index.rst

@@ -4,16 +4,25 @@ Welcome to numpy-ml
 tools written exclusively in `NumPy`_ and the Python `standard library`_. 
 
 The purpose of the project is to provide reference implementations of common
-machine learning components for rapid prototyping and experimentation. 
+machine learning components for rapid prototyping and experimentation. With
+that in mind, don't just read the docs -- read the source!
 
 .. _numpy-ml: http://www.github.com/ddbourgin/numpy-ml
 .. _NumPy: http://numpy.scipy.org/
 .. _standard library: https://docs.python.org/3/library/
 
-API Reference
--------------
+.. topic:: This documentation is under development!
+
+    We're working to expand our coverage. During this time there are likely to
+    be typos, bugs, and poorly-worded sections. If you encounter any of the
+    above, please file an `issue`_ or submit a `pull request`_! 
+
+.. _issue: https://github.com/ddbourgin/numpy-ml/issues
+.. _pull request: https://github.com/ddbourgin/numpy-ml/pulls
+
 .. toctree::
    :maxdepth: 3
+   :hidden:
 
    numpy_ml.hmm
 
@@ -23,20 +32,20 @@ API Reference
 
    numpy_ml.ngram
 
-   numpy_ml.trees
+   numpy_ml.rl_models
 
-   numpy_ml.utils
+   numpy_ml.nonparametric
 
-   numpy_ml.rl_models
+   numpy_ml.trees
 
    numpy_ml.neural_nets
 
    numpy_ml.linear_models
 
-   numpy_ml.nonparametric
-
    numpy_ml.preprocessing
 
+   numpy_ml.utils
+
 ##########
 Disclaimer	
 ##########	

docs/numpy_ml.gmm.gmm.rst

@@ -1,7 +1,7 @@
 ``GMM``
 -------
 
-.. autoclass:: numpy_ml.gmm.gmm.GMM
+.. autoclass:: numpy_ml.gmm.GMM
 	:members:
 	:undoc-members:
 	:inherited-members:

docs/numpy_ml.gmm.rst

@@ -53,7 +53,10 @@ algorithm`_ to learn the GMM parameters.
 
 .. topic:: References
 
-    .. [1]  w.
+    .. [1] Bilmes, J. A. (1998). "A gentle tutorial of the EM algorithm and its
+       application to parameter estimation for Gaussian mixture and hidden
+       Markov models" *International Computer Science Institute, 4(510)*
+       https://www.inf.ed.ac.uk/teaching/courses/pmr/docs/EM.pdf
 
 
 .. toctree::

docs/numpy_ml.hmm.MultinomialHMM.rst

@@ -1,8 +1,7 @@
 ``MultinomialHMM``
 ------------------
 
-.. autoclass:: numpy_ml.hmm.hmm.MultinomialHMM
+.. autoclass:: numpy_ml.hmm.MultinomialHMM
 	:members:
 	:undoc-members:
 	:inherited-members:
-	:show-inheritance:

docs/numpy_ml.lda.lda.rst

@@ -1,7 +1,7 @@
 ``LDA``
 =======
 
-.. autoclass:: numpy_ml.lda.lda.LDA
+.. autoclass:: numpy_ml.lda.LDA
     :members:
     :undoc-members:
     :inherited-members:

docs/numpy_ml.lda.rst

@@ -61,7 +61,9 @@ under the smoothed LDA model is:
 .. topic:: References
 
     .. [1]  Blei, Ng, & Jordan (2003). "Latent Dirichlet allocation". *Journal of
-       Machine Learning Research*, 3, 993–1022.
+       Machine Learning Research*, *3*, 993–1022.
+    .. [2]  Griffiths & Steyvers (2004). "Finding scientific topics". *PNAS*,
+       *101(1)*, 5228-5235.
 
 .. toctree::
    :maxdepth: 3

docs/numpy_ml.lda.smoothed_lda.rst

@@ -1,7 +1,7 @@
 ``SmoothedLDA``
 ===============
 
-.. autoclass:: numpy_ml.lda.lda_smoothed.SmoothedLDA
+.. autoclass:: numpy_ml.lda.SmoothedLDA
     :members:
     :undoc-members:
     :inherited-members: