Fixes to use latest sphinx (#1139)

* Fixes to use latest sphinx

* Update requirements to make allensdk install work

* Remove gallery35 tests -- allensdk incompatible with py35

.circleci/config.yml

@@ -193,13 +193,6 @@ jobs:
       - TEST_WHEELINSTALL_ENV: "wheelinstall-py37"
     <<: *conda-steps
 
-  gallery35:
-    docker:
-      - image: circleci/python:3.5.7-jessie
-    environment:
-     - TEST_TOX_ENV: "gallery-py35"
-    <<: *gallery-steps
-
   gallery36:
     docker:
       - image: circleci/python:3.6.3-jessie
@@ -279,8 +272,6 @@ workflows:
           <<: *no_filters
       - miniconda37:
           <<: *no_filters
-      - gallery35:
-          <<: *no_filters
       - gallery36:
           <<: *no_filters
       - gallery37:
@@ -294,7 +285,6 @@ workflows:
             - miniconda35
             - miniconda36
             - miniconda37
-            - gallery35
             - gallery36
             - gallery37
           filters:
@@ -314,7 +304,6 @@ workflows:
             - miniconda35
             - miniconda36
             - miniconda37
-            - gallery35
             - gallery36
             - gallery37
           filters:

docs/Makefile

@@ -9,12 +9,12 @@ PAPER          =
 BUILDDIR       = _build
 SRCDIR         = ../src
 RSTDIR         = source
-PKGNAME        = {pynwb,form}
+PKGNAME        = pynwb
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(RSTDIR)
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -41,10 +41,11 @@ help:
 	@echo "  changes    to make an overview of all changed/added/deprecated items"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-	@echo "  apidoc     to to build RST from source code"
+	@echo "  clean      to clean all documents built by Sphinx in _build"
+	@echo "  apidoc     to build RST from source code"
 
 clean:
-	-rm -rf $(BUILDDIR)/* $(RSTDIR)/$(PKGNAME)*.rst $(RSTDIR)/modules.rst
+	-rm -rf $(BUILDDIR)/* $(RSTDIR)/$(PKGNAME)*.rst
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -158,6 +159,5 @@ doctest:
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
 apidoc:
-	$(SPHINXAPIDOC) -f -e -o $(RSTDIR)  $(SRCDIR)
+	$(SPHINXAPIDOC) -f -e --no-toc -o $(RSTDIR) $(SRCDIR)
 	@echo "Build rst docs from source code."
-

docs/gallery/domain/brain_observatory.py

@@ -9,6 +9,8 @@
 # This example demostrates the basic functionality of several parts of the pynwb write API, centered around the optical
 # physiology submodule (pynwb.ophys). We will use the allensdk as a read API, while leveraging the pynwb data model and
 # write api to transform and write the data back to disk.
+#
+# .. note: Using the latest allensdk package requires Python 3.6 or higher.
 
 ########################################
 # .. raw:: html

docs/make.bat

@@ -5,8 +5,14 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
+if "%SPHINXAPIDOC%" == "" (
+	set SPHINXAPIDOC=sphinx-apidoc
+)
 set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set RSTDIR=source
+set SRCDIR=../src
+set PKGNAME=pynwb
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% %RSTDIR%
 set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
@@ -35,12 +41,15 @@ if "%1" == "help" (
 	echo.  changes    to make an overview over all changed/added/deprecated items
 	echo.  linkcheck  to check all external links for integrity
 	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	echo.  clean      to clean all documents built by Sphinx in _build
+	echo.  apidoc     to build RST from source code"
 	goto end
 )
 
 if "%1" == "clean" (
 	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
 	del /q /s %BUILDDIR%\*
+	del /q %RSTDIR%\%PKGNAME%*.rst
 	goto end
 )
 
@@ -187,4 +196,12 @@ results in %BUILDDIR%/doctest/output.txt.
 	goto end
 )
 
+if "%1" == "apidoc" (
+	%SPHINXAPIDOC% -f -e --no-toc -o %RSTDIR% %SRCDIR%
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build rst docs from source code.
+	goto end
+)
+
 :end

docs/source/conf.py

@@ -14,7 +14,6 @@
 import sys
 import os
 import sphinx_rtd_theme
-from sphinx.domains.python import PythonDomain
 
 
 # -- Support building doc without install --------------------------------------
@@ -71,9 +70,8 @@
 }
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3.5', None),
+    'python': ('https://docs.python.org/3.8', None),
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
     'matplotlib': ('https://matplotlib.org', None),
     'h5py': ('http://docs.h5py.org/en/latest/', None),
     'hdmf': ('https://hdmf.readthedocs.io/en/latest/', None),
@@ -173,7 +171,7 @@
 # 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 = 'favicon-96.png'
+html_favicon = 'favicon_96.png'
 
 # 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,
@@ -247,7 +245,7 @@
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-# latex_logo = None
+latex_logo = 'logo.pdf'
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
@@ -307,27 +305,17 @@
 #
 
 def run_apidoc(_):
-    from sphinx.apidoc import main
+    from sphinx.ext.apidoc import main as apidoc_main
     import os
     import sys
     out_dir = os.path.dirname(__file__)
     src_dir = os.path.join(out_dir, '../../src')
     sys.path.append(src_dir)
-    main(['-f', '-e', '-o', out_dir, src_dir])
-
-
-# https://github.com/sphinx-doc/sphinx/issues/3866
-class PatchedPythonDomain(PythonDomain):
-    def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
-        if 'refspecific' in node:
-            del node['refspecific']
-        return super(PatchedPythonDomain, self).resolve_xref(
-            env, fromdocname, builder, typ, target, node, contnode)
+    apidoc_main(['-f', '-e', '--no-toc', '-o', out_dir, src_dir])
 
 
 from abc import abstractproperty
 
-
 def skip(app, what, name, obj, skip, options):
     if isinstance(obj, abstractproperty) or getattr(obj, '__isabstractmethod__', False):
         return False
@@ -339,5 +327,4 @@ def skip(app, what, name, obj, skip, options):
 def setup(app):
     app.connect('builder-inited', run_apidoc)
     app.add_stylesheet("theme_overrides.css")  # overrides for wide tables in RTD theme
-    app.override_domain(PatchedPythonDomain)
     app.connect("autodoc-skip-member", skip)

requirements-doc.txt

@@ -1,8 +1,7 @@
-sphinx==1.8.5
+sphinx
 matplotlib
-pillow
 sphinx_rtd_theme
 sphinx-gallery
-allensdk==0.16.3
-tables==3.5.2
+Glymur==0.8.19  # required for allensdk 1.3.0 to work
+allensdk==1.3.0
 -r requirements.txt

tox.ini

@@ -80,18 +80,11 @@ deps =
 commands =
     python test.py --example
 
-[testenv:gallery-py35]
-basepython = python3.5
-deps = {[testenv:gallery]deps}
-commands = {[testenv:gallery]commands}
-
-
 [testenv:gallery-py36]
 basepython = python3.6
 deps = {[testenv:gallery]deps}
 commands = {[testenv:gallery]commands}
 
-
 [testenv:gallery-py37]
 basepython = python3.7
 deps = {[testenv:gallery]deps}