new docs build method

* build docs through tox environment
 * build docs on travis. Travis build checks that we haven't broken docs which would get pushed to rtd
 * generate docs directly from repo markdown using recommonmark, rather than converting into new files with pandoc
 * unpin recommonmark version
 * remove redundant makefiles, rely on tox to do our docs building (we don't really reliably support anything bar html/json generation anyway)
 * remove redundant conda `docs/environment.yml`
 * fix docs version using `.bumpversion.cfg`
 * update docs readme

.bumpversion.cfg

@@ -9,3 +9,5 @@ tag_name = {new_version}
 
 [bumpversion:file:src/jupyter_contrib_nbextensions/__init__.py]
 
+[bumpversion:file:docs/source/conf.py]
+

.gitignore

@@ -15,6 +15,8 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build
+# auto-generated Sphinx files
+docs/source/nbextensions.rst
 
 .idea
 

.travis.yml

@@ -19,6 +19,10 @@ matrix:
     - os: linux
       python: '3.4'
       env: TOXENV=lint
+    # check docs build correctly
+    - os: linux
+      python: '3.4'
+      env: TOXENV=docs
     # linux, various python and notebook versions
     - os: linux
       python: '3.4'

docs/Makefile

@@ -1,199 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = build
-
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-.PHONY: help clean rst html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  applehelp  to make an Apple Help Book"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-	@echo "  coverage   to run coverage check of the documentation (if enabled)"
-
-clean:
-	rm -rf $(BUILDDIR)/*
-	rm -rf source/nbextensions.rst
-	rm -R `ls -1 -d source/*/`
-
-source/nbextensions.rst:
-	python source/md2rst.py
-	@echo
-	@echo "Converting readme markdown files to rst"
-
-html: source/nbextensions.rst
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml: source/nbextensions.rst
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml: source/nbextensions.rst
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle: source/nbextensions.rst
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json: source/nbextensions.rst
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp: source/nbextensions.rst
-	$(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."
-
-qthelp: source/nbextensions.rst
-	$(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:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nbconvert.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nbconvert.qhc"
-
-applehelp: source/nbextensions.rst
-	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
-	@echo
-	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
-	@echo "N.B. You won't be able to view it unless you put it in" \
-	      "~/Library/Documentation/Help or install it in your application" \
-	      "bundle."
-
-devhelp: source/nbextensions.rst
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/nbconvert"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/nbconvert"
-	@echo "# devhelp"
-
-epub: source/nbextensions.rst
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex: source/nbextensions.rst
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf: source/nbextensions.rst
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja: source/nbextensions.rst
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text: source/nbextensions.rst
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man: source/nbextensions.rst
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo: source/nbextensions.rst
-	$(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: source/nbextensions.rst
-	$(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."
-
-gettext: source/nbextensions.rst
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes: source/nbextensions.rst
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck: source/nbextensions.rst
-	$(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."
-
-doctest: source/nbextensions.rst
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-coverage: source/nbextensions.rst
-	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
-	@echo "Testing of coverage in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/coverage/python.txt."
-
-xml: source/nbextensions.rst
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-
-pseudoxml: source/nbextensions.rst
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/README.md

@@ -1,40 +1,61 @@
-# Documenting jupyter_contrib_nbextensions
+Documenting jupyter_contrib_nbextensions
+========================================
 
-[Documentation for `jupyter_contrib_nbextensions`](https://jupyter_contrib_nbextensions.readthedocs.org/en/latest/)
-is hosted on ReadTheDocs.
+Documentation for `jupyter_contrib_nbextensions`
+is [hosted on ReadTheDocs](https://jupyter_contrib_nbextensions.readthedocs.org/en/latest/).
 
-## Build Documentation locally
 
-1. Change directory to documentation root:
+Building the documentation locally
+----------------------------------
 
-           $ cd docs
+The easiest way to build the docs locally is to use the provided tox
+environment, `docs`. Essentially this just installs the correct dependencies
+into a vitrualenv, and calls `sphinx-build` with the correct arguments.
+See the repo's [tox.ini](../tox.ini) for details.
 
-2. Install requirements:
+From the repository root:
 
-           $ pip install -r requirements.txt
+1. Install tox:
 
-3. Build documentation using Makefile for Linux and OS X:
+    $ pip install tox
 
-           $ make html
+2. Run the tox environment:
 
-  or on Windows:
+    $ tox -e docs
 
-           $ make.bat html
+3. Display the documentation locally by navigating to `build/html/index.html`
+   in your browser.
 
-4. Display the documentation locally by navigating to
-   ``build/html/index.html`` in your browser:
+   Or alternatively you may run a local server to display the docs.
+   In Python 3:
 
-   Or alternatively you may run a local server to display
-   the docs. In Python 3:
+      $ python -m http.server 8000
 
-           $ python -m http.server 8000
+   Then, in your browser, go to `http://localhost:8000`.
 
-   In your browser, go to `http://localhost:8000`.
 
-## Developing Documentation
+Developing Documentation
+------------------------
 
-### Helpful files and directories
+Helpful files and directories:
 
-* `source` directory - source for documentation
-* `source/conf.py` - Sphinx build configuration file
-* `source/md2rst.py` - Generates rst files from readme markdown files of individual extensions
+ * `source` directory - source files for documentation.
+ * [source/conf.py](source/conf.py) - Sphinx build configuration file.
+ * [source/autogen_scripts/autogen_nbextensions_list.py](source/autogen_scripts/autogen_nbextensions_list.py) -
+   Generates an rst file listing each of the provided nbextensions readmes.
+
+The readme files for each nbextension are incorporated into the documentation
+by using pandoc to convert them into rst as part of the parsing step.
+This is configured in the Sphinx configuration file (see above).
+
+In order to get the nbextensions' readmes to build in sphinx, they _must_ be
+inside the docs `source_dir`.
+As a result, we call sphinx-build with the repository root as the `source_dir`,
+and specify `docs/source` as the config directory (where sphinx can find
+`conf.py`).
+
+On ReadTheDocs, however, we _cannot_ specify a `source_dir` different from the
+config directory. As an alternative, we use a symlink to bring the readmes into
+the source directory. This would in principle be a better solution altogether,
+but symlinks aren't supported on Windows without admin rights, so we have to
+use the hack detailed above.

docs/environment.yml

@@ -1,11 +0,0 @@
-name: nbextensions
-channels:
-- conda-forge
-dependencies:
-- pandoc
-- pypandoc
-- sphinx
-- sphinx_rtd_theme
-- pip:
-    - recommonmark
-

docs/make.bat

@@ -1,272 +0,0 @@
-@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set BUILDDIR=build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
-set I18NSPHINXOPTS=%SPHINXOPTS% source
-if NOT "%PAPER%" == "" (
-	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
-	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
-)
-
-if "%1" == "" goto help
-
-if "%1" == "help" (
-	:help
-	echo.Please use `make ^<target^>` where ^<target^> is one of
-	echo.  html       to make standalone HTML files
-	echo.  dirhtml    to make HTML files named index.html in directories
-	echo.  singlehtml to make a single large HTML file
-	echo.  pickle     to make pickle files
-	echo.  json       to make JSON files
-	echo.  htmlhelp   to make HTML files and a HTML help project
-	echo.  qthelp     to make HTML files and a qthelp project
-	echo.  devhelp    to make HTML files and a Devhelp project
-	echo.  epub       to make an epub
-	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
-	echo.  text       to make text files
-	echo.  man        to make manual pages
-	echo.  texinfo    to make Texinfo files
-	echo.  gettext    to make PO message catalogs
-	echo.  changes    to make an overview over all changed/added/deprecated items
-	echo.  xml        to make Docutils-native XML files
-	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
-	echo.  linkcheck  to check all external links for integrity
-	echo.  doctest    to run all doctests embedded in the documentation if enabled
-	echo.  coverage   to run coverage check of the documentation if enabled
-	goto end
-)
-
-if "%1" == "clean" (
-	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
-	del /q /s %BUILDDIR%\*
-	for /d %%i in (source\*) do rmdir /q /s %%i
-	if exist soruce\nbextensions.rst (
-		del /q /s source\nbextensions.rst
-	)
-	goto end
-)
-
-if not exist source\nbextensions.rst (
-	python source\md2rst.py
-	echo.
-	echo.Converting readme markdown files to rst
-)
-
-REM Check if sphinx-build is available and fallback to Python version if any
-%SPHINXBUILD% 2> nul
-if errorlevel 9009 goto sphinx_python
-goto sphinx_ok
-
-:sphinx_python
-
-set SPHINXBUILD=python -m sphinx.__init__
-%SPHINXBUILD% 2> nul
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-:sphinx_ok
-
-
-if "%1" == "html" (
-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
-)
-
-if "%1" == "dirhtml" (
-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
-	goto end
-)
-
-if "%1" == "singlehtml" (
-	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
-	goto end
-)
-
-if "%1" == "pickle" (
-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the pickle files.
-	goto end
-)
-
-if "%1" == "json" (
-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the JSON files.
-	goto end
-)
-
-if "%1" == "htmlhelp" (
-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
-	goto end
-)
-
-if "%1" == "qthelp" (
-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\nbconvert.qhcp
-	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\nbconvert.ghc
-	goto end
-)
-
-if "%1" == "devhelp" (
-	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished.
-	goto end
-)
-
-if "%1" == "epub" (
-	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The epub file is in %BUILDDIR%/epub.
-	goto end
-)
-
-if "%1" == "latex" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdf" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf
-	cd %~dp0
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "latexpdfja" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf-ja
-	cd %~dp0
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "text" (
-	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The text files are in %BUILDDIR%/text.
-	goto end
-)
-
-if "%1" == "man" (
-	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The manual pages are in %BUILDDIR%/man.
-	goto end
-)
-
-if "%1" == "texinfo" (
-	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
-	goto end
-)
-
-if "%1" == "gettext" (
-	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
-	goto end
-)
-
-if "%1" == "changes" (
-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.The overview file is in %BUILDDIR%/changes.
-	goto end
-)
-
-if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
-	goto end
-)
-
-if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-	goto end
-)
-
-if "%1" == "coverage" (
-	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of coverage in the sources finished, look at the ^
-results in %BUILDDIR%/coverage/python.txt.
-	goto end
-)
-
-if "%1" == "xml" (
-	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The XML files are in %BUILDDIR%/xml.
-	goto end
-)
-
-if "%1" == "pseudoxml" (
-	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
-	goto end
-)
-
-:end

docs/requirements.txt

@@ -1,7 +1,6 @@
-pandoc
-pypandoc
+ipython
+jupyter_nbextensions_configurator
+readthedocs-sphinx-ext
+recommonmark>=0.4.0
 sphinx>=1.3.6
 sphinx_rtd_theme
-recommonmark==0.4.0
-entrypoints
-

docs/source/autogen_scripts/autogen_nbextensions_list.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python
+"""
+Create nbextensions.rst, a Sphinx documentation source file.
+
+Links to documentation for each of the nbextensions provided by the
+jupyter_contrib_nbextensions package.
+"""
+
+import logging
+import os
+
+from jupyter_contrib_core.testing_utils import get_logger
+from jupyter_nbextensions_configurator import get_configurable_nbextensions
+
+log = get_logger(name=os.path.basename(__file__), log_level=logging.INFO)
+
+# Set on_rtd to whether we are building on readthedocs. We get this test from
+# docs.readthedocs.io
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+log.info('on_rtd = {}'.format(on_rtd))
+
+doc_autogen_dir = os.path.dirname(__file__)
+doc_srcdir = os.path.dirname(doc_autogen_dir)
+doc_root = os.path.dirname(doc_srcdir)
+pkg_root = os.path.dirname(doc_root)
+destination = os.path.join(doc_root, 'source', 'nbextensions.rst')
+nbext_dir = os.path.realpath(os.path.join(
+    pkg_root, 'src', 'jupyter_contrib_nbextensions', 'nbextensions'))
+
+log.info('doc_autogen_dir = {}'.format(doc_autogen_dir))
+log.info('doc_srcdir = {}'.format(doc_srcdir))
+log.info('doc_root = {}'.format(doc_root))
+log.info('pkg_root = {}'.format(pkg_root))
+log.info('nbext_dir = {}'.format(nbext_dir))
+
+log.info('Writing Sphinx doc file {}'.format(destination))
+
+# readthedocs doesn't allow us to specify the docs source_dir, but assumes
+# it to be the same as the parent dir of this file. As such, we cheat for rtd
+# by inserting a symlink, which requires us to alter the relative paths from
+# the nbextensions.rst list to the readme files.
+readme_rst_uri_prefix = (
+    'nbextensions/' if on_rtd else
+    '../../src/jupyter_contrib_nbextensions/nbextensions/')
+
+log.info('readme_rst_uri_prefix = {}'.format(readme_rst_uri_prefix))
+log.info('looking for nbextensions in {}...'.format(nbext_dir))
+nbextensions = sorted(
+    get_configurable_nbextensions([nbext_dir], log=log),
+    key=lambda a: a['Name'].lower())
+
+header = """
+
+.. This is an automatically generated file. Do not modify by hand.
+
+List of provided nbxtensions
+============================
+
+.. toctree::
+   :maxdepth: 1
+
+"""
+
+with open(destination, 'w') as f:
+    f.write(header)
+    f.writelines([
+        '   {}\n'.format(
+            readme_rst_uri_prefix + os.path.splitext(nbext['readme'])[0])
+        for nbext in nbextensions if nbext.get('readme')
+    ])

docs/source/conf.py

@@ -1,319 +1,185 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
-# nbconvert documentation build configuration file, created by
-# sphinx-quickstart on Tue Jun  9 17:11:30 2015.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+# jupyter_contrib_nbextensions sphinx documentation build configuration file.
+# This file gets execfile()d with the current directory set to its containing
+# dir.
 
+import datetime
+import glob
+import logging
 import os
-from recommonmark.parser import CommonMarkParser
+
+from jupyter_contrib_core.testing_utils import get_logger
 from recommonmark.transform import AutoStructify
+from recommonmark.parser import CommonMarkParser
 
+log = get_logger(name=os.path.basename(__file__), log_level=logging.INFO)
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+# Set on_rtd to whether we are building on readthedocs. We get this test from
+# docs.readthedocs.io
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+log.info('on_rtd = {}'.format(on_rtd))
 
-if os.environ.get('READTHEDOCS', ''):
-    # RTD doesn't use the repo's Makefile to build docs. We run
-    # autogen_config.py to create the config docs (i.e. Configuration Options
-    # page).
-
-    with open('md2rst.py') as f:
-        exec(compile(f.read(), 'md2rst.py', 'exec'), {})
-
-
-# -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
-source_parsers = {
-    '.md': CommonMarkParser,
+# mappings to other sphinx docs
+intersphinx_mapping = {
+    'ipython': ('http://ipython.org/ipython-doc/dev/', None),
+    'nbconvert': ('http://nbconvert.readthedocs.io/en/latest/', None),
+    'nbformat': ('http://nbformat.readthedocs.io/en/latest/', None),
+    'jupyter': ('http://jupyter.readthedocs.io/en/latest/', None),
 }
 
+# General information about the project.
+project = 'jupyter_contrib_nbextensions'
+copyright = '2015-{}, Jupyter Contrib Team'.format(datetime.date.today().year)
+author = 'Jupyter Contrib Team'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.2.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.2.1'
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of strings
+source_suffix = ['.rst', '.md']
+source_parsers = {'.md': CommonMarkParser}
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = [
+    '.ipynb_checkpoints',
+    '.tox',
+    'build',
+    'COPYING.rst',
+    'dist',
+    'docs/README.md',
+    'example.ipynb',
+    'README.md',
+    'src/jupyter_contrib_nbextensions/nbextensions/exercise/history.md',
+    'src/jupyter_contrib_nbextensions/nbextensions/latex_envs/doc/README.md',
+    ('src/jupyter_contrib_nbextensions/nbextensions/' +
+     'slidemode/slidemode2/README.md'),
+    'venv',
+]
+
+# The master toctree document.
+master_doc = 'docs/source/index'
+if on_rtd:
+    # readthedocs doesn't allow us to specify the docs source_dir, but assumes
+    # it to be the same as the parent dir of this file. As such, we must adapt
+    # paths slightly:
+    master_doc = 'index'
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'IPython.sphinxext.ipython_console_highlighting',
     'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    'sphinx.ext.mathjax',
 ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = ['.rst', '.ipynb', '.md' ]
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = 'nbextensions'
-from datetime import date
-year = date.today().year
-copyright = '2015-%s, Jupyter Contrib Team' % year
-author = 'Jupyter Contrib Team'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['.ipynb_checkpoints', 'example.ipynb']
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-
-# -- Options for HTML output ----------------------------------------------
-
-# Set on_rtd to whether we are building on readthedocs.org. We get this line of
-# code grabbed from docs.readthedocs.org
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+# -- Options for HTML output --------------------------------------------------
 
 if not on_rtd:  # only import and set the theme if we're building docs locally
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
 # otherwise, readthedocs.org uses their default theme, so no need to specify it
 
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#html_theme = 'sphinx_rtd_theme'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#html_extra_path = []
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
-#html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# Now only 'ja' uses this config value
-#html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-#html_search_scorer = 'scorer.js'
-
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'nbconvertdoc'
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-
-# Latex figure (float) alignment
-#'figure_align': 'htbp',
-}
+htmlhelp_basename = project + '_doc'
 
+# -- Options for LaTeX output -------------------------------------------------
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, 'nbextensions.tex', 'Contributed Notebook Extensions Documentation',
-   'Jupyter Contrib Team', 'manual'),
+    (master_doc, project + '_doc.tex',
+     'Jupyter-contrib Notebook Extensions Documentation', author, 'manual'),
 ]
 
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output ---------------------------------------
-
+# -- Options for man-page output ----------------------------------------------
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'nbextensions', 'nbextensions Documentation',
-     [author], 1)
+    (master_doc, project,
+     'Jupyter-contrib Notebook Extensions Documentation', [author], 1)
 ]
 
-# If true, show URL addresses after external links.
-#man_show_urls = False
-
-
-# -- Options for Texinfo output -------------------------------------------
-
+# -- Options for Texinfo output -----------------------------------------------
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  (master_doc, 'nbextensions', 'nbextensions Documentation',
-   author, 'nbextensions', 'Contributed Jupyter Notebook Extensions.',
-   'Miscellaneous'),
+    (master_doc, project + '_doc',
+     'Jupyter-contrib Notebook Extensions Documentation', author,
+     'nbextensions', 'Contributed Jupyter Notebook Extensions.',
+     'Miscellaneous'),
 ]
 
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
+# -- ReadTheDocs cheats -------------------------------------------------------
+# readthedocs doesn't allow us to specify the docs source_dir, but assumes
+# it to be the same as the parent dir of this file. As such, we must cheat:
+if on_rtd:
+    log.info('-------- on_rtd commencing symlink cheat')
+    doc_srcdir = os.path.dirname(__file__)
+    doc_root = os.path.dirname(doc_srcdir)
+    pkg_root = os.path.dirname(doc_root)
+    nbext_dir = os.path.join(
+        pkg_root, 'src', 'jupyter_contrib_nbextensions', 'nbextensions')
+    nbext_dir_symlink = os.path.join(doc_root, 'source', 'nbextensions')
 
-# If false, no module index is generated.
-#texinfo_domain_indices = True
+    log.info('- doc_srcdir = {}'.format(doc_srcdir))
+    log.info('- doc_root = {}'.format(doc_root))
+    log.info('- pkg_root = {}'.format(pkg_root))
+    log.info('- nbext_dir = {}'.format(nbext_dir))
+    log.info('- nbext_dir_symlink = {}'.format(nbext_dir_symlink))
+    if os.path.exists(nbext_dir_symlink):
+        log.info('- removing {}'.format(nbext_dir_symlink))
+        os.remove(nbext_dir_symlink)
+    log.info('- symlinking {} at {}'.format(nbext_dir, nbext_dir_symlink))
+    os.symlink(nbext_dir, nbext_dir_symlink)
+    log.info('-------- on_rtd finished symlink cheat')
 
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
+# -- Run our auto-generation scripts ------------------------------------------
+for autogen_path in glob.glob(os.path.join('autogen_scripts', '*.py')):
+    autogen_path = os.path.realpath(autogen_path)
+    log.info('> running autogen script {}'.format(
+        os.path.relpath(autogen_path, os.path.dirname(__file__))))
+    with open(autogen_path) as f:
+        _code = compile(f.read(), autogen_path, 'exec')
+        exec(_code, {'__file__': autogen_path})
 
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
 
 def setup(app):
-    app.add_config_value('recommonmark_config', {
-            'url_resolver': lambda url: 'abc' + url,
-            'auto_toc_tree_section': 'Contents',
-            }, True)
-    app.add_transform(AutoStructify )
+    if not on_rtd:
+        from readthedocs_ext.readthedocs import ReadtheDocsBuilder
+        app.add_builder(ReadtheDocsBuilder)
 
+    def resolve_url(url):
+        """Return path to code file given relative url."""
+        github_root = ('https://github.com/ipython-contrib/' +
+                       'jupyter_contrib_nbextensions/blob/master/')
+        return github_root + url.replace(os.path.sep, '/')
+
+    app.add_config_value('recommonmark_config', dict(
+        enable_auto_toc_tree=True,
+        auto_toc_tree_section='Contents',
+        enable_auto_doc_ref=True,
+        enable_math=True,
+        enable_inline_math=True,
+        url_resolver=resolve_url,
+        enable_eval_rst=False,
+    ), True)
+    app.add_transform(AutoStructify)

docs/source/md2rst.py

@@ -1,51 +0,0 @@
-# Use pandoc to convert readme md files to rst and copy images to a place sphinx can process them.
-# Afterwards, generate a rst file with links to all extensions
-import sys
-import os
-from shutil import copyfile
-import pypandoc
-
-extensions = """
-List of Extensions
-==================
-
-.. toctree::
-   :maxdepth: 1
-
-"""
-
-destination = 'source'
-if not os.path.exists(destination):
-    destination = '.'
-print('Copying converted docs to %s directory' % destination)
-src_path = os.path.join(destination, '..', '..', 'src', 'jupyter_contrib_nbextensions', 'nbextensions')
-for root, directories, filenames in os.walk(src_path):
-    for filename in filenames:
-        ext = os.path.splitext(filename)
-        if 'md' in ext[1]:
-            md_filename = os.path.join(root, filename)
-            rst_path = os.path.join(os.path.split(root)[-1])
-            src_path = os.path.join(destination, rst_path)
-            if not os.path.exists(src_path):
-                os.mkdir(src_path)
-            rst_name = ext[0]+'.rst'
-            rst_filename = os.path.join(src_path, rst_name)
-            output = pypandoc.convert_file(md_filename, format='md', to='rst', outputfile=rst_filename)
-            extensions += '   %s/%s\n' % (rst_path, ext[0])
-            # copy images
-            for root2, directories2, filenames2 in os.walk(root):
-                for name2 in filenames2:
-                    ext2 = os.path.splitext(name2)
-                    if ext2[1].strip('.').lower() in ['jpg', 'png', 'gif']:
-                        src = os.path.join(root2, name2)
-                        dst = os.path.join(src_path, name2)
-                        print('Destination: %s' % dst)
-                        copyfile(src, dst)
-
-# Write list of extensions
-extname = os.path.join(destination, 'nbextensions.rst')
-f = open(extname, 'w')
-f.write(extensions)
-f.write('\n')
-f.close()
-

tox.ini

@@ -16,8 +16,8 @@ basepython =
     py33: {env:TOXPYTHON:python3.3}
     py34: {env:TOXPYTHON:python3.4}
     py35: {env:TOXPYTHON:python3.5}
-    {docs,spell}: {env:TOXPYTHON:python2.7}
-    {appveyorartifacts,bump,check,clean,codecov,condarecipe,coveralls,lint,report,pypi_build,pypi_upload}: {env:TOXPYTHON:python3.4}
+    {spell}: {env:TOXPYTHON:python2.7}
+    {appveyorartifacts,bump,check,clean,codecov,condarecipe,coveralls,docs,lint,report,pypi_build,pypi_upload}: {env:TOXPYTHON:python3.4}
 setenv =
     PYTHONPATH={toxinidir}/tests
     PYTHONUNBUFFERED=yes
@@ -60,8 +60,8 @@ commands =
 deps =
     -r{toxinidir}/docs/requirements.txt
 commands =
-    sphinx-build {posargs:-E} -b html docs dist/docs
-    sphinx-build -b linkcheck docs dist/docs
+    sphinx-build {posargs:-E} -T -b readthedocs -c docs/source . dist/docs
+    sphinx-build {posargs:-E} -T -b linkcheck   -c docs/source . dist/docs
 
 [testenv:spell]
 skip_install = true