Update docs building

MANIFEST.in

@@ -8,6 +8,7 @@ include .bumpversion.cfg
 exclude .travis.yml
 exclude appveyor.yml
 exclude codecov.yml
+exclude readthedocs.yml
 
 # directory includes
 graft docs

docs/Makefile

@@ -23,7 +23,6 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo."  rst        to create rst files from markdown README files"
 	@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"
@@ -54,43 +53,43 @@ clean:
 	rm -rf source/extensions.rst
 	rm -R `ls -1 -d source/*/`
 
-rst:
+source/nbextensions.rst:
 	python source/md2rst.py
 	@echo
 	@echo "Converting readme markdown files to rst"
 
-html:
+html: source/nbextensions.rst
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml:
+dirhtml: source/nbextensions.rst
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-singlehtml:
+singlehtml: source/nbextensions.rst
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-pickle:
+pickle: source/nbextensions.rst
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json:
+json: source/nbextensions.rst
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp:
+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:
+qthelp: source/nbextensions.rst
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -99,15 +98,15 @@ qthelp:
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nbconvert.qhc"
 
-applehelp:
+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:
+devhelp: source/nbextensions.rst
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -116,85 +115,85 @@ devhelp:
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/nbconvert"
 	@echo "# devhelp"
 
-epub:
+epub: source/nbextensions.rst
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
-latex:
+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:
+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:
+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:
+text: source/nbextensions.rst
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-man:
+man: source/nbextensions.rst
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
-texinfo:
+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:
+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:
+gettext: source/nbextensions.rst
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
-changes:
+changes: source/nbextensions.rst
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck:
+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:
+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:
+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:
+xml: source/nbextensions.rst
 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
 	@echo
 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
 
-pseudoxml:
+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

@@ -0,0 +1,40 @@
+# Documenting jupyter_contrib_nbextensions
+
+[Documentation for `jupyter_contrib_nbextensions`](https://jupyter_contrib_nbextensions.readthedocs.org/en/latest/)
+is hosted on ReadTheDocs.
+
+## Build Documentation locally
+
+1. Change directory to documentation root:
+
+           $ cd docs
+
+2. Install requirements:
+
+           $ pip install -r requirements.txt
+
+3. Build documentation using Makefile for Linux and OS X:
+
+           $ make html
+
+  or on Windows:
+
+           $ make.bat html
+
+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:
+
+           $ python -m http.server 8000
+
+   In your browser, go to `http://localhost:8000`.
+
+## Developing Documentation
+
+### 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

docs/environment.yml

@@ -1,11 +1,10 @@
-name: nbextensions_docs
+name: jupyter_contrib_nbextensions_docs
 
 dependencies:
 - pandoc
 - nbformat
 - jupyter_client
 - sphinx
 - pip:
-    - nbsphinx
     - entrypoints
     - recommonmark

docs/make.bat

@@ -18,7 +18,6 @@ if "%1" == "" goto help
 if "%1" == "help" (
 	:help
 	echo.Please use `make ^<target^>` where ^<target^> is one of
-	echo.  rst        to create rst files from markdown README files
 	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
@@ -46,15 +45,16 @@ 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 "%1" == "rst" (
-	python source/md2rst.py
+if not exist source\nbextensions.rst (
+	python source\md2rst.py
 	echo.
 	echo.Converting readme markdown files to rst
-	goto end
 )
 
 REM Check if sphinx-build is available and fallback to Python version if any

docs/source/index.rst

@@ -24,7 +24,7 @@ Contents:
    :maxdepth: 2
 
    install
-   extensions
+   nbextensions
    troubleshooting
    exporting
    internals

docs/source/md2rst.py

@@ -40,7 +40,7 @@
                         copyfile(src, dst)
 
 # Generate list of extensions
-f = open('extensions.rst', 'w')
+f = open('nbextensions.rst', 'w')
 f.write(extensions)
 f.write('\n')
 f.close()

readthedocs.yml

@@ -0,0 +1,5 @@
+conda:
+    file: docs/environment.yml
+python:
+    version: 3.5
+    setup_py_install: true