Merge pull request #488 from willingc/doc-rtd

Update docs build and config for clean RTD deploys

.gitignore

@@ -25,3 +25,10 @@ src
 
 *.swp
 *.map
+.idea/
+Read the Docs
+config.rst
+
+# Ignore all in rstversions but index.rst
+docs/source/examples/Notebook/rstversions/*
+!docs/source/examples/Notebook/rstversions/index.rst

docs/Makefile

@@ -50,7 +50,7 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf source/config.rst
+	rm -rf config.rst
 
 html: source/config.rst ipynb2rst
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -62,7 +62,7 @@ source/config.rst:
 	@echo "Created docs for config options"
 
 ipynb2rst:
-	jupyter nbconvert --to rst source/examples/Notebook/*.ipynb --template=source/template --FilesWriter.build_directory=source/examples/Notebook
+	jupyter nbconvert --to rst source/examples/Notebook/*.ipynb --template=source/template --FilesWriter.build_directory=source/examples/Notebook/rstversions
 	@echo "Converted notebooks to rst"
 
 dirhtml:

docs/source/conf.py

@@ -20,8 +20,12 @@ import shlex
 # 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('.'))
 sys.path.insert(0, os.path.abspath('../..'))
 
+# Check if docs are being built by ReadTheDocs
+# If so, generate a config.rst file and populate it with documentation about
+# configuration options
 if os.environ.get('READTHEDOCS', ''):
 
     # Readthedocs doesn't run our Makefile, so we do this to force it to generate

docs/source/examples/Notebook/rstversions/index.rst

@@ -0,0 +1,37 @@
+
+`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/docs/source/examples/Notebook/Examples%20and%20Tutorials%20Index.ipynb>`__
+
+
+
+Examples and Tutorials
+======================
+
+This portion of the documentation was generated from notebook files. You
+can download the original interactive notebook files using the links at
+the tops and bottoms of the pages.
+
+Tutorials
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   What is the Jupyter Notebook
+   Notebook Basics
+   Running Code
+   Working With Markdown Cells
+   Custom Keyboard Shortcuts
+   JavaScript Notebook Extensions
+
+Examples
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   Importing Notebooks
+   Connecting with the Qt Console
+   Typesetting Equations
+
+
+`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/docs/source/examples/Notebook/Examples%20and%20Tutorials%20Index.ipynb>`__

docs/source/index.rst

@@ -24,36 +24,13 @@ The Jupyter notebook
    development
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Community documentation
-   
-   examples/Notebook/Examples and Tutorials Index
+
+   examples/Notebook/rstversions/index
 
 .. toctree::
    :maxdepth: 2
    :caption: About Jupyter Notebook
 
    changelog
-
-
-.. _old-notebook-docs:
-.. Comment: The following hidden table of contents enables `make html`
-   to build without error. If this hidden toctree is removed the build will
-   error that the old ipynb generated docs are not included in a table of contents.
-   These older docs can be accessed via the Examples and Tutorials section of
-   the current docs and the nbviewer link at the top and bottom of that page.
-
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-
-   examples/Notebook/Examples and Tutorials Index
-   examples/Notebook/What is the Jupyter Notebook
-   examples/Notebook/Notebook Basics
-   examples/Notebook/Running Code
-   examples/Notebook/Working With Markdown Cells
-   examples/Notebook/Custom Keyboard Shortcuts
-   examples/Notebook/JavaScript Notebook Extensions
-   examples/Notebook/Importing Notebooks
-   examples/Notebook/Connecting with the Qt Console
-   examples/Notebook/Typesetting Equations