[docs] update docs build to include nbextensions provided by dependencies

.gitignore

@@ -15,6 +15,8 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build
+# nbextensions installed as part of sphinx-build
+docs/source/nbextensions
 # auto-generated Sphinx files
 docs/source/nbextensions.rst
 

.travis.yml

@@ -103,7 +103,7 @@ script:
 after_script:
   # test if TOXENV not in set
   # see http://unix.stackexchange.com/a/111518
-  - 'if ! [[ ${TOXENV} =~ ^(appveyorartifacts|check|lint)$ ]]; then tox -e coveralls,codecov; fi'
+  - 'if ! [[ ${TOXENV} =~ ^(appveyorartifacts|check|condarecipe|docs|lint)$ ]]; then tox -e coveralls,codecov; fi'
 after_failure:
   - more .tox/log/* | cat
   - more .tox/*/log/* | cat

README.md

@@ -206,7 +206,7 @@ which will
 
 For complex or customized installation scenarios, please look at the
 documentation for installing notebook extensions, server extensions, nbconvert
-pre/postprocessors and templates on the [Jupyter homepage](http://www.jupyter.org).
+pre/postprocessors and templates on the [Jupyter homepage](http://jupyter.org).
 More information can also be found in the
 [Wiki](https://github.com/ipython-contrib/jupyter_contrib_nbextensions/wiki).
 

docs/README.md

@@ -45,17 +45,17 @@ Helpful files and directories:
    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).
+by using the [recommonmark parser](https://github.com/rtfd/recommonmark).
+This is configured in the Sphinx configuration file (see above), but has some
+limitations compared to the markdown spec routinely used on, for example,
+GitHub, most notably things like:
+ * no table support
+ * no auto-linking of urls
 
 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.
+As a result, we install the nbextensions into the `docs/source` directory as
+part of the build process, in `autogen_nbextensions_list.py`. The install is
+performed using symlinks on non-windows platforms, to minimize the amount of
+writing needed. Symlinks aren't supported on Windows without admin rights, so
+we have to use the regular install process which copies the files.

docs/requirements.txt

@@ -1,4 +1,6 @@
 ipython
+jupyter_highlight_selected_word>=0.0.5
+jupyter_latex_envs>=1.3.4
 jupyter_nbextensions_configurator
 readthedocs-sphinx-ext
 recommonmark>=0.4.0

docs/source/autogen_scripts/autogen_nbextensions_list.py

@@ -12,6 +12,8 @@
 from jupyter_contrib_core.testing_utils import get_logger
 from jupyter_nbextensions_configurator import get_configurable_nbextensions
 
+import jupyter_contrib_nbextensions.install
+
 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
@@ -21,29 +23,27 @@
 
 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'))
+nbext_dir = os.path.join(doc_srcdir, 'nbextensions')
+destination = os.path.join(doc_srcdir, 'nbextensions.rst')
 
 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('-------- commencing nbextensions install')
+log.info('---- installing nbextensions into {}'.format(nbext_dir))
+do_symlink = hasattr(os, 'symlink') and os.name not in ('nt', 'dos')
+log.info('---- {}using symlinks for install'.format(
+    '' if do_symlink else 'not '))
+jupyter_contrib_nbextensions.install.toggle_install_files(
+    True, logger=log,
+    nbextensions_dir=nbext_dir,
+    overwrite=True,
+    symlink=do_symlink,
+)
+log.info('-------- finished nbextensions install')
 
-log.info('readme_rst_uri_prefix = {}'.format(readme_rst_uri_prefix))
+log.info('Writing Sphinx doc file {}'.format(destination))
 log.info('looking for nbextensions in {}...'.format(nbext_dir))
 nbextensions = sorted(
     get_configurable_nbextensions([nbext_dir], log=log),
@@ -54,7 +54,7 @@
 .. This is an automatically generated file. Do not modify by hand.
 
 List of provided nbextensions
-============================
+=============================
 
 .. toctree::
    :maxdepth: 1
@@ -65,6 +65,6 @@
     f.write(header)
     f.writelines([
         '   {}\n'.format(
-            readme_rst_uri_prefix + os.path.splitext(nbext['readme'])[0])
+            'nbextensions/' + os.path.splitext(nbext['readme'])[0])
         for nbext in nbextensions if nbext.get('readme')
     ])

docs/source/conf.py

@@ -51,26 +51,14 @@
 # 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/slidemode/slidemode2/README.md',  # noqa
-    'venv',
+    '**/.ipynb_checkpoints',
+    'nbextensions/exercise/history.md',
+    'nbextensions/slidemode/slidemode2/README.md',
+    'nbextensions/latex_envs/doc/README.md',
 ]
 
 # 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'
+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
@@ -90,6 +78,8 @@
 # Set standard backtick role
 default_role = 'code'
 
+suppress_warnings = ['image.nonlocal_uri']
+
 # -- Options for HTML output --------------------------------------------------
 
 if not on_rtd:  # only import and set the theme if we're building docs locally
@@ -129,30 +119,6 @@
      'Miscellaneous'),
 ]
 
-# -- 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')
-
-    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')
-
 # -- Run our auto-generation scripts ------------------------------------------
 for autogen_path in glob.glob(os.path.join('autogen_scripts', '*.py')):
     autogen_path = os.path.realpath(autogen_path)
@@ -171,7 +137,8 @@ def setup(app):
     def resolve_url(url):
         """Return path to code file given relative url."""
         github_root = ('https://github.com/ipython-contrib/' +
-                       'jupyter_contrib_nbextensions/blob/master/')
+                       'jupyter_contrib_nbextensions/blob/master/' +
+                       'src/jupyter_contrib_nbextensions/')
         return github_root + url.replace(os.path.sep, '/')
 
     app.add_config_value('recommonmark_config', dict(

docs/source/exporting.rst

@@ -95,14 +95,14 @@ To find the location of the custom templates you can use this function:
 Hiding cells
 ^^^^^^^^^^^^
 
-*nbextensions.tpl* and *nbextensions.tplx*<br>
+*nbextensions.tpl* and *nbextensions.tplx* <br>
 Templates for notebook extensions that allow hiding code cells, output, or text cells.
 Usage::
 
     $ jupyter nbconvert --template=nbextensions mynotebook.ipynb
-        
+
 The supported cell metadata tags are:
  * `cell.metadata.hidden` - hide complete cell
  * `cell.metadata.hide_input` - hide code cell input
  * `cell.metadata.hide_output` - hide code cell output
-   
+

docs/source/install.md

@@ -139,7 +139,7 @@ which will
 
 For complex or customized installation scenarios, please look at the
 documentation for installing notebook extensions, server extensions, nbconvert
-pre/postprocessors and templates on the [Jupyter homepage](http://www.jupyter.org).
+pre/postprocessors and templates on the [Jupyter homepage](http://jupyter.org).
 More information can also be found in the
 [Wiki](https://github.com/ipython-contrib/jupyter_contrib_nbextensions/wiki).
 

src/jupyter_contrib_nbextensions/nbextensions/addbefore/readme.md

@@ -1,3 +1,6 @@
+Addbefore
+=========
+
 This extension adds a button to add a empty cell before the currently active cell.
 As was present in IPython 1.0.
 It is with a circled up arrow.

src/jupyter_contrib_nbextensions/nbextensions/toc2/README.md

@@ -57,7 +57,7 @@ This option requires the IPython kernel and is not present with other kernels.
 ## Testing 
 - At loading of the notebook, configuration and initial rendering of the table of contents were fired on the event "notebook_loaded.Notebook". It happens that the extension is sometimes loaded *after* this event. I now rely  on a direct rendering at load and on a combination of  "notebook_loaded.Notebook" and "kernel_ready.Kernel". 
 
-- This extension also includes a quick workaround as described in [#429](https://github.com/ipython-contrib/jupyter_contrib_nbextensions/issues/429)
+- This extension also includes a quick workaround as described in [#429](https://github.com/ipython-contrib/jupyter_contrib_nbextensions/pull/429)
 
 ## History
 

tox.ini

@@ -62,8 +62,8 @@ commands =
 deps =
     -r{toxinidir}/docs/requirements.txt
 commands =
-    sphinx-build {posargs:-E} -T -b readthedocs -c docs/source . dist/docs
-    sphinx-build {posargs:-E} -T -b linkcheck   -c docs/source . dist/docs
+    sphinx-build {posargs:-E} -T -b readthedocs docs/source dist/docs
+    sphinx-build {posargs:-E} -T -b linkcheck   docs/source dist/docs
 
 [testenv:spell]
 skip_install = true