Add new API-reference page, automated generation of .rst files, enable sphinx-gallery. Fix #1808

.gitignore

@@ -49,7 +49,9 @@ Thumbs.db
 .eggs
 cython_debug
 docs/src/_build/
-docs/_static
+docs/src/generated/
+docs/src/modules/generated/
+docs/src/auto_examples/
 docs/notebooks/.ipynb_checkpoints
 dedan_gensim.tmproj
 gensim*.egg-info
@@ -70,7 +72,10 @@ data
 *.model
 *~
 *_out.txt
-*.html
+docs/src/*.html
+docs/src/modules/*.html
 *.inv
 *.js
-docs/_images/
+!docs/src/_static/js/*.js
+!docs/src/gensim_theme/static/*.js
+docs/src/_images/

docs/examples/README.txt

@@ -0,0 +1,12 @@
+.. _examples-index:
+
+Gallery of Examples
+===================
+
+
+.. _general_examples:
+
+General examples
+----------------
+
+General-purpose and introductory examples from the gensim

docs/examples/plot_downloader_api_tutorial.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""
+EXAMPLE EXAMPLE
+===============
+
+TO BE REPLACED WITH A REAL EXAMPLE
+"""
+
+###########################################################################
+# Here's our imports:
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+###########################################################################
+# Here's the first graph:
+
+x = np.linspace(-1, 2, 100)
+y = np.exp(x)
+
+plt.figure()
+plt.plot(x, y)
+plt.xlabel('$x$')
+plt.ylabel('$\exp(x)$')
+
+plt.show()
+
+###########################################################################
+# And here's the second one:
+
+plt.figure()
+plt.plot(x, -np.exp(-x))
+plt.xlabel('$x$')
+plt.ylabel('$-\exp(-x)$')
+
+plt.show()

docs/src/Makefile

@@ -32,13 +32,14 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm -rf generated/*
+	-rm -rf modules/generated/
+	-rm -rf auto_examples/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	rm -r $(BUILDDIR)/html/_sources
-	cp -r $(BUILDDIR)/html/* ../
 	@echo
-	@echo "Build finished. The HTML pages are in ../"
+	@echo "Build finished. The HTML pages are in /docs/src/_build/html"
 
 upload:
 	scp -r _build/html/* rr:public_html/gensim/
@@ -62,13 +63,13 @@ htmlhelp:
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+		  ".hhp project file in $(BUILDDIR)/htmlhelp."
 
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+		  ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/gensim.qhcp"
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/gensim.qhc"
@@ -78,7 +79,7 @@ latex:
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
+		  "run these through (pdf)latex."
 	cd $(BUILDDIR)/latex && make all-pdf
 	cp  $(BUILDDIR)/latex/gensim.pdf ../gensim_manual.pdf
 
@@ -91,9 +92,9 @@ linkcheck:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
+		  "or in $(BUILDDIR)/linkcheck/output.txt."
 
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+		  "results in $(BUILDDIR)/doctest/output.txt."

docs/src/_templates/class.rst

@@ -0,0 +1,13 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+    :members:
+    :special-members:
+    :exclude-members: __init__
+
+.. raw:: html
+
+    <div class="clearer"></div>

docs/src/_templates/function.rst

@@ -0,0 +1,10 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}====================
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. raw:: html
+
+    <div class="clearer"></div>

docs/src/_templates/module.rst

@@ -0,0 +1,11 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. currentmodule:: {{ module }}
+
+.. automodule:: {{module}}.{{objname}}
+    :members:
+
+.. raw:: html
+
+    <div class="clearer"></div>