Add documentation

The doc system is stolen from IPython.

If readthedocs is setup, the templates (docs\source\_templates)
should be adjusted to link to it.

.gitignore

@@ -53,6 +53,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/source/magics-generated.txt
 
 # PyBuilder
 target/

docs/Makefile

@@ -0,0 +1,159 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+SRCDIR        = source
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
+
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
+
+default: html
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html        standalone HTML files"
+	@echo "  html_noapi  same as above, without the time consuming API docs"
+	@echo "  pickle      pickle files (usable by e.g. sphinx-web)"
+	@echo "  htmlhelp    HTML files and a HTML help project"
+	@echo "  latex       LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  texinfo     Texinfo files"
+	@echo "  info        Texinfo files and run them through makeinfo"
+	@echo "  changes     an overview over all changed/added/deprecated items"
+	@echo "  linkcheck   check all external links for integrity (takes a long time)"
+	@echo "  gh-pages    clone IPython docs in ./gh-pages/ , build doc, autocommit"
+	@echo
+	@echo "Compound utility targets:"
+	@echo "pdf          latex and then runs the PDF generation"
+	@echo "all          html and pdf"
+	@echo "dist         all, and then puts the results in dist/"
+
+clean_api:
+	-rm -rf $(SRCDIR)/api/generated
+
+clean: clean_api
+	-rm -rf build/* dist/*
+	-cd $(SRCDIR)/config/options; test -f generated && cat generated | xargs rm -f
+	-rm -rf $(SRCDIR)/config/options/generated
+	-rm -f $(SRCDIR)/interactive/magics-generated.txt
+
+pdf: latex
+	cd build/latex && make all-pdf
+
+all: html pdf
+
+# For final distribution, only build HTML (our pdf is now so large as to be
+# unusable, takes forever to build and just bloats the downloads).  We leave
+# them hardlinked at the top-level so users find them easily, though the
+# original build/html dir is left in-place (useful to reload builds while
+# testing).
+dist: html
+	rm -rf html
+	cp -al build/html .
+	@echo "Build finished.  Final docs are in html/"
+
+html: api autoconfig automagic
+html_noapi: clean_api autoconfig automagic
+
+html html_noapi:
+	mkdir -p build/html build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
+	@echo
+	@echo "Build finished. The HTML pages are in build/html."
+
+automagic: source/interactive/magics-generated.txt
+
+source/interactive/magics-generated.txt: autogen_magics.py
+	python autogen_magics.py
+	@echo "Created docs for line & cell magics"
+
+autoconfig: source/config/options/generated
+
+source/config/options/generated:
+	python autogen_config.py
+	@echo "Created docs for config options"
+
+api: source/api/generated/gen.txt
+
+source/api/generated/gen.txt:
+	python autogen_api.py
+	@echo "Build API docs finished."
+
+pickle:
+	mkdir -p build/pickle build/doctrees
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files or run"
+	@echo "  sphinx-web build/pickle"
+	@echo "to start the sphinx-web server."
+
+web: pickle
+
+htmlhelp:
+	mkdir -p build/htmlhelp build/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in build/htmlhelp."
+
+qthelp:
+	mkdir -p build/qthelp
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
+
+latex: api autoconfig
+	mkdir -p build/latex build/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in build/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	mkdir -p build/changes build/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
+	@echo
+	@echo "The overview file is in build/changes."
+
+linkcheck:
+	mkdir -p build/linkcheck build/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in build/linkcheck/output.rst."
+
+nightly: dist
+	rsync -avH --delete dist/ ipython:www/doc/nightly
+
+gh-pages: clean html
+	# if VERSION is unspecified, it will be dev
+	# For releases, VERSION should be just the major version,
+	# e.g. VERSION=2 make gh-pages
+	python gh-pages.py $(VERSION)
+
+texinfo:
+	mkdir -p $(BUILDDIR)/texinfo
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	mkdir -p $(BUILDDIR)/texinfo
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

docs/README.rst

@@ -0,0 +1,24 @@
+IPython Documentation
+---------------------
+
+This directory contains the documentation for IPython-extensions. 
+
+
+Requirements
+------------
+The following tools are needed to build the documentation:
+
+sphinx numpydoc 
+
+The documentation gets built using ``make``, and comes in several flavors.
+
+``make html`` - build the API (both Javascript and Python) and narrative 
+documentation web pages, this is the the default ``make`` target, so 
+running just ``make`` is equivalent to ``make html``. 
+
+``make pdf`` will compile a pdf from the documentation.
+
+You can run ``make help`` to see information on all possible make targets.
+
+
+

docs/autogen_magics.py

@@ -0,0 +1,85 @@
+import os
+
+from IPython.core.alias import Alias
+from IPython.core.interactiveshell import InteractiveShell
+from IPython.core.magic import MagicAlias
+from IPython.utils.text import dedent, indent
+
+shell = InteractiveShell.instance()
+magics = shell.magics_manager.magics
+
+# Register our own magics
+
+ipy_magics = []
+for name, func in magics['line'].items():
+    ipy_magics.append(name)
+for name, func in magics['cell'].items():
+    ipy_magics.append(name)
+
+from ipyext import all_class_magics
+shell.register_magics(*all_class_magics)
+
+
+def _strip_underline(line):
+    chars = set(line.strip())
+    if len(chars) == 1 and ('-' in chars or '=' in chars):
+        return ""
+    else:
+        return line
+
+def format_docstring(func):
+    docstring = (func.__doc__ or "Undocumented").rstrip()
+    docstring = indent(dedent(docstring))
+    # Sphinx complains if indented bits have rst headings in, so strip out
+    # any underlines in the docstring.
+    lines = [_strip_underline(l) for l in docstring.splitlines()]
+    return "\n".join(lines)
+
+output = [
+"Line magics",
+"===========",
+"",
+]
+
+# Case insensitive sort by name
+def sortkey(s): return s[0].lower()
+
+for name, func in sorted(magics['line'].items(), key=sortkey):
+    if name in ipy_magics:
+        continue
+    if isinstance(func, Alias) or isinstance(func, MagicAlias):
+        # Aliases are magics, but shouldn't be documented here
+        # Also skip aliases to other magics
+        continue
+    output.extend([".. magic:: {}".format(name),
+                   "",
+                   format_docstring(func),
+                   ""])
+
+output.extend([
+"Cell magics",
+"===========",
+"",
+])
+
+for name, func in sorted(magics['cell'].items(), key=sortkey):
+    if name in ipy_magics:
+        continue
+
+    if name == "!":
+        # Special case - don't encourage people to use %%!
+        continue
+    if func == magics['line'].get(name, 'QQQP'):
+        # Don't redocument line magics that double as cell magics
+        continue
+    if isinstance(func, MagicAlias):
+        continue
+    output.extend([".. cellmagic:: {}".format(name),
+                   "",
+                   format_docstring(func),
+                   ""])
+
+here = os.path.dirname(__file__)
+dest = os.path.join(here, 'source', 'magics-generated.txt')
+with open(dest, "w") as f:
+    f.write("\n".join(output))

docs/make.cmd

@@ -0,0 +1,81 @@
+@ECHO OFF
+REM ~ Windows command line make file for Sphinx documentation
+
+SETLOCAL
+
+SET SPHINXOPTS=
+SET SPHINXBUILD=sphinx-build
+SET PAPER=
+SET SRCDIR=source
+
+IF "%PAPER%" == "" SET PAPER=a4
+SET ALLSPHINXOPTS=-d build\doctrees -D latex_paper_size=%PAPER% %SPHINXOPTS% %SRCDIR%
+
+FOR %%X IN (%SPHINXBUILD%.exe) DO SET P=%%~$PATH:X
+
+
+)
+
+FOR %%L IN (html pickle htmlhelp latex changes linkcheck) DO (
+    IF "%1" == "%%L" (
+        IF "%P%" == "" (
+            ECHO.
+            ECHO Error: Sphinx is not available. Please make sure it is correctly installed.
+            GOTO END
+        )
+        MD build\doctrees 2>NUL
+        MD build\%1 || GOTO DIR_EXIST
+        python autogen_magics.py
+        @echo "Created auto-docs for line & cell magics"
+        %SPHINXBUILD% -b %1 %ALLSPHINXOPTS% build\%1
+        IF NOT ERRORLEVEL 0 GOTO ERROR
+        ECHO.
+        ECHO Build finished. Results are in build\%1.
+        IF "%1" == "pickle" (
+            ECHO Now you can process the pickle files or run
+            ECHO    sphinx-web build\pickle to start the sphinx-web server.
+        )
+        IF "%1" == "htmlhelp" (
+            ECHO Now you can run HTML Help Workshop with the
+            ECHO    .hhp project file in build/htmlhelp.
+        )
+        IF "%1" == "linkcheck" (
+            ECHO Look for any errors in the above output
+            ECHO    or in build\linkcheck\output.rst.
+        )
+        GOTO END
+    )
+)
+
+
+IF "%1" == "clean" (
+    RD /s /q build dist %SRCDIR%\api\generated 2>NUL
+    del %SRCDIR%\magics-generated.txt 2>NUL
+
+    IF ERRORLEVEL 0 ECHO Build environment cleaned!
+    GOTO END
+)
+
+ECHO.
+ECHO Please use "make [target]" where [target] is one of:
+ECHO.
+echo    magics    to generate the magics documenatation
+ECHO    html      to make standalone HTML files
+ECHO    jsapi     to make standalone HTML files for the Javascript API
+ECHO    pickle    to make pickle files (usable by e.g. sphinx-web)
+ECHO    htmlhelp  to make HTML files and a HTML help project
+ECHO    latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ECHO    changes   to make an overview over all changed/added/deprecated items
+ECHO    linkcheck to check all external links for integrity
+GOTO END
+
+:DIR_EXIST
+ECHO.
+ECHO Info: Run "make clean" to clean build environment
+
+:ERROR
+ECHO.
+ECHO Error: Build process failed!
+
+:END
+ENDLOCAL

docs/requirements.txt

@@ -0,0 +1,4 @@
+ipython
+numpydoc
+-e .
+ipykernel