[sphinx] use nbsphinx to include notebooks, include parent readme as …

…install instructions

docs/conf.py

@@ -20,20 +20,45 @@
 import sys
 sys.path.insert(0, os.path.abspath('../'))
 
+try:
+    from mock import Mock as MagicMock
+except ImportError:
+    from unittest.mock import Mock as MagicMock
+
+
+class Mock(MagicMock):
+    @classmethod
+    def __getattr__(cls, name):
+        return Mock()
+
+    __name__ = "Mock"
+
+MOCK_MODULES = ['mdtraj',
+                'mdtraj.reporters',
+                'ujson',
+                'pymongo',
+                'pymongo.errors',
+                'gridfs',
+                'numpy',
+                'simtk',
+                'simtk.unit',
+                'simtk.openmm',
+                'simtk.openmm.app',
+                'pyemma.coordinates',
+                ]
+
+sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
 # needs_sphinx = '1.0'
 
-import adaptivemd
-import adaptivemd.version
-import pyemma.coordinates
+from adaptivemd import version as v
 
 print("Generating doc for AdaptiveMD version {version} installed in {path}"
-      .format(version=adaptivemd.version.short_version,
-              path=adaptivemd.__path__))
+      .format(version=v.short_version, path=v.__file__))
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -45,9 +70,11 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
-    'sphinx.ext.autosummary'
+    'sphinx.ext.autosummary',
+    'nbsphinx',
 ]
 
+nbsphinx_execute = 'never'
 
 # issuetracker = 'github'
 # issuetracker_project = 'markovmodel/adaptivemd'
@@ -57,18 +84,20 @@
 
 
 # add pandoc directives
-pandoc_from = ['markdown', 'mediawiki']
-
-sys.path.insert(0, os.path.abspath('sphinxext'))
-extensions.append('notebook_sphinxext')
-extensions.append('pandoc_sphinxext')
+#pandoc_from = ['markdown', 'mediawiki']
 
+#sys.path.insert(0, os.path.abspath('sphinxext'))
+#extensions.append('notebook_sphinxext')
+#extensions.append('pandoc_sphinxext')
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+
+# markdown support: https://blog.readthedocs.com/adding-markdown-support/
+from recommonmark.parser import CommonMarkParser
+source_suffix = ['.rst', '.md']
+source_parsers = {'.md': CommonMarkParser,}
 
 # The master toctree document.
 master_doc = 'index'
@@ -83,9 +112,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = adaptivemd.version.short_version
+version = v.short_version
 # The full version, including alpha/beta/rc tags.
-release = adaptivemd.version.short_version
+release = v.full_version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -97,7 +126,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**/.ipynb_checkpoints', ]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -218,68 +247,3 @@
 napoleon_use_ivar = True
 napoleon_use_param = True
 napoleon_use_rtype = True
-
-
-from adaptivemd.mongodb import StorableMixin
-
-
-# try to exclude deprecated
-def skip_unwanted(app, what, name, obj, skip, options):
-    if hasattr(StorableMixin, name):
-        return True
-
-    return skip or False
-
-
-def setup(app):
-    app.connect('autodoc-skip-member', skip_unwanted)
-    try:
-        from sphinx.ext.autosummary import Autosummary
-        from sphinx.ext.autosummary import get_documenter
-        from docutils.parsers.rst import directives
-        from sphinx.util.inspect import safe_getattr
-        import re
-
-        class AutoAutoSummary(Autosummary):
-
-            option_spec = {
-                'methods': directives.unchanged,
-                'attributes': directives.unchanged
-            }
-
-            required_arguments = 1
-
-            @staticmethod
-            def get_members(obj, typ, include_public=None):
-                if not include_public:
-                    include_public = []
-                items = []
-                for name in dir(obj):
-                    try:
-                        documenter = get_documenter(safe_getattr(obj, name), obj)
-                    except AttributeError:
-                        continue
-                    if documenter.objtype == typ:
-                        items.append(name)
-                public = [x for x in items if x in include_public or not x.startswith('_')]
-                return public, items
-
-            def run(self):
-                clazz = self.arguments[0]
-                try:
-                    (module_name, class_name) = clazz.rsplit('.', 1)
-                    m = __import__(module_name, globals(), locals(), [class_name])
-                    c = getattr(m, class_name)
-                    if 'methods' in self.options:
-                        _, methods = self.get_members(c, 'method', ['__init__'])
-
-                        self.content = ["~%s.%s" % (clazz, method) for method in methods if not method.startswith('_') and not hasattr(StorableMixin, method)]
-                    if 'attributes' in self.options:
-                        _, attribs = self.get_members(c, 'attribute')
-                        self.content = ["~%s.%s" % (clazz, attrib) for attrib in attribs if not attrib.startswith('_')]
-                finally:
-                    return super(AutoAutoSummary, self).run()
-
-        app.add_directive('autoautosummary', AutoAutoSummary)
-    except BaseException as e:
-        raise e

docs/examples/example1.rst

@@ -3,4 +3,6 @@
 Example 1 - Setup
 =================
 
-.. notebook:: examples/tutorial/1_example_setup_project.ipynb
+.. toctree::
+
+   ../examples_nb/tutorial/1_example_setup_project

docs/examples/example2.rst

@@ -3,4 +3,6 @@
 Example 2 - Run
 ===============
 
-.. notebook:: examples/tutorial/2_example_run.ipynb
+.. toctree::
+
+  ../examples_nb/tutorial/2_example_run.ipynb

docs/examples/example3.rst

@@ -3,4 +3,6 @@
 Example 3 - Adaptive
 ====================
 
-.. notebook:: examples/tutorial/3_example_adaptive.ipynb
+.. toctree::
+
+   ../examples_nb/tutorial/3_example_adaptive.ipynb

docs/examples/example4.rst

@@ -3,4 +3,6 @@
 Example 4 - Tasks
 =================
 
-.. notebook:: examples/tutorial/4_example_advanced_tasks.ipynb
+.. toctree::
+
+  ../examples_nb/tutorial/4_example_advanced_tasks.ipynb

docs/examples/example5.rst

@@ -3,4 +3,6 @@
 Example 5 - Generators
 ======================
 
-.. notebook:: examples/tutorial/5_example_advanced_generators.ipynb
+.. toctree::
+
+  ../examples_nb/tutorial/5_example_advanced_generators.ipynb

docs/examples/example6.rst

@@ -3,4 +3,6 @@
 Example 6 - Multiple Output Types
 =================================
 
-.. notebook:: examples/tutorial/6_example_multi_traj_type.ipynb
+.. toctree::
+
+  ../examples_nb/tutorial/6_example_multi_traj_type.ipynb

docs/examples_nb

@@ -0,0 +1 @@
+../examples

docs/install.rst

@@ -1,2 +1,7 @@
+installation
+============
 
-.. markdown:: README.md
+
+.. toctree::
+
+   readme_parent

docs/readme_parent.md

@@ -0,0 +1 @@
+../README.md

docs/requirements.txt

@@ -0,0 +1,5 @@
+sphinx_rtd_theme
+nbsphinx
+IPython
+recommonmark
+jupyter_client